ai-agent-manager
vikashruhilgit/ai-agent-manager
A Claude Code plugin for AI agents to collaborate on software projects. 13 specialized agents (Launch Pad, Supervisor v4, Execute Manager, Context-Keeper, Worker, Plan Reviewer, Rubric Grader, Product Owner, Orchestrator, Code Reviewer, Red Team Reviewer, Dual-agent QA automation).
Instalação
npx convez-ai vikashruhilgit/ai-agent-manager1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
AI Agent Manager
A Claude Code plugin for AI agents to collaborate on software projects. 14 specialized agents (Launch Pad, Supervisor v4, Execute Manager, Context-Keeper, Worker, Plan Reviewer, Rubric Grader, Product Owner, Orchestrator, Code Reviewer, Red Team Reviewer, Review-PR, QA Strategist, QA Executor) and the /commit skill automate plan-first readiness, parallel workflow execution, requirements, planning, review, commits, adversarial audits, standalone PR review-and-heal, and dual-agent QA automation.
Key Idea: Your projects need only a CLAUDE.md file for codebase knowledge. The Supervisor uses .supervisor/ for state management. Orchestrator and Product Owner can optionally use Beads issue tracker. Repeatable across any project.
Install the plugin and run slash commands instead of manually managing agents.
NEW in v14.13.0 — Clickable desktop notifications (opt-in, macOS): Install
terminal-notifier(brew install terminal-notifier) and the pause-event banner becomes clickable — clicking brings the Claude desktop app to the foreground (default). SetAI_AGENT_MANAGER_NOTIFY_CLICK=resumeto instead deep-link to the exact session viaclaude://…/resume— works on older macOS, but on macOS 26terminal-notifier's click callback can't fire, soactivate(focus the app) is the reliable default. Withoutterminal-notifierthe existingosascriptbanner is unchanged — zero regression. Click logic lives in a self-tested pure helper (scripts/notify-click-target.sh, 15 cases incl. injection-safety). No new agent / command / skill / hook (still 13 / 15 / 50 / 19), no schema change.NEW in v14.10.0 — System Twin foundation slice (advisory, propose-only): One thin, additive, reversible vertical that exercises all three System Twin pillars on the plugin's own repo while staying advisory and strictly subordinate to
CLAUDE.md. A.supervisor/twin/per-subsystem System Contract store is written only by the repo-root sole writerscripts/write-system-contract.sh(worktree-guard + hash-chained provenance + atomic; read viaread-system-contract.sh; self-tested). Predict: Launch Pad reads the contract's dependency graph for advisory blast-radius prediction (graceful fallback when absent). Prove: Supervisor Phase 4.5 runs an advisory contract-conformance check on the integrated diff plus a deterministic benchmark, then an ephemeral builder writes contracts from the pinned repo-root CWD and emits a hard signal toSUPERVISOR_RESULT+ the session JSONL. Compound:/insightssurfaces the conformance/benchmark trend,/dreamingreads contract drift, and the rubric-grader reports the signal as advisory lines that never gate. Propose-only, no self-applied writes without the existing human gate — no new agent/command/skill/hook (still 13 / 14 / 50 / 19).NEW in v14.9.0 —
/capability-check --strategy: product-direction strategist:--strategyturns/capability-checkfrom a pure platform-adoption diff into a grounded product-evolution pass that proposes scored, deduped, differentiated product directions (reusing the brainstorming skill), each grounded in a real product asset plus a newly-feasible enabler or an explicit drop. Default (no-flag) behavior is unchanged; the mode is propose-only, bounded, and human-gated — no new command/agent/skill/hook (still 13 / 14 / 50 / 19).NEW in v14.3.0 — Advisory project memory (P2b): Agent-writable, cross-session project memory under
.supervisor/memory/so the plugin stops re-discovering your codebase each run. Built behind guardrails: a sole writer (scripts/write-project-memory.sh) that refuses git-worktree CWDs + hash-chains provenance + caps at 200 lines, and a read-side gate (scripts/read-project-memory.sh) that emits only chain-verified entries (poisoned lines dropped). Memory is advisory, subordinate toCLAUDE.md, human-gated — Launch Pad reads it during analysis and proposes new facts for your approval. Launch-Pad-only in v1; no new agent/skill/command/hook (still 19 hooks).NEW in v14.2.2 — Notification polish (patch):
notify-desktop.shnow debounces rapid notification bursts into a single banner (AI_AGENT_MANAGER_NOTIFY_DEBOUNCE, default 5s) and detects the display on Linux (skipsnotify-sendon headless)./autonomous --notifyfails loud if no webhook URL is resolvable (env var or.supervisor/notify-config.json) instead of silently doing nothing. No hook/schema/agent change (still 19 hooks).NEW in v14.2.1 — Webhook + telemetry result-extraction fix (patch): The supervisor-completion webhook (
send-webhook.sh) and the opt-in telemetry post (send-telemetry-core.sh) read the finishing agent's output from the realSubagentStoppayload field —last_assistant_message(with the legacyresult_block/output/agent_outputnames and theagent_transcript_path/transcript_pathJSONL as fallbacks) — instead of a top-levelresult_blockfield that Claude Code never actually sends. The pre-fix readers resolved to empty and silently suppressed every supervisor-completion webhook and telemetry issue since v14.1.0. No hook-count (still 19), schema, agent, command, or skill change. Seeai-agent-manager-plugin/docs/TELEMETRY.md§"Result-text extraction".NEW in v14.0.0 — Continuous autonomous mode with stacked PRs:
/autonomousflips to multi-iteration by default (cap 10, default--max-iterations 3) with stacked-branch semantics — iteration N+1 branches fromiterations[N].branch, producing a reviewable PR stack. Out-of-order merge hazard: reviewers MUST merge the bottom of the stack first (followAUTONOMOUS_RUN.iterations[]order). Restore v13 cadence with--no-stacked-branches; reproduce v13's single-iteration default with--max-iterations 1. New flags:--notify(opt-in gate-event webhooks for rubric / adjudication / NO-GO / Plan Review FAIL × 3, gated onAI_AGENT_MANAGER_WEBHOOK_URL, jq-only payload construction for injection safety, fire-and-forget POST) and--non-interactive-fallback(per-gate fail-closed policy for CI / stdin-not-tty: rubric gate aborts, no-rubriccompletedreturnsdone, adjudication inherits Supervisor's--non-interactivepolicy when forwarded). Supervisor gains--base-branch <ref>+--non-interactive+ Phase 0/4/4.5 base-mismatch detection + cleanup, and emits optional additivebranch_base+pr_statefields onSUPERVISOR_RESULT(schema_version still 1, optional). Context-Keeper gains atomicset_flag/get_flag/clear_flagoperations writing under a new## Phase Flagssection instate.md.AUTONOMOUS_RUNbumps to schema_version 2 with nine new closedstatus_reasonvalues. W-NEW-3 spike PASSED pre-merge: Code Reviewer + Rubric Grader both honorDIFF-SCOPE OVERRIDEinline directives on stacked-branch fixtures. v14 is additive on top of v13: no new agent, no hook count change in v14.0.0 (still 14). v14.1.0 adds desktop + webhook pause notifications (PreToolUse[AskUserQuestion]+Notificationhooks), bringing the hook count 14 → 17 — see "Enabling notifications" below. v14.2.0 adds the concurrency/resume layer — aLAUNCH_PAD_RESULTschema (sosaved_brief_pathbecomes the primary/autonomousbrief-detection signal, retiring the fragilels-diff) plus aSessionStartcrash/compact resume hook — bringing the count 17 → 19. All v13.0.0 / v13.0.1 capabilities preserved (foreground-assisted gates, rubric-gate user-merge verification, Option Cinter_subtask_gapre-plan, webhook empty-payload suppression). 14 agent roles, 17 slash commands, 53 skills, 19 quality gate hooks. All v12.2.0 capabilities preserved (Agent Teams graduation, Outcomes Rubric,/dreaming, opt-in SubagentStop webhook hook) and v12.1.0 documentation increments preserved.v12.1.0 (preserved): Documentation + skills increment — Memory Tool skill (Anthropic memory-tool pattern reference), "## Structured Outputs" section in
AGENT_GUIDELINES.mddocumenting both enforcement paths (output_config.formatfor direct API agents,SubagentStophooks for plugin agents), and the "## Advisor Tool (SDK-only pattern)" section noting theadvisor-tool-2026-03-01beta is reachable only via directclient.beta.messages.create(...)calls.v12.0.0 (preserved): Reliability primitives — inter-subtask
provides/requirescontracts, pre-spawn dependency verification gate, scope-expansion adjudication (4-option escalation), effort-tier discipline across the 10 execution-shaped agents (haiku context-keeper and discovery-only product-owner exempt), and hardened SubagentStop validation rejectingoutputs_gap/toolset_gapdrift. WORKER_RESULT schema bumped to v2.v7 baseline (preserved): Enhanced Code Reviewer (LSP diagnostics, read-only mode, issue categorization: new/pre_existing/nit), senior-grade QA (strict assertions, negative testing, CRUD lifecycle, data integrity probes, security boundary tests, missing functionality detection with
MISSING_FUNCTIONALITY_REPORT), session-based QA (--plan,--scope,--continue), Strategist assertion quality audit. Plus all v6 features: structured result schemas, failure escalation, merge safety gate, session logging, per-agent hooks, architecture contracts.
Quick Start
1. Install the Plugin
Local development (from a checkout of this repo):
/plugin marketplace add /path/to/ai-agent-manager
/plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace
The repo is a marketplace wrapper (/.claude-plugin/marketplace.json) with the plugin nested at ai-agent-manager-plugin/. The first command registers the marketplace, the second installs the plugin from it.
Once published to the official Anthropic marketplace, installation becomes a single /plugin install command without needing a local checkout.
2. Setup Your Project
cd /path/to/your-project
# Create CLAUDE.md with your project patterns
# (See CLAUDE.md Structure section below)
# Optional: Initialize Beads issue tracker (for Orchestrator/Product Owner)
bd init
This creates:
your-project/
├── CLAUDE.md # Codebase knowledge (you maintain)
├── .supervisor/ # Supervisor state (auto-created, gitignored)
│ ├── state.md # Current session state
│ ├── history/ # Completed session summaries
│ ├── jobs/ # Supervisor-Ready Briefs lifecycle
│ │ ├── pending/ # Launch Pad saves briefs here
│ │ ├── in-progress/ # Supervisor moves brief here on ACQUIRE
│ │ ├── done/ # Supervisor moves here on FINALIZE
│ │ └── failed/ # Supervisor moves here on failure
│ ├── logs/ # Structured JSONL session logs
│ └── worker-summaries/ # Worker summaries (inline mode)
├── .beads/ # Beads issue tracker (optional)
│ └── issues/
└── src/ (your code)
3. (Optional) Enable MySQL MCP
The plugin bundles a read-only MySQL MCP server that gives agents direct database access — schema inspection, query execution with impact analysis, and multi-DB profile switching.
Set your DB credentials as environment variables (add to ~/.zshrc or ~/.bashrc):
export DB_HOST=localhost
export DB_USER=myuser
export DB_PASS=mypassword
export DB_NAME=mydatabase
export DB_PORT=3306 # numeric string, defaults to 3306
Note: Running
exportin your terminal takes effect immediately in the current session only. When you close that terminal or open a new one, the variables are gone. To persist across sessions, add these lines to~/.zshrcor~/.bashrc:echo 'export DB_HOST=localhost' >> ~/.zshrc echo 'export DB_USER=myuser' >> ~/.zshrc echo 'export DB_PASS=mypassword' >> ~/.zshrc echo 'export DB_NAME=mydatabase' >> ~/.zshrc echo 'export DB_PORT=3306' >> ~/.zshrc source ~/.zshrc
The MCP server starts automatically via uvx when the plugin is loaded — no extra steps needed.
Multi-DB profiles (optional) — connect to multiple databases by setting:
export DB_PROFILES_MYSQL_PROD='{"host":"prod.example.com","user":"ro","pass":"secret","db":"myapp"}'
export DB_PROFILES_MYSQL_STAGING='{"host":"staging.example.com","user":"ro","pass":"secret","db":"myapp"}'
Then call switch_database(host="prod.example.com") at runtime to switch between them.
Security: Only
SELECTqueries are permitted. All write operations (INSERT,UPDATE,DELETE,DROP, etc.) are blocked.
4. Run Your First Command
# Plan-first autonomous workflow
/launch-pad goal: "what you want to accomplish"
/supervisor job: .supervisor/jobs/pending/{date}-{slug}.md
# Or run directly
/supervisor task: "what you want to accomplish"
# Or plan manually
/orchestrator goal: "what you want to accomplish"
# Or chain Launch Pad → Supervisor in one command (v14.0.0)
# Foreground-assisted automation: you stay at the terminal to answer
# in-session prompts (Phase 6 save, NO-GO, adjudication, etc.); the
# loop handles the chaining and the rubric-driven re-plan.
# Default is multi-iteration with stacked PRs (cap 10, default 3).
/autonomous "what you want to accomplish" # multi-iter default (3), stacked PRs
/autonomous "what you want to accomplish" --max-iterations 1 # reproduce v13's single-iter default
/autonomous "what you want to accomplish" --no-stacked-branches # v13-style: branch from integration base
/autonomous "what you want to accomplish" --notify # opt-in gate webhooks (AI_AGENT_MANAGER_WEBHOOK_URL)
/autonomous "what you want to accomplish" --non-interactive-fallback # CI / unattended: per-gate fail-closed policy
The 14 Agents
User-Facing Agents (9 + commit skill)
| Agent | Command | Purpose | When |
|---|---|---|---|
| Launch Pad | /launch-pad goal: "..." | Prepare goals for autonomous Supervisor execution with feasibility gate (Phase 2.5: GO/CAUTION/NO-GO) and mandatory Plan Review (Phase 5.5) | Before /supervisor, planning |
| Supervisor | /supervisor task: "..." | Autonomous workflow → Phase 1.5 PRE-FLIGHT SYNC (remote-overlap gate) → parallel workers → PR creation | Full automation |
| Product Owner | /product-owner feature: "..." | Define requirements → create user stories with acceptance criteria. Assumption Check (standard flow, user gate before bd create if flags) + Reality Check (brainstorm flow, VIABLE/NEEDS_FOUNDATION/BLOCKED with Feasibility score caps). Use --brainstorm for multi-mind ideation. | New feature, vague requirements, exploring directions |
| Orchestrator | /orchestrator goal: "..." | Plan work → create tasks with review gates | Starting implementation |
| Code Reviewer | /code-reviewer src/ | Review code → output PASS/FAIL/NEEDS_HUMAN | After writing code |
| Commit (skill) | /commit | Stage changes → create conventional commits | Ready to commit |
| Red Team Reviewer | /red-team-reviewer | Adversarial audit → find production failures | Pre-launch, security |
| QA Strategist | /qa-strategist src/ | Risk-based test strategy → coverage targets → assertion quality audit | Before QA, strategy planning |
| QA Executor | /qa-executor | Discover → generate strict tests → find missing functionality → QA_RESULT | Automated QA |
| Review-PR | /review-pr <pr-url> | Standalone review→fix→re-review loop against an existing PR; auto-heals the diff, never auto-merges → REVIEW_HEAL_RESULT | Review/heal any open PR |
Internal Agents (5)
| Agent | Spawned By | Purpose |
|---|---|---|
| Execute Manager | Supervisor (Phase 3) | Own poll loop, worker/reviewer lifecycle, Context-Keeper coordination |
| Context-Keeper | Supervisor / Execute Manager | Manage externalized state file (sole writer) |
| Worker | Execute Manager / Supervisor | Implement a single subtask in an isolated git worktree |
| Plan Reviewer | Launch Pad | Validate Supervisor-Ready Briefs before execution |
| Rubric Grader | Supervisor (Phase 4.5) | Read-only Haiku scorer for the optional Outcomes Rubric (advisory) |
Orchestration Shell: /autonomous (v14.0.0)
/autonomous is not a new agent — it is a slash command that chains the agents above. The command body (ai-agent-manager-plugin/commands/autonomous.md) is executed inline on the main thread: it reads commands/launch-pad.md and commands/supervisor.md at Step 0, then runs Launch Pad inline (which still Task-spawns plan-reviewer), then runs Supervisor inline (which still Task-spawns orchestrator / execute-manager / code-reviewer / rubric-grader). Default mode is multi-iteration (cap 10, default --max-iterations 3) with stacked PRs: iteration N+1 branches from iterations[N].branch. The loop re-plans on the same two existing SUPERVISOR_RESULT signals as v13 (rubric N<M with user-merge confirmation; failed + inter_subtask_gap from Option C adjudication). The protocol skill is at ai-agent-manager-plugin/skills/autonomous-loop/SKILL.md.
Stacked PR workflow (v14.0.0+)
The v14 default flips /autonomous from "run once, return" to a continuous loop that produces a stack of PRs, one per iteration:
- Branching: Iteration 1 branches from the integration base (typically
origin/main). Iteration N+1 branches fromiterations[N].branch— the previous iteration's feature branch — so each iteration builds on top of the prior unmerged work. This produces a reviewable bottom-up stack rather than divergent siblings. - Out-of-order merge hazard: Reviewers MUST merge the bottom of the stack first (the earliest iteration, listed first in
AUTONOMOUS_RUN.iterations[]). Merging a higher iteration before its base leaves the remaining higher iterations rebased against the wrong base and produces phantom conflicts. The autonomous-loop preservesiterations[N].branchin the run summary precisely so reviewers can walk the stack in order. Usegh pr list --base <iter-N-branch>to confirm dependencies. - Base-mismatch detection: Supervisor's Phase 0/4/4.5 base-mismatch detection (added in v14) catches the case where a stacked iteration is unintentionally run against the wrong base; it emits
branch_base+pr_stateonSUPERVISOR_RESULT(withpr_state: "closed_by_loop"when Phase 4.5 retired the wrong-base PR) and surfaces upward assupervisor_base_branch_mismatchonAUTONOMOUS_RUN.status_reason. - Opt-out (
--no-stacked-branches): Forces every iteration to branch from the integration base — restores v13's branch-from-base cadence. Use this when iterations are truly independent or when your review process can't handle stacks. Each iteration produces a standalone PR. - Single iteration (
--max-iterations 1): Reproduces v13's default behavior exactly — runs Launch Pad → Supervisor once and exits. Useful when you just want command chaining without re-planning. - AUTONOMOUS_RUN summary: Always lists
iterations[]withbranch,pr_url, andstatus/status_reasonper iteration. The schema (v2 in v14) is documented inai-agent-manager-plugin/docs/RESULT_SCHEMAS.md.
Running /autonomous in CI / unattended
/autonomous is designed as a foreground-assisted loop — most gates bubble AskUserQuestion in-session. For CI / cron / stdin-not-tty environments, opt in to a deterministic per-gate fail-closed policy:
--non-interactive-fallback— engage the per-gate policy. Without this flag, anAskUserQuestionon a closed stdin will hang or error; with it, each gate has a defined non-interactive outcome:- Rubric gate (rubric_score N<M, multi-iter only): aborts with
status_reason: rubric_gate_closed_non_interactive— the loop cannot verify a user merge, so it stops rather than guess. Inspect the PR manually and re-run if you want to continue. - No-rubric
completedrun: returnsdonewithstatus_reason: no_rubric_in_non_interactive— without a rubric there's nothing to evaluate, so the iteration is treated as terminal. - Adjudication gate (Supervisor's 4-option scope-expansion question): when
--non-interactive-fallbackis set on/autonomous, the loop auto-forwards--non-interactiveto the inlined/supervisor, so the adjudication gate (and Supervisor's Phase 4ghretry path) fail closed consistently with the loop's own policy. A single--non-interactive-fallbackon/autonomousis sufficient — you do NOT need to also pass--non-interactive. (Standalone/supervisorinvocations still accept--non-interactiveexplicitly; the forwarding only applies inside/autonomous.) - Launch Pad NO-GO override + Plan Review FAIL × 3: with
--non-interactive-fallbackengaged, these gates abort the autonomous run rather than prompt for an override — fail-closed by design.
- Rubric gate (rubric_score N<M, multi-iter only): aborts with
--notify+AI_AGENT_MANAGER_WEBHOOK_URL— opt in to gate-event webhooks for out-of-band notification. Each gate (rubric, adjudication, NO-GO, Plan Review FAIL × 3) emits a JSON event constructed withjq(no shell interpolation into the JSON payload, for injection safety). Fire-and-forget POST; failures are logged to the session log but don't abort the run. Combine with--non-interactive-fallbackfor an unattended run that still pings you when a gate triggers — useful for monitoring long-running CI loops.- Recommended CI shape:
claude /autonomous "..." --non-interactive-fallback --notify --max-iterations 3withAI_AGENT_MANAGER_WEBHOOK_URLset in the CI environment. The loop auto-forwards--non-interactiveto the inlined/supervisor, so you do not need to pass it separately. Examine the JSON sidecar at.supervisor/autonomous/{session_id}/AUTONOMOUS_RUN.jsonafter the run; thestatus_reasonwill tell you exactly which gate (if any) closed the loop.
See ai-agent-manager-plugin/skills/autonomous-loop/SKILL.md for the full state machine and per-status_reason recovery actions.
Enabling notifications (desktop + phone) — v14.1.0
The plugin surfaces a notification the moment a run pauses for you (Supervisor adjudication, /autonomous rubric gate, Plan Reviewer NEEDS_HUMAN, Launch Pad Phase 6, merge-and-continue) and on Claude Code's own permission_prompt / idle_prompt / elicitation_* events.
-
Desktop banners — work out of the box, no setup. macOS uses
osascript, Linux usesnotify-send. On the first macOS fire, grant your terminal (or "Script Editor") notification permission in System Settings → Notifications. Hard-disable withAI_AGENT_MANAGER_DESKTOP_NOTIFICATIONS=0. Windows (outside WSL) has no desktop banner yet — use the phone/webhook path below. -
Clickable desktop banners (macOS, opt-in) — click the banner to jump straight to Claude. The built-in
osascriptbanner can't carry a click action (clicking it just opens Script Editor), so installterminal-notifier(brew install terminal-notifier) — when present, the banner becomes clickable. Click behaviour is set byAI_AGENT_MANAGER_NOTIFY_CLICK:activate(default) — click brings the Claude desktop app to the foreground. Reliable on modern macOS (incl. macOS 26); for a single active session, focusing the app lands you back on it.resume— click opensclaude://claude.ai/resume?session=<id>to jump back to the exact session. ⚠️ Works only whereterminal-notifier's-openclick still fires (older macOS). On macOS 26 the click callback is dead (terminal-notifier2.0.0 relies on the deprecatedNSUserNotificationdelegate), so a clickedresumebanner won't navigate — useactivatethere. Theclaude://…/resumeroute itself is valid (reachable via a directopen), it just can't be triggered from a notification click on macOS 26.auto— focuses the app when you're already inside the desktop app; otherwise resumes. ⚠️ Its resume branch inherits the same macOS 26 click-callback caveat asresumeabove — so on macOS 26 a terminal/CLI session underautogets the dead-click behaviour; preferactivatethere.off— non-clickable banner (the pre-terminal-notifierbehaviour).
Notes: do not expect the Claude icon on the banner — impersonating Claude's bundle id (
-sender) is silently dropped by macOS 26, so the banner usesterminal-notifier's own icon. Theclaude://resume route is an undocumented desktop-app surface;resumealways degrades safely to focusing the app. Withoutterminal-notifierinstalled, everything behaves exactly as before (plainosascriptbanner). -
Phone / chat push — set a webhook URL one of two ways:
- export
AI_AGENT_MANAGER_WEBHOOK_URL=..., or - (more robust) create
.supervisor/notify-config.json→{"webhook_url":"https://ntfy.sh/your-topic"}. The hook reads this file directly, so it works even when an env var set only in~/.zshrcdoesn't propagate to the non-interactive hook shell. Make sure.supervisor/is in your project's.gitignore(it is by default once/supervisorhas run) so the URL is never committed. The path resolves relative to the directory Claude Code runs in, so launch from your repo root. - ntfy.sh URLs get a readable plain-text push (with
Title/Priority/Tags) automatically; Slack/Discord/custom endpoints get a JSON payload. Self-hosted ntfy: setAI_AGENT_MANAGER_WEBHOOK_FORMAT=ntfyto force the plain-text format.
- export
-
Test it without a real run:
AI_AGENT_MANAGER_WEBHOOK_DRY_RUN=1makessend-webhook.shprint the constructed payload instead of POSTing — use it to verify your URL/format before relying on it. -
Scope:
AI_AGENT_MANAGER_NOTIFY_SCOPE=plugin(default) only firesAskUserQuestionnotifications when a plugin run is detected;allfires on everyAskUserQuestionin any session. -
Bidirectional (answer from anywhere): the pause is a live, same-session wait — answering continues the run. To reply remotely (e.g. from your phone) so the session resumes without returning to the terminal, enable Claude Code Remote Control: the banner/push tells you to come back; Remote Control lets you answer.
-
Notification stderr (e.g. revoked permissions) is logged to
.supervisor/logs/notifications.log; webhook hooks always exit 0 (fire-and-forget).
Plan-First Autonomous Workflow
/launch-pad goal: "add user authentication"
↓
Supervisor-Ready Brief saved to .supervisor/jobs/pending/
↓
/supervisor job: .supervisor/jobs/pending/{date}-{slug}.md (fresh session)
↓
INIT → ACQUIRE → PRE-FLIGHT SYNC → PLAN → EXECUTE (via Execute Manager) → FINALIZE → SELF_HEAL → LOOP
↓
PR created, next task or exit
Autonomous Workflow (Supervisor v4)
/supervisor task: "add user authentication"
↓
INIT: Detect env → Ask preferences → Create .supervisor/
↓
ACQUIRE: Select task → Create feature branch (MANDATORY)
↓
PRE-FLIGHT SYNC: Fetch remote → scan recent commits + open PRs → classify
CLEAR / OVERLAP / SUPERSEDED (silent on CLEAR; soft-gate or
fail-closed on overlap; --skip-preflight-sync escape hatch)
↓
PLAN: Orchestrator → Subtasks → Parallelism analysis
↓
EXECUTE: → Execute Manager (isolated context, 60 tool call budget)
Worktree A ─→ Worker A ─→ Reviewer A ─→ PASS
Worktree C ─→ Worker C ─→ Reviewer C ─→ PASS
(unblocked) → Worktree B → Worker B → PASS
← EXECUTE_RESULT (merge_order, worktrees, branches)
↓
FINALIZE: Pre-merge validation → Commit in worktrees → Sequential merge → PR
↓
LOOP: Next task or exit
Manual Workflow
Product Owner → Create user stories (requirements)
↓
Orchestrator → Break into tasks (EPIC → TASK → SUBTASK)
↓
You code
↓
Code Reviewer → PASS/FAIL/NEEDS_HUMAN (review gate)
↓
You fix issues (if needed)
↓
/commit → Conventional commits
↓
Next task
QA Workflow
/qa-executor
↓
DETECT URL: playwright.config.ts → .env → ask user
↓
DISCOVER: Static analysis → Runtime crawl → Selective vision → Merge & gate
↓
STRATEGY: QA Strategist classifies routes (HIGH/MEDIUM/LOW risk)
↓
GENERATE: Strict tests (value assertions, negative tests, CRUD lifecycle,
data integrity probes, security boundary tests)
↓
GAP ANALYSIS: Missing functionality detection → MISSING_FUNCTIONALITY_REPORT
↓
EXECUTE: npx playwright test --reporter=json
↓
COVERAGE: Routes discovered vs tested, APIs discovered vs tested
↓
AUDIT: QA Strategist reviews results + assertion quality + gaps → STRATEGIST_VERDICT
↓
QA_RESULT: passed | failed | needs_human
MISSING_FUNCTIONALITY_REPORT: gaps found in the app
Requirements:
playwright.config.ts(or .js) must exist- App must be running at the base URL
npxavailable (Node.js installed)- Playwright browsers installed (
npx playwright install)
Quick commands:
/qa-executor # Full QA run (functional depth)
/qa-executor --skip-strategy # Skip Strategist, use defaults
/qa-executor --url http://localhost:3000 # Override URL
/qa-executor --depth smoke # Quick smoke tests only
/qa-executor --depth functional # Deep tests (default)
/qa-strategist src/ # Strategy only (no tests)
/qa-strategist --audit .qa-summary.md # Audit existing QA results
Session-Based QA (Large Apps)
For apps with many routes, use session-based QA to test in chunks:
# Step 1: Create a test plan (discovers all routes, groups into scopes)
/qa-executor --plan
# Step 2: Test one scope at a time
/qa-executor --scope auth # Test auth scope
/qa-executor --scope tournaments # Test tournaments scope
/qa-executor --scope billing # Test billing scope
# Step 3: Continue with next unfinished scope
/qa-executor --continue # Auto-picks next pending scope
# Step 4: Check cumulative coverage
# coverage.json tracks routes_tested/routes_total across sessions
How it works:
--planruns discovery and creates.qa-session/plan.jsonwith scopes sorted by risk priority--scope <name>tests only routes in that scope, updates.qa-session/coverage.json--continuepicks the nextpendingscope from the plan automatically- Coverage accumulates across sessions — no retesting already-covered routes
What the QA Agent Tests
Assertion strictness (all modes):
- Exact HTTP status assertions (
toBe(200), nevertoContain([200, 500])) - Response body VALUE assertions (not just property existence)
- State verification after mutations (GET after POST/PUT/DELETE)
- 5xx responses are ALWAYS BLOCKING bugs — never accepted
Negative testing (functional depth, HIGH/MEDIUM risk):
- Empty body → expect 400
- Missing required fields → expect 400 with field name in error
- Wrong types → expect 400
- No auth / invalid auth → expect 401
Multi-step flows (functional depth, HIGH risk):
- CRUD lifecycle: create → read → update → verify → delete → verify gone
- Auth lifecycle: login → access protected → logout → verify session revoked
Data integrity probes (functional depth, HIGH risk):
- Concurrent creation race conditions (
Promise.all) - Duplicate creation → expect 409/400
- Cascade delete verification
Security boundary tests (functional depth, HIGH risk):
- Cross-resource access (IDOR) → expect 403/404
- Role escalation → expect 403
- Session invalidation after logout
- XSS/SQL injection probes (non-destructive)
Missing functionality detection (all modes):
- Missing CRUD operations (create exists but no edit/delete)
- Missing pagination on list endpoints
- Missing search/filter on data tables
- Missing input validation on forms
- Missing rate limiting on auth endpoints
- Missing confirmation dialogs on destructive actions
- Output:
MISSING_FUNCTIONALITY_REPORTwith severity + recommendations
Telemetry (opt-in)
New in v11.2.0 (preserved in v14.0.0) — an optional GitHub Issues telemetry pipeline. After
qualifying agent runs (/supervisor, /code-reviewer, /qa-executor)
complete, the plugin can post a structured GitHub issue summarising the
result block, a derived score, agent performance breakdown, and AI
suggestions for longitudinal analysis. Telemetry is disabled by
default — there is no origin-remote fallback because the plugin runs
in arbitrary user projects.
/telemetry status # Show consent state, target repo, last-sent timestamp
/telemetry enable # Interactive — choose target repo, write consent file
/telemetry disable # Mark consent denied; no further sends
/telemetry test # Dry-run latest payload; never calls gh
Privacy guarantees: the wrapper script always exits 0 (telemetry
can never block an agent run); the core script fails closed on a regex
deny-list (tokens, API keys, bearer tokens, home-dir paths, emails,
.env-style assignments) and never emits matched content — only the
pattern label. To enable, run /telemetry enable (and pick a target
repo) or set AI_AGENT_MANAGER_TELEMETRY_REPO=owner/repo. See
ai-agent-manager-plugin/docs/TELEMETRY.md
for the scoring rubric, exit-code table, and wrapper-vs-core
architecture.
System Twin (advisory foundation, v14.10.0)
The System Twin is an in-repo model of your own system that the agents
consult and update — entirely advisory, propose-only, and strictly
subordinate to CLAUDE.md. v14.10.0 ships its foundation slice: one thin,
additive, reversible vertical that exercises all three pillars on the plugin's
own repo. Nothing here gates a PR or self-applies a change.
- Foundation — System Contracts. A per-subsystem System Contract store
under
.supervisor/twin/(dependency graph, invariants, expectations) is written exclusively by the repo-root sole writerscripts/write-system-contract.sh— it refuses any git-worktree CWD, hash-chains provenance, and writes atomically. Contracts are read viascripts/read-system-contract.shand self-tested byscripts/test-system-contract.sh. (Context-Keeper is deliberately not in this write path.) - Pillar 1 — Predict. Launch Pad's analysis phase reads the contract's dependency graph to produce an advisory blast-radius / impact prediction for the requested work, degrading gracefully (no prediction, no error) when no contract exists yet.
- Pillar 2 — Prove. The Supervisor's post-merge self-heal phase runs an
advisory contract-conformance check against the integrated diff plus a
deterministic benchmark; an ephemeral builder then refreshes the contracts
from the pinned repo-root CWD via the sole writer and emits a hard signal to
both
SUPERVISOR_RESULTand the session JSONL. - Pillar 3 — Compound.
/insightssurfaces the conformance / benchmark trend over time,/dreamingreads contract drift as a distillation input, and the rubric-grader reports the signal as advisory lines — it never gates the PR.
Guardrails: propose-only (no self-applied Twin writes without the existing
human gate), advisory and subordinate to CLAUDE.md, sole-writer +
pinned-CWD enforcement, and every new script self-tested. The foundation added
no new agent / command / skill / hook — the builder is an ephemeral Task and
the helper scripts are not counted.
Task Management
Beads (Optional)
Beads is an optional issue tracker used by Orchestrator and Product Owner. The Supervisor and Launch Pad use .supervisor/ exclusively.
| Command | Purpose |
|---|---|
bd list | View open/in-progress/completed tasks |
bd create | Create new task |
bd claim BD-XX | Start working on a task |
bd close BD-XX | Mark task complete |
bd comment BD-XX "note" | Add notes to task |
bd dep BD-XX BD-YY | Set task dependencies |
Task Structure:
- EPIC: Large feature (contains multiple tasks)
- TASK: Implementation work (30-60 min)
- SUBTASK: Review gate (blocks next task)
Review Gates:
- Every implementation task has a review subtask
- Review subtask blocks next implementation task
- Review decisions: PASS (proceed), FAIL (fix and re-review), NEEDS_HUMAN (creates bug issues)
Project Setup
For New Projects
- Create CLAUDE.md with your project structure and patterns
- Run
/launch-pad goal: "first task"(plan-first) or/supervisor task: "first task"(direct) - Optional:
bd initif using Orchestrator/Product Owner with Beads
CLAUDE.md Structure
Fill in once at the start:
# [Your Project Name]
## Structure
- src/ — [what's here]
- test/ — [what's here]
## Tech Stack
- Node.js, Express, PostgreSQL
- Jest for testing
## Key Patterns
(Document as you discover them)
## Quick Commands
- Build: npm run build
- Test: npm test
- Lint: npm run lint
Common Patterns & Best Practices
Agents Follow These Rules
- Quality First: Thorough, well-tested solutions
- Surgical Changes: Only modify what's necessary
- Pattern Consistency: Use existing patterns
- Type Safety: Strict type checking
- Security: No secrets, validate inputs
- Performance: Profile and document tradeoffs
See AGENT_GUIDELINES.md for detailed standards per language.
Workflow Tips
- Plan first: Run
/launch-pad goal: "..."to prepare a Supervisor-Ready Brief - Use Supervisor for automation: Run
/supervisorfor fully autonomous task completion - Or start with Orchestrator: Run
/orchestrator goal: "..."for manual control - Review iteratively: Run
/code-reviewermultiple times as you fix issues - Review gates: Wait for PASS before moving to next task
- Adversarial audit: Run
/red-team-reviewerbefore launch
CLAUDE.md Proposal Workflow
When Code Reviewer discovers a new pattern:
- Flag in review output: Pattern flagged with rationale and file:line references
- You review: Check if worth documenting
- If approved: You update CLAUDE.md manually
- Next agent learns: Reads updated CLAUDE.md, uses the new pattern
This prevents knowledge loss and helps agents learn from discoveries.
Documentation
- This file (README.md): Overview and quick start
- CLAUDE.md (this repo): Architecture and agent system
- AGENT_GUIDELINES.md: Development standards, quality checklist
- .claude-plugin/marketplace.json: Marketplace manifest (root)
- .claude-plugin/README.md: Detailed plugin documentation
- ai-agent-manager-plugin/.claude-plugin/plugin.json: Plugin manifest
- ai-agent-manager-plugin/agents/*.md: Individual agent prompts (14 roles)
- ai-agent-manager-plugin/skills/*/SKILL.md: 53 skill files for guidance
- ai-agent-manager-plugin/docs/RESULT_SCHEMAS.md: Structured result contracts
- ai-agent-manager-plugin/docs/FAILURE_ESCALATION.md: Agent failure paths
- ai-agent-manager-plugin/docs/ARCHITECTURE_CONTRACTS.md: Capability matrix, budgets, rules
- ai-agent-manager-plugin/docs/ARCHITECTURE.md: Visual agent topology
- ai-agent-manager-plugin/docs/QA_SYSTEM_BLUEPRINT.md: QA system architecture
For Developers
To modify or extend agents:
- Agents are Markdown prompts in
ai-agent-manager-plugin/agents/(14 files) - Commands are in
ai-agent-manager-plugin/commands/(17 commands) - Skills are in
ai-agent-manager-plugin/skills/(53 skills, versioned with SKILLS_INDEX.md) - Hooks: per-agent in frontmatter (Worker, Execute Manager) + cross-cutting in
ai-agent-manager-plugin/hooks/hooks.json(Code Reviewer, QA Executor, TaskCompleted) - Docs:
ai-agent-manager-plugin/docs/RESULT_SCHEMAS.md,…/FAILURE_ESCALATION.md,…/ARCHITECTURE_CONTRACTS.md,…/ARCHITECTURE.md - All agents follow standard output format (see AGENT_GUIDELINES.md)
To test locally, install via the marketplace flow shown in Quick Start → 1. Install the Plugin, then run agents in a test project to verify changes. After pulling new changes, use the refresh flow under Troubleshooting → Skills / agents / hooks not showing after plugin update.
Troubleshooting
Agent doesn't understand my project?
- Update CLAUDE.md with clearer patterns and examples
- Add more detailed structure documentation
Supervisor workflow interrupted?
- State is saved to
.supervisor/state.mdautomatically - Resume with:
/supervisor --continue - Check
.supervisor/history/for completed sessions
Orphaned worktrees after crash?
- Run
git worktree listto see all worktrees - Remove with:
git worktree remove ../project-{subtask_id}
Beads tasks not appearing?
- Run
bd listto check current state - Ensure
bd initwas run in project - Beads is only used by Orchestrator/Product Owner (not Supervisor)
Agents suggesting wrong patterns?
- Update CLAUDE.md with approved patterns
- Review and reject unwanted proposals
Need help?
- Run
/agent-helpfor command reference - Check AGENT_GUIDELINES.md for quality standards
- Check .claude-plugin/README.md for detailed command documentation
- Review agent prompts in ai-agent-manager-plugin/agents/
Skills / agents / hooks not showing after plugin update?
Claude Code caches plugin contents. After pulling new changes (e.g. a fresh git pull on main), force a full refresh:
- Minimal flow — try this first:
/plugin uninstall ai-agent-manager-plugin /plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace /reload-plugins - Full reset — if the minimal flow doesn't pick up your changes, drop the marketplace cache too:
Run from the repo root so/plugin uninstall ai-agent-manager-plugin /plugin marketplace remove ai-agent-manager-marketplace /plugin marketplace add ./ /plugin install ai-agent-manager-plugin@ai-agent-manager-marketplace /reload-plugins./resolves to your local checkout. - Verify with
/skills— should show all 53 skills under "Plugin skills". Use/agent-helpto confirm all 16 user-facing commands are registered.
Previously installed via claude --plugin-dir (flat layout)? Older install instructions told you to launch Claude with --plugin-dir pointing at the repo root. That no longer works — the plugin is now nested under ai-agent-manager-plugin/. Switch to the marketplace flow shown in Quick Start → 1. Install the Plugin.
Known Limitations
Agent Behavior
- LLM limitations: Agents may occasionally reference non-existent files despite validation steps. Always verify before following plans.
- Context7 dependency: External library lookups depend on Context7 MCP. If unavailable, agents fall back to CLAUDE.md patterns.
Scale
- Token usage: Each agent invocation loads prompts (potentially 5,000-10,000 tokens overhead). Consider this for high-frequency usage.
Git Operations
- Main branch protection: The
/commitskill refuses commits on main/master without explicit flag. - No rollback: Git operations are not automatically reversible. Use
git reflogfor manual recovery.
QA System (Level 1)
- Requires Playwright config:
playwright.config.tsmust exist and app must be running - Crawl limits: Max 30 pages, depth 3, same-origin only
- Single debate round: Strategist audits once (multi-round is Level 2+)
- No state modeling or fuzz: L1 tests happy paths + basic errors only
- Coverage is inventory-level: Tracks routes/APIs discovered vs tested, not behavioral
License
MIT — See LICENSE file
Happy shipping!