| name | team-execute |
| description | Two-phase Agent Teams execution — replaces the old /team-implement and /team-review skills.
Phase 1 IMPLEMENT (formerly /team-implement): parallel implementation with teammates per
module/layer, file-ownership separation, and a shared task list with dependencies.
Run after /feature plan approval.
Phase 2 REVIEW (formerly /team-review): specialized reviewers (security, quality,
test coverage) review the changes from different perspectives in parallel.
Pass --review-only to skip Phase 1 and review existing changes
(after manual or Codex implementation).
|
| metadata | {"short-description":"Parallel implementation + parallel review with Agent Teams"} |
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 .agents/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
.agents/rules/cli-execution.md apply.
Inputs
Read these before designing the team so execution stays aligned with the plan
produced by /feature or /plan:
.agents/STATE.md — current project context and decisions.agents/docs/DESIGN.md — architecture and design decisions from the Architect.agents/docs/research/ — Researcher findings and library constraintsPROGRESS.md (repo root) — rolling summary of recent sessions and next actions.agents/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
(.agents/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 .agents/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
- File ownership separation: Each Teammate owns a different set of files
- Respect dependencies: Dependent tasks go to the same Teammate or execute in dependency order
- 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
.agents/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 .agents/skills/team-execute/check_ownership.py \
--assignment .agents/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 .agents/docs/DESIGN.md
- Library constraints from .agents/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)
- .agents/docs/DESIGN.md (architecture)
- .agents/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 .agents/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 .agents/skills/_shared/workspace.py --skill team-execute
--slug {slug} --teammate {your-teammate-name}
and use the returned path verbatim — per the shared
format: .agents/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, .agents/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 .agents/skills/_shared/workspace.py --skill team-execute
--slug {slug} --teammate {your-teammate-name}
and use the returned path verbatim — per the shared
format: .agents/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
Intervention Triggers
| Situation | Response |
|---|
| Teammate not making progress for a long time | Send a message to check, re-instruct if needed |
| File conflict detected | Reassign file ownership |
| Tests keep failing | Send message to the relevant Implementer |
| Sonnet exposes ambiguous or high-risk complexity | Stop that workstream and reassign it to general-purpose-opus with the evidence collected so far |
| Unexpected technical issue | Consult Codex via general-purpose-opus |
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 .agents/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 (
.agents/rules/cli-execution.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 .agents/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 .agents/skills/team-execute/check_ownership.py \
--assignment .agents/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 .agents/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 .agents/skills/_shared/workspace.py \
--skill team-execute --slug {slug} --create
1. Run the gates before spending three reviewers on a red tree
bash .agents/skills/_shared/verify.sh
Exit 0 pass · 1 bad arguments · 2 a gate failed or no gate ran ·
3 write failure. On 2 do not spawn reviewers: report overall, the
failing tools and log_file to the user and stop, unless the user explicitly
chooses to review a red tree. This is the only executable check on the
--review-only path, where the implementer was a Codex run or a human and
"all tests pass" is otherwise an unverified claim.
2. Collect the Guardrail evidence for a delegated implementation
On the --review-only path, also run:
python3 .agents/skills/_shared/verify_delegation.py --base main
It reports deletions, placeholders, weakened_tests and
out_of_scope_files, and its verdict is always needs-review — it collects
evidence, it never accepts a delegated change on your behalf. Hand the findings
to the reviewers as known risk areas.
3. Gather the diff
python3 .agents/skills/_shared/gather_diff.py --base main --out {paths.diff_file}
Always pass --out {paths.diff_file}. The script's own default is a single
fixed path, so two reviews running at once would overwrite each other's patch —
the resolved diff_file is slug-keyed and cannot collide.
Uncommitted work is in scope by default: Phase 1 never commits, and the
predecessor of this script compared committed history only — with the teammates'
edits still in the working tree it reported changed_files: [] and exit 0, and
the three reviewers below then reviewed nothing and reported a clean review.
It writes the full patch to the resolved diff_file
(.agents/logs/review-diff-{slug}.patch, kept out of context) and prints one
JSON object:
changed_files[] — the review scope: committed, staged, unstaged and
untracked, deduplicated. committed_files[], worktree_files[] and
untracked_files[] break it down; diffstat and commits[] summarise it.scope_empty — gate on this. true means nothing changed relative to
--base; do not spawn reviewers.diff_file, patch_bytes — the full patch for reviewers to read as needed.ruff — {status, reason?, exit_code?, issues?, files_linted?, scope} over
the changed .py files only. status is pass / fail / skipped /
error, following verify.sh: an absent linter is skipped, never a lint
failure.coverage — {report, percent, mtime, stale_vs_scope} parsed from an
existing coverage.json / coverage.xml, else null with a warning.
stale_vs_scope: true means the report predates the newest file in scope, so
the percentage does not describe this change.warnings[], artifacts[].
Exit codes: 0 scope collected and non-empty · 1 bad arguments or --out
outside the project root · 2 not a git repository, base ref not found, or
scope_empty · 3 git failed or the patch could not be written.
--no-include-uncommitted restores the committed-only view;
--base/--out override the defaults (main, and a single fixed patch path
that this skill always overrides with the slug-keyed diff_file).
Pass the changed_files list and diff_file path to the reviewers in Step 2-2.
Step 2-2: Spawn Review Team
Launch reviewers with specialized perspectives in parallel.
Entry condition, checked before spending three agents: Step 2-1's verify.sh
did not exit 2 (or the user overrode it), and gather_diff.py reported
scope_empty: false. Reviewers spawned against an empty changed_files list
produce a clean review of nothing.
Reviewers use general-purpose-sonnet by default. Use general-purpose-opus for a
review whose dominant risk is subtle security, concurrency, data integrity,
performance, or cross-system behavior; Quality Reviewer may also consult Codex as
specified below.
Create an agent team to review implementation of: {feature}
The following files were changed:
{changed files list}
Spawn reviewers:
1. **Security Reviewer**
Prompt: "You are a Security Reviewer for: {feature}.
Review all changed files for security vulnerabilities:
- Hardcoded secrets or credentials
- SQL injection, XSS, command injection
- Input validation gaps
- Authentication/authorization issues
- Sensitive data exposure in logs/errors
- Dependency vulnerabilities
Changed files: {list}
Reference: .agents/rules/security.md
For each finding:
- Severity: Critical / High / Medium / Low
- File and line number
- Description of the issue
- Recommended fix
Save report to .agents/docs/research/review-security-{slug}.md
IMPORTANT — Work Log:
When your review is complete, write your work log to
{paths.work_log} — resolve it with
python3 .agents/skills/_shared/workspace.py --skill team-execute
--slug {slug} --teammate security-reviewer
and use the returned path verbatim — per the shared
format: .agents/skills/_shared/work-log-format.md (reviewer variant:
Review Scope + Findings instead of Tasks Completed).
"
2. **Quality Reviewer**
Prompt: "You are a Quality Reviewer for: {feature}.
Review all changed files for code quality:
- Adherence to coding principles (.agents/rules/coding-principles.md)
- Single responsibility violations
- Deep nesting (should use early return)
- Missing type hints
- Magic numbers
- Naming clarity
- Function length (target < 20 lines)
- Library constraint violations (.agents/docs/libraries/)
Use Codex CLI for deep analysis of complex logic. Write the question to
.agents/logs/codex/prompt-quality-review.md, then:
python3 .agents/skills/_shared/codex_consult.py --prompt-file .agents/logs/codex/prompt-quality-review.md --label quality-review --sandbox read-only
Read the answer from the JSON output's response_file. Exit codes: 0 ok
(read response_file); 1 bad args; 2 codex CLI missing; 3 codex failed or
timed out (inspect error/stderr_file).
Changed files: {list}
For each finding:
- Severity: High / Medium / Low
- File and line number
- Current code
- Suggested improvement
Save report to .agents/docs/research/review-quality-{slug}.md
IMPORTANT — Work Log:
When your review is complete, write your work log to
{paths.work_log} — resolve it with
python3 .agents/skills/_shared/workspace.py --skill team-execute
--slug {slug} --teammate quality-reviewer
and use the returned path verbatim — per the shared
format: .agents/skills/_shared/work-log-format.md (reviewer variant:
Review Scope + Findings instead of Tasks Completed).
Extra role-specific section after Findings:
## Codex Consultations
- {question asked to Codex}: {key insight from response}
"
3. **Test Reviewer**
Prompt: "You are a Test Reviewer for: {feature}.
Review test coverage and quality:
- Coverage: use `coverage.percent` from Step 2-1's gather_diff.py JSON. If
`coverage` is null, or `stale_vs_scope` is true, the number does not
describe this change: produce a fresh report with the pytest coverage
command from .agents/rules/testing.md (quality-gate commands:
.agents/rules/dev-environment.md), or report "coverage not measured".
Never estimate a percentage.
- Check: Are all happy paths tested?
- Check: Are error cases covered?
- Check: Are boundary values tested?
- Check: Are edge cases handled?
- Check: Are external deps properly mocked?
- Check: Do tests follow AAA pattern?
- Check: Are tests independent (no order dependency)?
Reference: .agents/rules/testing.md
For each gap:
- File/function missing coverage
- What test cases are needed
- Priority: High / Medium / Low
Save report to .agents/docs/research/review-tests-{slug}.md
IMPORTANT — Work Log:
When your review is complete, write your work log to
{paths.work_log} — resolve it with
python3 .agents/skills/_shared/workspace.py --skill team-execute
--slug {slug} --teammate test-reviewer
and use the returned path verbatim — per the shared
format: .agents/skills/_shared/work-log-format.md (reviewer variant:
Review Scope + Findings instead of Tasks Completed).
Role-specific notes: in Review Scope report Coverage: {percentage};
Findings use [{priority}] {file/function}: {missing test case description}.
Extra role-specific section after Findings:
## Test Execution Results
- Total: {N} tests, Passed: {N}, Failed: {N}
- Coverage: {percentage}
"
Wait for all reviewers to complete.
Optional: Competing Hypotheses (for debugging)
For bug investigation, add adversarial reviewers:
Spawn 3-5 teammates with different hypotheses about the bug.
Have them actively try to disprove each other's theories.
Step 2-3: Synthesize Findings
Validate reviewer work logs, then integrate results and assign priorities.
Reviewer Work Log Validation
Validate every reviewer's work log in the team directory with a single call.
{N} is the number of reviewers you dispatched (3 for the standard team, plus
any Phase 1 logs still in the directory — count what should be there):
python3 .agents/skills/_shared/validate_doc.py --contract work-log \
--dir {paths.team_dir} --expect-files {N}
Exit 0 all valid · 1 bad arguments or missing directory · 2 a required
section is missing or the count differs from --expect-files. On 2, inspect
results and error, and ask that reviewer to fix its log before proceeding —
a reviewer that produced no log has not demonstrably reviewed anything.
Workspace Artifact Check
python3 .agents/skills/_shared/workspace.py --skill team-execute --slug {slug} --verify
ok: true means all three review reports exist and are non-empty — read them
next. On ok: false, check missing / empty before synthesizing.
Review Reports
Read review reports:
.agents/docs/research/review-security-{slug}.md.agents/docs/research/review-quality-{slug}.md.agents/docs/research/review-tests-{slug}.md
Prioritization
| Priority | Criteria | Action |
|---|
| Critical | Security vulnerabilities, data loss risk | Must fix before merge |
| High | Bugs, missing critical tests, type errors | Should fix before merge |
| Medium | Code quality, naming, patterns | Fix if time allows |
| Low | Style, minor improvements | Track for later |
Step 2-4: Report to User
Present the integrated review results to the user.
## Review Results: {feature}
### Summary
- Security: {N} findings (Critical: {n}, High: {n}, Medium: {n})
- Code Quality: {N} findings (High: {n}, Medium: {n}, Low: {n})
- Test Coverage: {coverage.percent from Step 2-1, or "not measured"}
({above/below} the 80% target — omit the comparison when not measured)
### Critical / High Findings
#### [{Severity}] {Issue Title}
- **File**: `{file}:{line}`
- **Issue**: {description}
- **Recommended Fix**: {recommended fix}
...
### Recommended Actions
1. {Action 1 — Critical fix}
2. {Action 2 — High priority fix}
3. {Action 3 — Test gap to fill}
### Medium / Low Findings
{Brief list — details in review reports}
---
Shall we proceed with fixes?
Cleanup
Clean up the team
Tips
- Delegate mode: Use Shift+Tab to prevent Lead from implementing directly
- Task granularity: 5-6 tasks per Teammate is optimal
- File conflict prevention: Module-level ownership separation is the most important factor — and the one part of team design that is checked rather than trusted (
check_ownership.py, preflight before spawning and reconcile after)
- Separate Tester: Having a dedicated Tester separate from Implementers enables a TDD-like workflow
- Reviewer specialization: Each reviewer focuses on a different perspective to prevent blind spots
- Codex utilization: Quality Reviewer delegates complex logic analysis to Codex
- Model routing: Sonnet is the default; use Opus only when ambiguity, risk, or failed attempts justify the additional capability
- Report persistence: Save review results in
.agents/docs/research/ for reference during fixes
- Competing hypotheses mode: Adversarial review pattern is effective for bug investigation
- Cost awareness: Each Teammate is an independent Claude instance (high token consumption). 3 reviewers = 3x tokens; for small changes, a subagent-based review is sufficient
