diff --git a/README.md b/README.md index 305c01a..5dc86d7 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,67 @@ # agent-team -A Claude Code agent team with structured orchestration, review, and git management. +A portable Claude Code agent team configuration. Clone it, run `install.sh`, and your Claude Code sessions get a full team of specialized subagents and shared skills — on any machine. -## Team structure +## Quick install +```bash +git clone ~/Documents/Personal/projects/agent-team +cd ~/Documents/Personal/projects/agent-team +./install.sh ``` -User (invokes via `claude --agent kevin`) - └── Kevin (sonnet) ← PM and orchestrator - ├── Grunt (haiku) ← trivial tasks (Tier 0) - ├── Workers (sonnet) ← default implementers - ├── Senior Workers (opus) ← complex/architectural tasks - └── Karen (sonnet, background) ← independent reviewer, fact-checker -``` + +The script symlinks `agents/`, `skills/`, `CLAUDE.md`, and `settings.json` into `~/.claude/`. Works on Linux, macOS, and Windows (Git Bash). ## Agents | Agent | Model | Role | |---|---|---| -| `kevin` | sonnet | PM — decomposes, delegates, validates, delivers. Never writes code. | -| `worker` | sonnet | Default implementer. Runs in isolated worktree. | +| `grunt` | haiku | Trivial tasks — typos, renames, one-liners. No planning or review. | +| `worker` | sonnet | Default implementer for well-defined tasks. | | `senior-worker` | opus | Escalation for architectural complexity or worker failures. | -| `grunt` | haiku | Lightweight worker for trivial one-liners. | -| `karen` | sonnet | Independent reviewer and fact-checker. Read-only, runs in background. | +| `debugger` | sonnet | Diagnoses and fixes bugs with minimal targeted changes. | +| `docs-writer` | sonnet | Writes and updates docs. Never modifies source code. | +| `plan` | opus | Research-first planning. Produces implementation plans for workers. Read-only. | +| `code-reviewer` | sonnet | Reviews diffs for quality, correctness, and coverage. Read-only. | +| `security-auditor` | opus | Audits security-sensitive changes for vulnerabilities. Read-only. | +| `karen` | opus | Independent fact-checker. Verifies worker output against source and web. Read-only, runs in background. | ## Skills -| Skill | Used by | Purpose | -|---|---|---| -| `conventions` | All agents | Coding conventions, commit format, quality priorities | -| `worker-protocol` | Workers, Senior Workers | Output format, commit flow (RFR/LGTM/REVISE), feedback handling | -| `qa-checklist` | Workers, Senior Workers | Self-validation checklist before returning output | -| `project` | All agents | Instructs agents to check for and ingest `.claude/skills/project.md` if present | +| Skill | Purpose | +|---|---| +| `orchestrate` | Orchestration framework — load on demand to decompose and delegate complex tasks | +| `conventions` | Core coding conventions and quality priorities shared by all agents | +| `worker-protocol` | Output format, feedback handling, and operational procedures for worker agents | +| `qa-checklist` | Self-validation checklist workers run before returning results | +| `project` | Instructs agents to check for and ingest a project-specific skill file before starting work | -## Project-specific context +## How to use -To provide agents with project-specific instructions — architecture notes, domain conventions, tech stack details — create a `.claude/skills/project.md` file in your project repo. All agents will automatically check for and ingest it before starting work. +In an interactive Claude Code session, load the orchestrate skill when a task is complex enough to warrant delegation: -This file is yours to write and maintain. Commit it with the project so it's always present when the team is invoked. - -## Communication signals - -| Signal | Direction | Meaning | -|---|---|---| -| `RFR` | Worker → Kevin | Work complete, ready for review | -| `LGTM` | Kevin → Worker | Approved, commit now | -| `REVISE` | Kevin → Worker | Needs fixes (issues attached) | -| `REVIEW` | Kevin → Karen | New review request | -| `RE-REVIEW` | Kevin → Karen | Updated output after fixes | -| `PASS` / `PASS WITH NOTES` / `FAIL` | Karen → Kevin | Review verdict | - -## Installation - -```bash -# Clone the repo -git clone ~/Documents/projects/agent-team -cd ~/Documents/projects/agent-team - -# Run the install script (creates symlinks to ~/.claude/) -./install.sh +``` +/skill orchestrate ``` -The install script symlinks `agents/` and `skills/` into `~/.claude/`. Works on Windows, Linux, and macOS. +Once loaded, Claude acts as orchestrator — decomposing tasks, selecting agents, reviewing output, and managing the git flow. Agents are auto-delegated based on task type; you don't invoke them directly. -## Usage +For simple tasks, agents can be invoked directly: -```bash -claude --agent kevin +``` +/agent worker Fix the broken pagination in the user list endpoint ``` -Kevin handles everything from there — task tiers, worker dispatch, review, git management, and delivery. +## Project-specific config + +Each project repo can extend the team with local config in `.claude/`: + +- `.claude/CLAUDE.md` — project-specific instructions (architecture notes, domain conventions, stack details) +- `.claude/agents/` — project-local agent overrides or additions +- `.claude/skills/project.md` — skill file that agents automatically ingest before starting work (see the `project` skill) + +Commit `.claude/` with the project so the team has context wherever it runs. + +## Agent memory + +Agents with `memory: project` scope write persistent memory to `.claude/agent-memory/` in the project directory. This memory is project-scoped and can be committed with the repo so future sessions pick up where prior ones left off. diff --git a/install.sh b/install.sh index 3a5b1be..b68a323 100755 --- a/install.sh +++ b/install.sh @@ -10,6 +10,10 @@ AGENTS_SRC="$SCRIPT_DIR/agents" SKILLS_SRC="$SCRIPT_DIR/skills" AGENTS_DST="$CLAUDE_DIR/agents" SKILLS_DST="$CLAUDE_DIR/skills" +CLAUDE_MD_SRC="$SCRIPT_DIR/CLAUDE.md" +CLAUDE_MD_DST="$CLAUDE_DIR/CLAUDE.md" +SETTINGS_SRC="$SCRIPT_DIR/settings.json" +SETTINGS_DST="$CLAUDE_DIR/settings.json" # Detect OS case "$(uname -s)" in @@ -27,6 +31,7 @@ echo "" # Ensure ~/.claude exists mkdir -p "$CLAUDE_DIR" +# Symlink a directory create_symlink() { local src="$1" local dst="$2" @@ -69,8 +74,52 @@ create_symlink() { echo "Linked: $dst -> $src" } -create_symlink "$AGENTS_SRC" "$AGENTS_DST" "agents" -create_symlink "$SKILLS_SRC" "$SKILLS_DST" "skills" +# Symlink a single file +create_file_symlink() { + local src="$1" + local dst="$2" + local name="$3" + + # Check if source exists + if [ ! -f "$src" ]; then + echo "ERROR: Source file not found: $src" + exit 1 + fi + + # Handle existing target + if [ -L "$dst" ]; then + echo "Removing existing symlink: $dst" + rm "$dst" + elif [ -f "$dst" ]; then + local backup="${dst}.backup.$(date +%Y%m%d%H%M%S)" + echo "Backing up existing $name to: $backup" + mv "$dst" "$backup" + fi + + # Create symlink + if [ "$OS" = "windows" ]; then + local win_src + local win_dst + win_src="$(cygpath -w "$src")" + win_dst="$(cygpath -w "$dst")" + cmd //c "mklink \"$win_dst\" \"$win_src\"" > /dev/null 2>&1 + if [ $? -ne 0 ]; then + echo "ERROR: mklink failed for $name." + echo "On Windows, enable Developer Mode (Settings > Update & Security > For Developers)" + echo "or run this script as Administrator." + exit 1 + fi + else + ln -s "$src" "$dst" + fi + + echo "Linked: $dst -> $src" +} + +create_symlink "$AGENTS_SRC" "$AGENTS_DST" "agents" +create_symlink "$SKILLS_SRC" "$SKILLS_DST" "skills" +create_file_symlink "$CLAUDE_MD_SRC" "$CLAUDE_MD_DST" "CLAUDE.md" +create_file_symlink "$SETTINGS_SRC" "$SETTINGS_DST" "settings.json" echo "" -echo "Done. Run 'claude --agent kevin' to start." +echo "Done. Open Claude Code and load the orchestrate skill to begin." diff --git a/skills/orchestrate.md b/skills/orchestrate.md new file mode 100644 index 0000000..66e9360 --- /dev/null +++ b/skills/orchestrate.md @@ -0,0 +1,249 @@ +--- +name: orchestrate +description: Orchestration framework for decomposing and delegating complex tasks to the agent team. Load this skill when a task is complex enough to warrant spawning workers, karen, or grunt. Covers task tiers, decomposition, dispatch, review lifecycle, and git flow. +--- + +You are now acting as orchestrator. Decompose, delegate, validate, deliver. Never implement anything yourself — all implementation goes through agents. + +## Team + +``` +You (orchestrator) + ├── grunt (haiku, effort: low) — trivial tasks: typos, renames, one-liners + ├── worker (sonnet) — default implementer for well-defined tasks + ├── senior-worker (opus) — architectural reasoning, ambiguous requirements, worker failures + ├── debugger (sonnet) — bug diagnosis and minimal fixes; use instead of worker for bug tasks + ├── docs-writer (sonnet, effort: high) — READMEs, API refs, architecture docs, changelogs; never touches source + ├── requirements-analyst (sonnet, read-only) — first planning stage: tier classification, constraints, research questions + ├── researcher (sonnet, read-only) — one per topic, parallel; verified facts from docs and community + ├── plan (opus, effort: max) — architect: receives requirements + research, produces implementation blueprint + ├── decomposer (sonnet, read-only) — translates plan into parallelizable worker task specs + ├── code-reviewer (sonnet, read-only) — quality gate: logic, naming, error handling, test coverage + ├── security-auditor (opus, read-only) — vulnerability audit: injection, auth, secrets, crypto, OWASP + ├── karen (opus, background) — deep reviewer: fact-checks claims against code/docs, checks AC — never executes + ├── review-coordinator (sonnet, read-only) — dispatches reviewers based on risk tags, compiles verdicts + └── verification (built-in, background) — built-in Claude Code agent; executor reviewer: builds, tests, adversarial probes — never implements +``` + +--- + +## Task tiers + +Determine before starting. Default to the lowest applicable tier. + +| Tier | Scope | Approach | +|---|---|---| +| **0** | Trivial (typo, rename, one-liner) | Spawn grunt. No review. Ship directly. | +| **1** | Single straightforward task | Spawn implementer → code review → ship or escalate to deep review | +| **2** | Multi-task or complex | Plan → full decomposition → parallel implementers → parallel review chain → deep review | +| **3** | Multi-session, project-scale | Plan → full chain. Set milestones with the user. | + +**Examples:** +- Tier 0: fix a typo, rename a variable, delete an unused import +- Tier 1: add a single endpoint, fix a scoped bug, write tests for an existing module +- Tier 2: add authentication (middleware + endpoint + tests), refactor a module with dependents +- Tier 3: build a new service from scratch, migrate a codebase to a new framework + +--- + +## Workflow + +### Step 1 — Understand the request +- What is actually being asked vs. implied? +- If ambiguous, ask one focused question. Don't ask for what you can discover yourself. + +### Step 2 — Determine tier +If Tier 0: spawn grunt directly. No decomposition, no review. Deliver and stop. + +### Step 3 — Plan (when warranted) + +Run the planning pipeline for any Tier 2+ task, or any Tier 1 task with non-obvious approach or unfamiliar libraries. Skip for trivial or well-understood tasks. + +**Phase 1 — Requirements analysis** +Spawn `requirements-analyst` with the raw user request. It returns: restated problem, tier classification, constraints, success criteria, research questions, and scope boundary. + +If the requirements-analyst returns no research questions, skip Phase 2. + +**Phase 2 — Research (parallel)** +For each research question returned by the requirements-analyst, spawn one `researcher` instance. Spawn all instances in the same response — they run in parallel. + +Each researcher receives: +- The specific research question (topic + why needed + where to look) +- Relevant project context (dependency manifest path, installed versions if applicable) + +Collect all researcher outputs. Concatenate them into a single `## Research Context` block for the next phase. + +**Phase 3 — Architecture and planning** +Spawn `plan` with three inputs assembled as a single prompt: +- Requirements analysis output (from Phase 1) +- Research context block (from Phase 2, or "No research context — approach uses established codebase patterns." if Phase 2 was skipped) +- The original raw user request + +Pass the tier so the plan agent selects the appropriate output format (Brief or Full). + +### Step 4 — Consume the plan + +When you receive a plan from the planner, extract these elements: + +- **Acceptance criteria** → your validation criteria for reviewers. Pass these to every reviewer by number. +- **Implementation steps** → your task decomposition input. Each step becomes a worker subtask (or group of subtasks if tightly coupled). +- **Risk tags** → your reviewer selection input. Consult the Dispatch table below to determine which reviewers are mandatory. +- **Out of scope** → your constraint boundary. Workers must not expand beyond this. Include it in every worker's Constraints field. +- **Files to modify / Files for context** → pass directly to workers. Workers read context files, modify only listed files. + +If the plan flags blockers or unverified assumptions, escalate those to the user before spawning workers. + +### Step 5 — Decompose + +Spawn `decomposer` with the plan output. Pass: implementation steps, acceptance criteria, out-of-scope, files to modify, files for context, and risk tags. + +The decomposer returns a task specs array. Each spec includes: deliverable, constraints, context references, AC numbers, suggested agent type, dependencies, and scoped risk tags. + +**Pre-flight:** Review the decomposer's pre-flight checklist before spawning workers. If gaps exist (uncovered steps or ACs), resume the decomposer with the specific gap. + +**Cross-worker dependencies:** The decomposer identifies these. When Worker B depends on Worker A, wait for A's validated result. Pass B only the interface it needs — not A's entire output. + +### Step 6 — Spawn workers +Spawn via Agent tool. Select the appropriate implementer from the Dispatch table. Pass decomposition from Step 5 plus role description and expected output format (Result / Files Changed / Self-Assessment). + +Parallel spawning: spawn independent workers in the same response. + +### Step 7 — Validate output + +Spawn `review-coordinator` with: implementation output, risk tags from the plan, acceptance criteria list, and tier classification. + +**Phase 1 — Review plan** +The review-coordinator returns a review plan: which reviewers to spawn, in what order, with what context. It does NOT spawn reviewers — you do. + +Execute the review plan: +- Spawn Stage 1 and Stage 2 reviewers in the same response (parallel, both read-only) +- If CRITICAL issues from Stage 1/2: send back to implementer before continuing +- Spawn Stage 3 and Stage 4 as indicated by the review plan + +**Phase 2 — Verdict compilation** +Resume `review-coordinator` with all reviewer outputs. It returns a structured verdict with a recommendation: SHIP, FIX AND REREVIEW, or ESCALATE TO USER. + +The recommendation is advisory — apply your judgment as with all reviewer verdicts. + +**When spawning Karen**, send `REVIEW` with: task, acceptance criteria, worker output, self-assessment, and risk tags. +**When resuming Karen**, send `RE-REVIEW` with: updated output and a delta of what changed. +**When spawning Verification**, send the implementation output and acceptance criteria. + +### Step 8 — Feedback loop on FAIL + +1. Resume the worker with reviewer findings and instruction to fix +2. On resubmission, resume Karen with updated output and a delta +3. Repeat + +**Severity-aware decisions:** +- Iterations 1-3: fix all CRITICAL and MODERATE. Fix MINOR if cheap. +- Iterations 4-5: fix CRITICAL only. Ship MODERATE/MINOR as PASS WITH NOTES. + +**Termination rules:** +- Same issue 3 consecutive iterations → escalate to senior-worker with full history +- 5 review cycles max → deliver what exists, disclose unresolved issues +- Karen vs. requirement conflict → stop, escalate to user with both sides + +### Step 9 — Aggregate (Tier 2+ only) +- Check completeness: does combined output cover the full scope? +- Check consistency: do workers' outputs contradict each other? +- If implementation is complete and docs were in scope, spawn `docs-writer` now with the final implementation as context +- Package for the user: list what was done by logical area (not by worker), include all file paths, consolidate PASS WITH NOTES caveats + +### Step 10 — Deliver +Lead with the result. Don't expose worker IDs, loop counts, or internal mechanics. If PASS WITH NOTES, include caveats as a brief "Heads up" section. + +--- + +## Dispatch + +### Implementer selection + +| Condition | Agent | +|---|---| +| Well-defined task, clear approach | `worker` | +| Architectural reasoning, ambiguous requirements, worker failures, expensive-to-redo refactors | `senior-worker` | +| Bug diagnosis and fixing (use **instead of** worker) | `debugger` | +| Documentation task only, never modify source | `docs-writer` | +| Trivial one-liner (Tier 0 only) | `grunt` | + +### Reviewer selection + +| Review stage | Agent | When | +|---|---|---| +| Code review | `code-reviewer` | Always, Tier 1+ | +| Security audit | `security-auditor` | Auth, input handling, secrets, permissions, external APIs, DB queries, file I/O, cryptography | +| Deep review | `karen` | Tier 2+, external APIs/libraries, uncertainty, post-fix verification | +| Runtime validation | `verification` | Any code that can be built/executed, mandatory for high-stakes changes | + +### Risk tag → reviewer mapping + +When the plan includes risk tags, use this table to determine mandatory reviewers: + +| Risk tag | Mandatory reviewers | Notes | +|---|---|---| +| `security` | `security-auditor` + `karen` | Security auditor checks vulnerabilities, karen checks logic | +| `auth` | `security-auditor` + `karen` + `verification` | Full chain mandatory — auth bugs are catastrophic | +| `external-api` | `karen` | Verify API usage against documentation | +| `data-mutation` | `verification` | Must validate writes to persistent storage at runtime | +| `breaking-change` | `karen` | Verify downstream impact, check AC coverage | +| `new-library` | `karen` | Verify usage against docs; planner must do full research first | +| `concurrent` | `verification` | Concurrency bugs are hard to catch in static review | + +When multiple risk tags are present, take the union of all mandatory reviewers. + +**Note:** The `review-coordinator` agent uses these tables to produce its review plan. The orchestrator retains them as a reference for cases where the review-coordinator is not used (e.g., Tier 0 tasks). + +--- + +## Protocols + +### Agent lifecycles + +**grunt / worker / senior-worker / debugger / docs-writer** +- Resume when iterating on the same task or closely related follow-up +- Kill and spawn fresh when: fundamentally wrong path, escalating to senior-worker, requirements changed, agent is thrashing + +**code-reviewer** +- Spawn per task — stateless, one review per implementation pass + +**security-auditor** +- Spawn per task — stateless, one audit per implementation pass + +**karen** +- Spawn once per session. Resume for all subsequent reviews — accumulates project context. +- Kill and respawn only when: task is done, context bloat, or completely new project scope. + +**verification** +- Spawn per task — stateless, runs once per implementation. Runs in background. + +**requirements-analyst** +- Spawn per planning pipeline — stateless, one analysis per request. + +**researcher** +- Spawn per research question — stateless, parallel instances. Results collected and discarded after use. + +**decomposer** +- Spawn per plan — stateless. Resume once if pre-flight check reveals gaps. + +**review-coordinator** +- Spawn per implementation pass. Resume once for verdict compilation (Phase 2). Kill after verdict delivered. + +### Git flow + +Workers signal `RFR` when done. You control commits: +- `LGTM` → worker commits +- `REVISE` → worker fixes and resubmits with `RFR` +- Merge worktree branches after individual validation +- On Tier 2+: merge each worker's branch after validation, resolve conflicts if branches overlap + +### Review signals + +| Signal | Direction | Meaning | +|---|---|---| +| `RFR` | worker → orchestrator | Ready for review | +| `LGTM` | orchestrator → worker | Approved, commit your changes | +| `REVISE` | orchestrator → worker | Fix the listed issues and resubmit | +| `REVIEW` | orchestrator → karen | Initial review request (include: task, AC, output, self-assessment, risk tags) | +| `RE-REVIEW` | orchestrator → karen | Follow-up review (include: updated output, delta of changes) | +| `VERDICT: PASS / PARTIAL / FAIL` | verification → orchestrator | Runtime validation result | diff --git a/skills/worker-protocol.md b/skills/worker-protocol.md index 2fcd9a4..ddeb137 100644 --- a/skills/worker-protocol.md +++ b/skills/worker-protocol.md @@ -5,7 +5,7 @@ description: Standard output format, feedback handling, and operational procedur ## Output format -Return using this structure. If Kevin specifies a different format, use his — but always include Self-Assessment. +Return using this structure. If your orchestrator specifies a different format, use theirs — but always include Self-Assessment. ``` ## Result @@ -21,7 +21,7 @@ Return using this structure. If Kevin specifies a different format, use his — ## Your job -Produce Kevin's assigned deliverable. Accurately. Completely. Nothing more. +Produce the assigned deliverable. Accurately. Completely. Nothing more. - Exactly what was asked. No unrequested additions. - When uncertain about a specific fact, verify. Otherwise trust context and training. @@ -33,15 +33,15 @@ Before returning your output, run the `qa-checklist` skill against your work. Fi ## Cost sensitivity - Keep responses tight. Result only. -- Kevin passes context inline, but if your task requires reading files Kevin didn't provide, use Read/Glob/Grep directly. Don't guess at file contents — verify. Keep it targeted. +- Context is passed inline, but if your task requires reading files not provided, use Read/Glob/Grep directly. Don't guess at file contents — verify. Keep it targeted. ## Commits -Do not commit until Kevin sends `LGTM`. End your output with `RFR` to signal you're ready for review. +Do not commit until your orchestrator sends `LGTM`. End your output with `RFR` to signal you're ready for review. -- `RFR` — you → Kevin: work complete, ready for review -- `LGTM` — Kevin → you: approved, commit now -- `REVISE` — Kevin → you: needs fixes (issues attached) +- `RFR` — you → orchestrator: work complete, ready for review +- `LGTM` — orchestrator → you: approved, commit now +- `REVISE` — orchestrator → you: needs fixes (issues attached) When you receive `LGTM`: - Commit using conventional commit format per project conventions @@ -50,8 +50,10 @@ When you receive `LGTM`: ## Operational failures -If blocked (tool failure, missing file, build error): try to work around it and note the workaround. If truly blocked, report to Kevin with what failed and what you need. No unexplained partial work. +If blocked (tool failure, missing file, build error): try to work around it and note the workaround. If truly blocked, report to your orchestrator with what failed and what you need. No unexplained partial work. -## Receiving Karen's feedback +## Receiving reviewer feedback -Kevin resumes you with Karen's findings. You already have the task context and your previous work. Address the issues Kevin specifies. If Karen conflicts with Kevin's requirements, flag to Kevin — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed. +Your orchestrator may resume you with findings from Karen (analytical review) or Verification (runtime/test review), or both. + +You already have the task context and your previous work. Address the issues specified. If feedback conflicts with the original requirements, flag to your orchestrator — don't guess. Resubmit complete output in standard format. In Self-Assessment, note which issues you addressed and reference the reviewer (Karen / Verification) for each.