Agent Gates

Runtime quality gates for AI coding agents. One install gives your team TDD enforcement, cross-review evidence checks, memory persistence reminders, and progress tracking — across Claude Code, OpenCode, and Codex.

📖 中文整体说明（问题、架构、与 agent-superpowers / OpenSpec 的关系、使用方式、含 mermaid 图）：docs/explainer.zh.md

Architecture

agent-gates/
├── lib/hetero/                      # v2.0.0 hetero-check subsystem
│   ├── config.sh                    # Config loader (env > json > legacy > default)
│   ├── select.sh                    # Model selection + effort + risk grading
│   ├── dispatch.sh                  # 5-channel dispatch + process-group spawn + fail-closed
│   ├── serve.sh                     # Shared opencode serve + .draining lock
│   └── janitor.sh                   # Lifecycle: measure + budget + recycle + circuit-breaker
├── skills/                          # Agent skills (auto-loaded by platforms)
│   ├── agent-workflow-rules/        # TDD, plan review, verification, anti-loop
│   ├── agent-review-protocol/       # Three-Agent Review, cross-check pipeline
│   ├── init-project-gates/          # Project initializer (one-time setup)
│   ├── init-deep-fallback/          # Cross-platform AGENTS.md hierarchy fallback (v1.5.2+)
│   └── memory/                      # Memory skill, bundled from clawic/skills (MIT, v1.5.4+)
├── hooks/
│   ├── git/
│   │   └── agent-quality-gate.sh    # Pre-commit: CHECK 1-6 (test + review + verifier)
│   └── platform/
│       └── memory-reminder.mjs      # PostToolUse: Memory persistence enforcement
├── templates/
│   ├── verifier.md                  # v2.0.0 Verifier custom agent config
│   └── .agent/                      # Project directory template
├── bin/
│   ├── agent-gates-verify-ack       # v2.0.0 USER_ACK writer (diff-hash bound)
│   ├── agent-gates-verify-strip     # v2.0.0 Strip USER_ACK from agent output
│   ├── agent-gates-config-migrate   # v2.0.0 Config v1→v2 migration
│   ├── oc-review                    # opencode cross-review with retry + fail-closed
│   └── oc-reaper                    # Clean orphaned opencode serve processes
└── install.sh                       # Multi-platform installer

Prerequisites（用户需要预先安装）

Things you must install before running ./install.sh:

Tool	Required / Optional	Purpose
Node.js ≥ 18	Required	Runs `memory-reminder.mjs` (ES modules + `node:fs`)
`git` or `curl`	Required	Installer fetches this repo; auto-install of upstream skills uses `git clone`
`jq`	Strongly recommended	Merges agent-gates entries into platform `hooks.json`; without it the installer prints manual JSON instructions
At least one agent platform	Recommended	Claude Code / OpenCode / Codex / cc-switch — installer auto-detects and falls back to `~/.claude/skills/` if none present
`npm` (ships with Node.js)	Optional	Only needed if you want the installer to auto-install the OpenSpec CLI

Install path constraint: $HOME must not contain spaces — shell hooks cannot reliably escape such paths.

Auto-Installed Dependencies（agent-gates 默认帮你装，v1.5.2+）

Running ./install.sh automatically performs the following (each step is skipped if already present):

Dependency	Default behavior	Source	Why it matters
agent-gates own 4 skills `agent-workflow-rules` / `init-project-gates` / `agent-review-protocol` / `init-deep-fallback` (new in v1.5.2)	Copied into the detected platform skills directory	This repo	Core workflow rules
Memory skill	Bundled in agent-gates repo since v1.5.4 — `skills/memory/` ships with this repo and is copied directly to the platform skills directory at install time. Skipped if already present. No network dependency.	Forked from clawic/skills (MIT) — see `skills/memory/UPSTREAM.md` for sync notes	`memory-reminder.mjs` hook prompts the agent to call this skill for session persistence
agent-superpowers 14-skill suite (test-driven-development / brainstorming / verification-before-completion / writing-plans / executing-plans + 9 supporting skills)	Full clone of the upstream repo into the platform skills dir	obra/superpowers	`agent-workflow-rules` TDD / plan / review / debug rules depend on these upstream skills
OpenSpec CLI (optional)	Interactive y/N prompt, defaults to N; runs `npm install -g @openspec/cli` only on explicit consent	@openspec/cli	Required for Path A (OpenSpec-driven team projects)
Platform hook registration	Writes PostToolUse entries into `~/.claude/settings.json` / `~/.config/opencode/hooks.json` / `~/.codex/hooks.json` for any detected platform	install.sh built-in	`memory-reminder.mjs` fires when a todo completes

Opt-out: ./install.sh --skip-deps skips all external dependencies — agent-gates' own skills and platform hooks still install. Without these dependencies agent-gates still runs — Path B (TDD only, no OpenSpec / no BDD) is the default and doctor.sh reports missing pieces as informational note, not FAIL.

Installation

One-line install (recommended):

curl -fsSL https://raw.githubusercontent.com/mcdowell8023/agent-gates/main/install.sh | bash

Or clone and run:

git clone https://github.com/mcdowell8023/agent-gates.git
cd agent-gates
./install.sh

Optional flags:

--skip-deps — Don't install external skill dependencies (Memory / Superpowers / OpenSpec)
--with-openspec — Detect-only check for OpenSpec CLI (no auto-install); mutually exclusive with the default y/N prompt
--codegraph-hook — Also register a zsh chpwd hook that runs codegraph init -i when entering a git repo
--skip-hooks — Skip platform hook registration
--upgrade / --force — Reinstall even when versions match

Upgrade:

./install.sh --upgrade

Uninstall:

./uninstall.sh

Usage

Initialize a project

Inside your project directory, in an agent platform session, say:

初始化项目

or in English:

init project gates

The init-project-gates skill will automatically:

Detect the project type (Path A: contains OpenSpec / Path B: no OpenSpec)
Install agent-quality-gate.sh into .githooks/
Run git config core.hooksPath .githooks
Create .agent/PROGRESS.md
Generate AGENTS.md (hierarchy depends on available tools — see the step 6 decision tree)
Inject project-level rules into CLAUDE.md

Daily use

While the agent works inside a session, agent-gates automatically:

After each completed todo: memory-reminder.mjs prompts the agent to save state via the Memory skill
Before each commit: agent-quality-gate.sh checks test correspondence / cross-review evidence / OpenSpec change / .feature files
Skill loading: agent-workflow-rules / agent-review-protocol / init-deep-fallback are triggered as needed

Health check

~/.agent-gates/doctor.sh           # Full check
~/.agent-gates/doctor.sh --quiet   # PASS/WARN/FAIL summary only
~/.agent-gates/doctor.sh --no-network  # Offline mode, skip remote version comparison

What's New

v2.0.0 — hetero-check subsystem + Verifier role (BREAKING)

Breaking: lib/review-selection.sh → lib/hetero/select.sh (shim kept for one minor); review-capability.json → hetero-check.json (agent-gates-config-migrate auto-converts).

hetero-check subsystem (lib/hetero/): Named, structured subsystem for heterogeneous quality checks — previously scattered across oc-serve, D6 doctor, Gate 2b, and reaper.

5-channel dispatch: Paseo → opencode (fail-closed) → codex → codebuddy → claude-agent, with automatic effort injection (--variant/--thinking/-c model_reasoning_effort) and risk-based grading (is_high_risk_path shared helper).
Resource lifecycle layer: Process-group spawn (setsid/perl POSIX::setsid(), macOS compatible) + PGID kill (NOT pkill -P) + .draining TOCTOU lock + wall-clock watcher + circuit-breaker with cold-start detection + HETERO_SPAWNED attribution. Prevents recurrence of two real OOM incidents (opencode serve stacking 2.7GB; codebuddy --acp crash-loop 12.5GB).
Config: hetero-check.json with lifecycle budgets, effort tiers, channel toggles — all overridable via env vars.

Verifier role: Black-box product verification after Writer + Reviewer pass.

templates/verifier.md: Claude Code custom agent config — runs the product from user perspective, reports issues, never modifies code.
CHECK 6 in pre-commit gate: Four-state verdict (PASS / FAIL / QUESTIONS / INCOMPLETE). FAIL blocks; QUESTIONS/INCOMPLETE require USER_ACK (human confirmation via agent-gates-verify-ack, bound to staged-diff-hash + HEAD). High-risk paths require FULL capability (Paseo agent); EVIDENCE_ONLY (opencode single-shot) is downgraded to INCOMPLETE for high-risk.
bin/agent-gates-verify-ack: Writes .ack file after human confirmation, with AGENT_MODE guard.
bin/agent-gates-verify-strip: Strips USER_ACK markers from agent output (defense-in-depth).
.agent/verify/ directory: Isolated from .agent/reviews/ to prevent CHECK 5/6 cross-contamination.

Migration: bin/agent-gates-config-migrate converts v1 → v2 config. Old paths have deprecation shims. install.sh auto-runs migration on first upgrade.

v1.9.0 — Global upgrade (per-project gates auto-upgrade)

The per-project gate is now a thin shim that delegates to the global authority, so install.sh --upgrade upgrades every project at once — no more re-running init project gates in each repo on every release.

hooks/git/gate-shim.sh: each project's .githooks/agent-quality-gate.sh is ~10 lines that exec the global gate (~/.agent-gates/hooks/git/agent-quality-gate.sh). If agent-gates isn't installed, the shim does NOT block commits (consistent with the AGENT_MODE=1 "humans pass through" design).
agent-gates-migrate: scan project root(s) and bulk-migrate old frozen-copy gates to the shim (default dry-run; --apply to act).
agent-gates-version: show the global gate version (= what every shim'd project runs); pass project roots to list per-project shim/stale status.

v1.8.0 — opencode cross-review reliability

oc-review: wraps opencode run with retry-on-empty (opencode intermittently exits 0 with empty output); on persistent failure exits 75 so the caller falls back to codex.
oc-reaper: cleans orphaned opencode serve processes (default dry-run; --apply).
doctor.sh → check_opencode_health surfaces leaked serves.

v1.7.0 — heterogeneous-review enforcement

Gate 2b: on a machine that supports heterogeneous review (L1+), a same-model or unmarked review is blocked — the review file must carry  proving a different model was used. (Catches "Opus reviewing Opus" self-approval.) SKIP_HETERO_CHECK=1 escape hatch.

v1.6.0 — cross-review capability detection + platform-adaptive routing

Capability levels (L0--L3) persisted in ~/.agent-gates/review-capability.json; platform-adaptive routing (§8) waterfall (opencode → codex → OMC plugin → Paseo → agent-tool); review prompt templates (§9); CI/Windows/WSL/container detection.

What's Included

Skills

Skill	Purpose	Activation
`init-project-gates`	Project setup: hook + `.agent/` dir + AGENTS.md	Manual: "init project"
`agent-workflow-rules`	TDD, plan review, verification, debugging	Auto-loads on code tasks
`agent-review-protocol`	Three-Agent Review pipeline, cross-check, platform-adaptive review routing (§8), review prompt templates (§9)	During review phases
`init-deep-fallback`	Cross-platform AGENTS.md hierarchy fallback (bundled v1.5.2+)	Invoked by `init-project-gates` Step 6 when no OMC/OMO tools available
`memory`	Infinite organized memory (bundled v1.5.4+)	Auto-loaded when `memory-reminder` hook fires

Hooks

Hook	Type	Trigger	Enforcement
`agent-quality-gate.sh`	Git pre-commit	Agent commits (`AGENT_MODE=1`)	Test files + review evidence + heterogeneous-review (Gate 2b)
`memory-reminder.mjs`	Platform PostToolUse	Todo completed / ≥3 plan-time todos	Memory save reminder + parallelism reminder
`gate-shim.sh`	Per-project hook source	Installed into `.githooks/`	Delegates to the global authority gate (v1.9.0+)

Commands (`~/.agent-gates/bin/`)

Command	Purpose
`oc-review run -m <model> --dir <wd> "<prompt>"`	opencode cross-review with retry-on-empty + fail-closed (no bare run)
`oc-reaper [--apply]`	clean orphaned `opencode serve` processes (PGID kill, default dry-run)
`agent-gates-verify-ack <run_id> [reason]`	Write USER_ACK for a verify run after human confirmation (v2.0.0)
`agent-gates-verify-strip`	Pipe filter: strip USER_ACK markers from verifier output (v2.0.0)
`agent-gates-config-migrate`	Migrate v1 `review-capability.json` → v2 `hetero-check.json` (v2.0.0)
`agent-gates-migrate [--apply] <root>...`	bulk-migrate old per-project gates to the v1.9.0 shim
`agent-gates-version [<root>...]`	show the global gate version; list per-project shim/stale status

Convention: `.agent/` Directory

.agent/
├── PROGRESS.md      # Sprint tracking, decisions, blockers (git tracked)
├── GATES.md         # Quality gates checklist (git tracked)
├── reviews/         # Cross-review evidence files (git tracked, CHECK 5)
├── verify/          # Verifier evidence + dispatch artifacts + .ack (v2.0.0, CHECK 6)
├── plans/           # Implementation plans (git tracked)
└── memory/          # Session memory (.gitignored)

Supported Platforms

Platform	Skills Location	Hook Registration	Schema
Claude Code (OMC)	`~/.claude/skills/`	`~/.claude/settings.json` → `.hooks.PostToolUse[]`	requires existing `settings.json` (start Claude Code once first)
Claude Code + OMO	`~/.config/opencode/skills/` (priority), `~/.claude/skills/` (fallback)	covered by OMC registration above — OMO reads `~/.claude/settings.json` PostToolUse hooks when running on Claude Code	same as OMC
OpenCode (OMO native)	`~/.config/opencode/skills/`	v1.5.2 auto-registers to `~/.config/opencode/hooks.json` `.hooks.PostToolUse[]` (reuses OMC/OMX `register_hook` jq logic)	nested schema (same shape as OMC/OMX)
Codex (OMX)	`~/.codex/skills/`	`~/.codex/hooks.json` → `.hooks.PostToolUse[]`	nested schema, installer creates file if missing
cc-switch	`~/.cc-switch/skills/` + symlinks	combines OMC + OMX above	—

The PostToolUse matcher used by the installer is TodoWrite|todowrite|TaskUpdate|TaskCreate to cover both the legacy TodoWrite tool name and Claude Code's current TaskUpdate / TaskCreate tools.

OMO on Claude Code: oh-my-openagent (OMO) is cross-platform — it runs on Claude Code, OpenCode, Codex, and more. When OMO runs on Claude Code, it reads ~/.claude/settings.json for PostToolUse hooks, so agent-gates' existing OMC registration already covers this scenario. OMO's own lifecycle hooks coexist with Claude Code native hooks. Skills are resolved dual-source: ~/.config/opencode/skills/ first, then ~/.claude/skills/.

How It Works

Git Quality Gate (agent-only)

The pre-commit hook ONLY fires for agent sessions (AGENT_MODE=1). Human developers pass through freely.

CHECK 1 — OpenSpec Change (Path A only): openspec/changes/ must contain an active change directory.

CHECK 2 — BDD Scenarios (Path A only): New source files require at least one features/*.feature file.

Gate 1 — Test Correspondence: Every new source file must have a corresponding test file.

Gate 2 — Cross-Review Evidence: When commits exceed threshold (LOGIC_FILES > 1 AND DIFF > 50 OR SINGLE_FILE > 150 lines), requires a review file in .agent/reviews/ with VERDICT: PASS.

CHECK 6 — Verifier Evidence (v2.0.0): Same threshold as Gate 2, plus high-risk path detection. Requires .agent/verify/*.md with VERIFY_VERDICT. PASS → proceed; FAIL → block (fix first); QUESTIONS/INCOMPLETE → requires USER_ACK: PROCEED in .ack file (human confirmation, diff-hash bound). High-risk + EVIDENCE_ONLY capability → forced INCOMPLETE (must use FULL black-box channel). SKIP_VERIFY=1 bypass for emergencies.

Memory Persistence Reminder

When an agent marks a todo as completed, the platform hook injects a system reminder to save key outputs via Memory skill — preventing session knowledge loss (红线 #12 enforcement).

Workflow Rules (Runtime)

TDD-first: write failing test → implement → verify
Plan review gates: get review before large implementations
Anti-loop: max 2 fix attempts before escalation
Verification-before-completion: evidence before claims

Workflow Paths: A (OpenSpec) vs B (no OpenSpec)

Agent Gates supports two workflow paths, auto-detected per project:

	Path A (team project)	Path B (individual / no OpenSpec)
Trigger	`.opencode/skills/openspec-propose/` or `.claude/skills/openspec-propose/` or `openspec/changes/` present	Otherwise
Planning	`opsx:explore` → `opsx:propose` (generates `proposal.md` + `specs.md` + `tasks.md`)	`brainstorming` skill → `writing-plans` skill
Acceptance	`features/*.feature` (Gherkin) referenced from `specs.md`; each `tasks.md` step links a scenario	Plan steps tagged RED / GREEN / REFACTOR
Implementation	`opsx:apply` (BDD-TDD: step-defs first)	`test-driven-development` skill
Pre-commit gate	4-CHECK (OpenSpec change + `.feature` + test correspondence + test pass) under `AGENT_MODE=1`	Test correspondence + cross-review evidence under `AGENT_MODE=1`
Review	Spec Reviewer → Quality Reviewer → CLI gate → `opsx:archive`	Cross-review evidence in `.agent/reviews/`

Both paths share the same agent-workflow-rules skill as the canonical source of TDD, plan-review, verification, and anti-loop rules. Path A layers OpenSpec (L1 requirements) and BDD (L2 acceptance) on top; Path B uses TDD alone.

doctor.sh reports which path applies for the current working directory (check_openspec_install + check_bdd_features_dir).

BDD Quick Start (Path A)

If your project uses OpenSpec (openspec/changes/ exists), the quality gate enforces BDD scenarios:

Create a .feature file in features/:

Feature: User registration

  Scenario: Register with valid email
    Given an unregistered email "new@example.com"
    When the user submits a registration request
    Then the system returns 201
    And the response contains a user ID

Write step definitions in features/step_definitions/:

// features/step_definitions/user-registration.steps.ts
import { Given, When, Then } from "@cucumber/cucumber";

Given("an unregistered email {string}", function (email: string) {
  this.email = email;
});

When("the user submits a registration request", async function () {
  this.response = await register(this.email);
});

Then("the system returns {int}", function (status: number) {
  expect(this.response.status).toBe(status);
});

Commit with AGENT_MODE=1 — the gate validates:
- CHECK 1: active openspec/changes/<name>/ directory exists
- CHECK 2: at least one features/*.feature file exists when adding source files
- Gate 1: test file correspondence (unchanged)
- Gate 2: cross-review evidence (unchanged)

Templates for TypeScript, Python, and Java are bundled in templates/features/.

OpenSpec Integration

When installing with --with-openspec, the installer checks for the OpenSpec CLI:

./install.sh --with-openspec

This verifies openspec is available on PATH and reports install instructions if missing. Since v1.5.2, the default ./install.sh flow already prompts (y/N) to run npm install -g @openspec/cli when the CLI is absent — --with-openspec remains supported for explicit declaration. Pass --skip-deps to suppress the prompt entirely.

Once OpenSpec is set up in your project, the workflow becomes:

opsx:explore → opsx:propose (generates specs + .feature) → plan-review
  → opsx:apply (BDD-TDD: step-defs first) → cross-review → opsx:archive

See agent-workflow-rules §3 (Path A) and §5 (OpenSpec Workflow) for the full flow.

Upgrade

Re-run the installer; the same command handles first install and upgrade:

curl -fsSL https://raw.githubusercontent.com/mcdowell8023/agent-gates/main/install.sh | bash

What the installer does on upgrade:

Compares the installed .version against the repo's; skips when they match (use --force or --upgrade to re-install anyway).
Backs up locally-modified SKILL.md files as SKILL.md.bak.<timestamp> before overwriting, and lists them in the final summary.
Idempotent hook registration: existing hooks.json is merged via jq without duplicates. If jq is missing, the installer prints the command to install it and the manual JSON entry to add.

Per-project gates auto-upgrade (v1.9.0+)

Since v1.9.0 the per-project .githooks/agent-quality-gate.sh is a thin shim that delegates to the global authority gate. So upgrading agent-gates globally upgrades every shim'd project at once — no per-project re-init needed. Verify with agent-gates-version <project-root>.

Migrating pre-v1.9.0 projects (one-time): projects initialized before v1.9.0 still carry a frozen full-copy gate (it won't auto-upgrade). Migrate them in one shot:

~/.agent-gates/bin/agent-gates-migrate <your-project-root>          # dry-run: list stale projects
~/.agent-gates/bin/agent-gates-migrate --apply <your-project-root>  # swap them to the shim

After migration, review + commit the .githooks/agent-quality-gate.sh change in each repo. From then on they auto-upgrade.

One-command upgrade + migrate (paste this to your agent)

Don't want to run the steps yourself? Paste the block below to your coding agent. The installer is idempotent — it installs if agent-gates is missing, upgrades if it's already there — then every initialized project is migrated to the auto-following shim.

Task: Install or upgrade agent-gates on this machine, then migrate all initialized projects to the v1.9.0 shim so they auto-follow future upgrades. Follow agent-gates discipline — never use --no-verify.

Project roots (fill in before sending, space-separated): ROOTS="$HOME/Projects $HOME/wb/projects". If unsure, ask me which roots to scan.

Install-or-upgrade (one command does both — installs if missing, upgrades if present): curl -fsSL https://raw.githubusercontent.com/mcdowell8023/agent-gates/main/install.sh | bash. Then confirm with cat ~/.agent-gates/.version and ~/.agent-gates/bin/agent-gates-version. (No curl? git clone https://github.com/mcdowell8023/agent-gates && cd agent-gates && ./install.sh.)

Scan gate status, read-only: ~/.agent-gates/bin/agent-gates-version $ROOTS. [shim → vX] = already auto-following; [STALE …] = old full-copy or unrecognized hook (step 3 will sort out which).

Dry-run the migration (touches nothing): ~/.agent-gates/bin/agent-gates-migrate $ROOTS. Only recognizable agent-gates gates are migrated; custom same-named hooks are skipped and reported as unknown. Eyeball the list.

Apply: ~/.agent-gates/bin/agent-gates-migrate --apply $ROOTS

The migration rewrites each repo's .githooks/agent-quality-gate.sh (effective on disk immediately). Do NOT push. Report which repos now have an uncommitted .githooks change so I can review + commit per each repo's own rules.

Report: the global version, which projects were migrated, and anything still STALE or unknown-skipped.

After this, every migrated project auto-follows future upgrades — next time you only run step 1.

Other upgrade notes

Backups accumulate. Each upgrade that detects user changes leaves a new SKILL.md.bak.* file. Run ./uninstall.sh --purge-backups (combined with --keep-skills if you only want to clean backups) to remove them after merging your edits.
OMO native (OpenCode) hook registration is manual. When the installer detects ~/.config/opencode/, it prints the JSON entry to add under ~/.config/opencode/hooks.json .hooks.PostToolUse[]. doctor.sh checks the same path/schema; if it reports the OMO hook as missing, add the entry by hand (see docs/platform-hooks.md → OMO for the full JSON shape). Note: if you run OMO on Claude Code (not on OpenCode), the OMC settings.json registration already covers you — no manual step needed.
No automatic skill migration. If a future version renames or restructures a skill directory, you may need to manually clean up the old layout — the installer only updates known skill names.

Doctor

After install, run ~/.agent-gates/doctor.sh (or ./doctor.sh from the repo) to verify deployment health:

~/.agent-gates/doctor.sh

Sample output (ideal Path A: OpenSpec installed + ≥1 .feature + clean transcripts + heterogeneous review tools):

✓ node v26.0.0
✓ jq jq-1.8.1
✓ Memory skill detected: ~/.cc-switch/skills/memory-1.0.2
✓ Superpowers skills detected (5/5)
✓ installed version: 1.6.0
✓ up to date with remote (1.6.0)
✓ memory-reminder.mjs present
✓ agent-quality-gate.sh present (executable)
✓ OMC settings.json hook registered (matcher contains TaskUpdate)
✓ OMO hooks.json hook registered
✓ OMX hooks.json hook registered
✓ hook output schema valid (hookEventName=PostToolUse, reminder included)
✓ no memory-reminder hook errors in last-7d transcripts
✓ OpenSpec installed in current project (Path A applies)
✓ BDD features/ has 3 .feature file(s)
✓ BDD step_definitions/ has 3 step file(s)
✓ Cross-review capability: L3 (opencode + codex)

17 pass · 0 warn · 0 fail

In a default Path B project (no OpenSpec, no features/) the OpenSpec/BDD lines become informational notes instead of PASS, and the cross-review capability check reflects whatever tools are installed (L0 becomes a WARN, L1+ is PASS). A typical output with cross-review tools but no OpenSpec is 14 PASS + 1 WARN/PASS + 3 note. note means "not applicable / not configured", not "broken".

Exit code is 0 if no FAIL (WARN allowed), 1 if any FAIL, so the script is CI-friendly:

~/.agent-gates/doctor.sh --quiet --no-network && echo "deployment OK"

Flag	Effect
`--quiet`	Suppress dim/info notes; show only the PASS/WARN/FAIL table
`--no-network`	Skip the remote `.version` check (offline mode)
`--help`	Usage

Doctor checks the same surface as the install/uninstall scripts (paths, registrations, schema). If a check FAILs, the message includes a one-line fix hint pointing back to install.sh or this README's Troubleshooting section.

Troubleshooting

Symptom	Likely cause	Fix
`node not found`	Node.js missing or not in PATH	Install Node.js ≥18: https://nodejs.org/
`node ≥18 required (found vXX)`	Old Node version	Upgrade Node (e.g. `nvm install 20`, or your package manager)
`jq not found for safe merge`	`jq` missing while `hooks.json` already exists	Run the install command the installer prints (`brew install jq` / `apt-get install jq` / etc.) and re-run
`Install path contains spaces`	`$HOME` contains a space	Use a space-free home path; shell hooks cannot reliably escape it
`No memory* skill found` warning	No Memory skill installed	Install a memory skill in any of the printed candidate dirs; without one the reminders fire but have no target skill to call
Hook fires but nothing seems to happen	Memory skill missing, or agent ignored reminder	Verify Memory skill is installed; check agent platform actually executes `PostToolUse` hooks
Skill behavior unchanged after upgrade	Per-project hook was not refreshed	In the affected repo: re-run `init project gates`
`hooks.json` has duplicate entries	Manual edits combined with installer re-runs	`./uninstall.sh` then re-install for a clean state
Need to roll back a skill change	Looking for the previous SKILL.md	Check `SKILL.md.bak.<timestamp>` in the same skill directory

Relationship Between Components

init-project-gates          ─── sets up project ───►  .agent/ + hook
       │
       │ runtime companion
       ▼
agent-workflow-rules        ─── governs how agent works ───►  TDD / verification
       │
       ├── review enforcement
       │         ▼
       │   agent-review-protocol  ─── cross-check pipeline ───►  .agent/reviews/ (CHECK 5)
       │
       ├── verifier enforcement (v2.0.0)
       │         ▼
       │   hetero-check subsystem ─── dispatch + lifecycle ───►  .agent/verify/ (CHECK 6)
       │         │
       │         ├── dispatch (paseo/opencode/codex/codebuddy/claude)
       │         ├── janitor (measure/budget/recycle/circuit-breaker)
       │         └── verifier.md (black-box product verification)
       │
       │ persistence enforcement
       ▼
memory-reminder.mjs         ─── platform hook ───►  Memory skill save

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
bin		bin
data		data
docs		docs
hooks		hooks
lib		lib
skills		skills
templates		templates
tests		tests
.gitignore		.gitignore
.version		.version
CHANGELOG.md		CHANGELOG.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
doctor.sh		doctor.sh
install.sh		install.sh
uninstall.sh		uninstall.sh

Folders and files

Latest commit

History

Repository files navigation

Agent Gates

Architecture

Prerequisites（用户需要预先安装）

Auto-Installed Dependencies（agent-gates 默认帮你装，v1.5.2+）

Installation

Usage

Initialize a project

Daily use

Health check

What's New

v2.0.0 — hetero-check subsystem + Verifier role (BREAKING)

v1.9.0 — Global upgrade (per-project gates auto-upgrade)

v1.8.0 — opencode cross-review reliability

v1.7.0 — heterogeneous-review enforcement

v1.6.0 — cross-review capability detection + platform-adaptive routing

What's Included

Skills

Hooks

Commands (~/.agent-gates/bin/)

Convention: .agent/ Directory

Supported Platforms

How It Works

Git Quality Gate (agent-only)

Memory Persistence Reminder

Workflow Rules (Runtime)

Workflow Paths: A (OpenSpec) vs B (no OpenSpec)

BDD Quick Start (Path A)

OpenSpec Integration

Upgrade

Per-project gates auto-upgrade (v1.9.0+)

One-command upgrade + migrate (paste this to your agent)

Other upgrade notes

Doctor

Troubleshooting

Relationship Between Components

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Commands (`~/.agent-gates/bin/`)

Convention: `.agent/` Directory

Packages