Team Execute

Team Execute

Parallel implementation followed by parallel review, both via Agent Teams. Executes the plan approved in /feature.

Preflight: ensure codex CLI is current (see codex-system skill).

Arguments

• (no arguments) — run Phase 1 IMPLEMENT, then Phase 2 REVIEW.
• --review-only — skip Phase 1 and go straight to Phase 2 REVIEW. Use after manual implementation or a Codex direct/MODERATE implementation from /feature.

Prerequisites

• Phase 1: /feature or /plan is complete and the plan has been approved by the user; architecture is documented in .claude/docs/DESIGN.md; task list has been created.
• Phase 2 (or --review-only): implementation is complete. "All tests pass" is not taken on trust here: Step 2-1 runs verify.sh and collects diff evidence before any reviewer is spawned. On the --review-only path the implementer was an external agent, which is exactly when the Guardrails in root AGENTS.md apply.

Inputs

Read these before designing the team so execution stays aligned with the plan produced by /feature or /plan:

• .claude/STATE.md — current project context and decisions
• .claude/docs/DESIGN.md — architecture and design decisions from the Architect
• .claude/docs/research/ — Researcher findings and library constraints
• PROGRESS.md (repo root) — rolling summary of recent sessions and next actions
• .claude/docs/plans/{slug}.md — the approved implementation plan, when the plan came from /plan (validated there with validate_doc.py --contract plan-doc; /plan hands over the slug as Next: /team-execute with slug {slug})

Use the same slug /feature or /plan resolved so work logs (.claude/logs/agent-teams/{team-name}/) and research/design files line up across phases. Step 1-1 resolves the workspace for a full run; Step 2-1 re-resolves it for a --review-only entry.

Workflow

Phase 1: IMPLEMENT                        (skipped with --review-only)
  Step 1-1: Analyze Plan & Design Team (check_ownership.py --mode preflight)
  Step 1-2: Spawn Agent Team (implementers per module + tester)
  Step 1-3: Monitor & Coordinate
  Step 1-4: Integration & Verification (validate_doc.py, verify.sh,
            check_ownership.py --mode reconcile)
    ↓
Phase 2: REVIEW
  Step 2-1: Verify & Gather Diff (verify.sh, gather_diff.py)
  Step 2-2: Spawn Review Team (security / quality / test reviewers)
  Step 2-3: Synthesize Findings
  Step 2-4: Report to User

Phase 1: IMPLEMENT

Step 1-1: Analyze Plan & Design Team

Identify parallelizable workstreams from the task list.

Resolve the Workspace

Resolve this run's paths once, reusing the same slug /feature or /plan resolved:

python3 .claude/skills/_shared/workspace.py \
  --skill team-execute --slug {slug} --create

The JSON carries team_name and paths (review_security, review_quality, review_tests, diff_file, team_dir). Adding --teammate NAME returns a work_log path inside team_dir for that teammate. Every {team-name} / output path below MUST come from this JSON verbatim, never be re-derived by hand.

Team Design Principles

1. File ownership separation: Each Teammate owns a different set of files
2. Respect dependencies: Dependent tasks go to the same Teammate or execute in dependency order
3. Appropriate granularity: Target 5-6 tasks per Teammate

Common Team Patterns

Pattern A: Module-Based (Recommended)

Teammate 1: Module A (models, core logic)
Teammate 2: Module B (API, endpoints)
Teammate 3: Tests (unit + integration)

Pattern B: Layer-Based

Teammate 1: Data layer (models, DB)
Teammate 2: Business logic (services)
Teammate 3: Interface layer (API/CLI)

Pattern C: Feature-Based

Teammate 1: Feature X (all layers)
Teammate 2: Feature Y (all layers)
Teammate 3: Shared infrastructure

Anti-patterns

• Two Teammates editing the same file → overwrite risk
• Too many tasks per Teammate → risk of prolonged idle time
• Overly complex dependencies → coordination costs outweigh benefits

Ownership Preflight (mandatory before spawning)

Which decomposition fits this plan is judgment and stays above. Whether the resulting ownership sets overlap has exactly one correct answer, so it is checked, not asserted. Write the map the teammates will actually receive to .claude/logs/ownership-{team_name}.json (gitignored, so it is not itself a change to reconcile later):

{
  "owners": {
    "implementer-api": ["src/api/**"],
    "implementer-core": ["src/core/**"],
    "tester": ["tests/**"]
  }
}

python3 .claude/skills/team-execute/check_ownership.py \
  --assignment .claude/logs/ownership-{team_name}.json --mode preflight

Patterns: ** crosses directories, * and ? do not, and a bare directory covers its subtree. A pattern with no glob character is also matched as an exact path, so two teammates told to create the same new file are caught before either exists.

Exit codes: 0 disjoint · 1 bad arguments or a malformed assignment · 2 overlap. On 2, overlaps[] names the exact path and the owners claiming it — reassign before spawning. patterns_matching_nothing and warnings list globs that match no existing file; confirm each is a file the plan creates rather than a typo. Feed the same JSON into the per-teammate Your file ownership block in Step 1-2 so the map that was checked is the map that was handed out.

Model Routing

• Use general-purpose-sonnet for implementers and the tester by default.
• Assign general-purpose-opus before spawning when a workstream has ambiguous architecture, broad cross-system invariants, subtle security/concurrency/data integrity/performance risk, or a history of failed implementation attempts.
• Do not route by file count alone. Mechanical multi-file work stays on Sonnet when the plan and acceptance criteria are clear.
• If a Sonnet teammate discovers an escalation condition, have it report concrete evidence, stop that workstream, and reassign the remaining work to Opus.

Step 1-2: Spawn Agent Team

Launch the team based on the plan.

Create an agent team for implementing: {feature}

Each teammate receives:
- Project Brief from AGENTS.md
- Architecture from .claude/docs/DESIGN.md
- Library constraints from .claude/docs/libraries/
- Their specific task assignments

Spawn teammates:

1. **Implementer-{module}** for each module/workstream
   Agent: `general-purpose-sonnet` by default; `general-purpose-opus` only when the
   Model Routing criteria above are already met.

   Prompt: "You are implementing {module} for project: {feature}.

   Read these files for context:
   - AGENTS.md (project context)
   - .claude/docs/DESIGN.md (architecture)
   - .claude/docs/libraries/ (library constraints)

   Your assigned tasks:
   {task list for this teammate}

   Your file ownership:
   {the owners entry for this teammate from the preflighted assignment JSON}

   Rules:
   - ONLY edit files in your ownership set — it is reconciled against git in
     Step 1-4, so an edit outside it will surface as unowned
   - Follow existing codebase patterns
   - Write type hints on all functions
   - Run ruff check after each file change
   - Before reporting a task complete, run
     bash .claude/skills/_shared/verify.sh and quote overall; exit 2 means a
     gate failed or no gate ran. No hook does this for you.
   - Communicate with other teammates if you need interface changes
   - If the task reveals an Opus escalation condition, stop and report the evidence

   When done with each task, mark it completed in the task list.

   IMPORTANT — Work Log:
   When ALL your assigned tasks are complete, write your work log to
   {paths.work_log} — resolve it with
   python3 .claude/skills/_shared/workspace.py --skill team-execute
     --slug {slug} --teammate {your-teammate-name}
   and use the returned path verbatim — per the shared
   format: .claude/skills/_shared/work-log-format.md
   Role-specific sections (between Tasks Completed and Communication):
   ## Files Modified
   - `{file path}`: {what was changed and why}
   ## Key Decisions
   - {decision made during implementation and rationale}
   "

2. **Tester** (optional but recommended)
   Agent: `general-purpose-sonnet` by default.

   Prompt: "You are the Tester for project: {feature}.

   Read:
   - AGENTS.md, .claude/docs/DESIGN.md
   - Existing test patterns in tests/

   Your tasks:
   - Write tests for each module as implementers complete them
   - Follow TDD where possible (write test stubs first)
   - Run uv run pytest after each test file
   - Report failing tests to the relevant implementer

   Test coverage target: 80%+ measured, never estimated. If the project has no
   coverage tooling configured, say so instead of reporting a number.

   IMPORTANT — Work Log:
   When ALL your assigned tasks are complete, write your work log to
   {paths.work_log} — resolve it with
   python3 .claude/skills/_shared/workspace.py --skill team-execute
     --slug {slug} --teammate {your-teammate-name}
   and use the returned path verbatim — per the shared
   format: .claude/skills/_shared/work-log-format.md
   Role-specific sections (between Tasks Completed and Communication):
   ## Files Modified
   - `{file path}`: {what was changed and why}
   ## Key Decisions
   - {decision made during implementation and rationale}
   "

Use delegate mode (Shift+Tab) to prevent Lead from implementing directly.
Wait for all teammates to complete their tasks.

Step 1-3: Monitor & Coordinate

Lead focuses on monitoring and integration, not implementing.

Monitoring Checklist

• Check task list progress (Ctrl+T)
• Review each Teammate's output (Shift+Up/Down)
• Verify no file conflicts — check_ownership.py --mode reconcile (below) rather than by eye
• Run bash .claude/skills/_shared/verify.sh yourself at least once mid-run; do not wait for Step 1-4 to discover a broken tree
• Check if any Teammate is stuck

Intervention Triggers

Quality Gates — who actually runs them

No hook runs a quality gate. The configured hooks are a TeammateIdle work-log reminder and a TaskCompleted CLI-call logger; neither executes ruff, pytest or ty. Treat the gates as entirely agent-driven:

• Each teammate runs bash .claude/skills/_shared/verify.sh itself before reporting a task complete, and quotes overall in its report.
• The lead re-runs it in Step 1-4 and does not accept a teammate's self-report in its place (root AGENTS.md Guardrails).
• Gate failure is exit 2, so a verify.sh call whose exit code was never checked is an unverified task.

Step 1-4: Integration & Verification

After all tasks are complete, validate work logs and run integration verification.

Work Log Validation

Validate every teammate's work log in the team directory with a single call. {N} is the number of teammates you actually dispatched:

python3 .claude/skills/_shared/validate_doc.py --contract work-log \
  --dir {paths.team_dir} --expect-files {N}

--expect-files is what makes "no teammate wrote a log at all" visible: Step 1-1's --create already made the directory, so without it an empty team directory returns ok: true, files_checked: 0, files_failed: 0 and exit 0 — indistinguishable from every log being valid.

Exit codes: 0 every log satisfies the contract · 1 bad arguments or the directory does not exist · 2 a required section is missing or the file count differs from --expect-files (error: "expected N files, found M"). On 2, inspect results for the failing file and error for a shortfall, and have that teammate fix its log before proceeding. Use {paths.team_dir} from Step 1-1 — do not re-derive the path by hand.

Ownership Reconcile

Compare the assignment against what git says actually changed:

python3 .claude/skills/team-execute/check_ownership.py \
  --assignment .claude/logs/ownership-{team_name}.json \
  --mode reconcile --base main

It derives the changed-file list through _shared/gather_diff.py, so uncommitted teammate work counts. Exit 0 clean · 1 bad arguments · 2 a changed file that two owners claim (overlaps[]) or that nobody was assigned (unowned_changes[]) · 3 git could not report the scope. Add --allow-path PATTERN for files the lead legitimately maintains outside the map (PROGRESS.md, a task list). idle_owners[] names teammates that changed nothing — a workstream that silently did not run.

Quality Gates

Run the quality gates:

bash .claude/skills/_shared/verify.sh

Exit codes: 0 overall: "pass" · 1 bad arguments · 2 a gate failed, or no gate could run at all · 3 the log file could not be written. On 2 read overall: fail means inspect log_file; no_gates means nothing was verified — supply the project's own commands, run them, and record each command with its exit code in the report below. Only then re-run with --allow-no-gates to record the state deliberately.

Integration Report

Quote the tools object from the verify.sh JSON verbatim. Do not re-type gate statuses: the payload distinguishes pass / fail / skipped, and a hand-written PASS erases the difference between a gate that passed and a gate that never ran.

## Implementation Complete: {feature}

### Completed Tasks
- [x] {task 1}
- [x] {task 2}
...

### Quality Checks
overall: {overall}
{the tools object, pasted from the verify.sh JSON}

### Ownership Reconcile
- overlaps: {overlaps} · unowned: {unowned_changes} · idle: {idle_owners}

### Next Steps
Proceed to Phase 2: REVIEW

Cleanup

Clean up the implementation team

Then continue to Phase 2.

Phase 2: REVIEW

Parallel review from multiple perspectives. Entry point when --review-only is passed.

Read the Inputs listed above (DESIGN.md, PROGRESS.md) so the review is grounded in the original intent, not just the raw diff. Carry the same {feature} name forward so the review references the matching design and work-log files.

Step 2-1: Verify & Gather Diff

Confirm the tree is green, then identify the scope of changes to review.

If Phase 1 already ran, Step 1-1 resolved the workspace already — repeat the identical call here (idempotent) when entering directly via --review-only:

python3 .claude/skills/_shared/workspace.py \
  --skill team-execute --slug {slug} --create