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/ver

Content truncated.