| name | ways-of-working |
| description | Agent team best practices — philosophy, routing, execution model, adversarial loop, cost management, failure modes, and brief writing.
|
Agent Flow — Ways of Working
Team Philosophy
- Parent implements directly. Default tier: zero subagent spawns. The parent (Claude) reads, plans, codes, tests, and documents end-to-end without routing to builder agents.
- Focused context beats broad context. Narrow agent scope = better reasoning.
- Clarity over speed. Vague brief → vague code. The brief is the bottleneck.
- Always use
AskUserQuestion for discrete options (multiple choice, yes/no, A/B/C) — never plain text.
Execution Model: Parent-Direct (Default)
The parent runs end-to-end. Subagents are used sparingly for specific roles only:
| When | Spawn | Mode |
|---|
/plan: repo >100 files AND entry points not read | explorer (read-only, ≤20 tool calls) | parallel if researcher also spawns |
/plan: domain-specific facts needed | researcher (web search) | parallel if explorer also spawns |
/plan: new external dep flagged | researcher (dependency validation) | parallel if explorer also spawns |
/build --strict or --loops N>0 | critic (adversarial review, once per loop) | sequential (depends on builder output) |
/review --strict or --loops N>0 | critic (adversarial review, once per loop) | parallel with external-review if both enabled |
Never spawn subagents outside these rules. Default tier (/build, /review) = zero spawns. /plan default tier may spawn explorer and/or researcher per the rules above.
Parallelism Rule
run_in_background=True is allowed only for independent spawns. A spawn is independent iff its inputs do not depend on another spawn's outputs from the same pipeline stage.
- Independent pairs (may parallelise):
explorer + researcher in /plan; critic + external-review in /build --strict or /review --strict (both consume the same diff).
- Dependent pairs (must remain sequential): builder → critic (critic consumes builder's diff); critic → builder-fix (builder-fix consumes critic's FAIL list); tester → builder-fix.
- Default is sequential. Parallelism is opt-in per invocation. No global auto-parallelise heuristic. If in doubt, run sequentially.
Mixed Pipeline Pattern
When combining independent and dependent spawns in one pipeline:
# 1. Launch independent spawns in background
Agent(subagent_type="A", run_in_background=True, ...) # write log marker immediately
Agent(subagent_type="B", run_in_background=True, ...) # write log marker immediately
# Both markers must appear in progress before either result is consumed.
# 2. Wait point — parent blocks until both report complete
# Stall detection applies per-spawn: A stalling does not cancel B. Partial completion allowed.
# 3. Dependent spawn runs sequentially, consuming A and B outputs
Agent(subagent_type="C", run_in_background=False, ...)
Stall Detection
A subagent producing no output for its configured stall threshold triggers a cancel-and-retry. This applies identically to foreground (run_in_background=False) and background (run_in_background=True) spawns — same threshold, cancelled the same way, parent notified the same way. Parallel fan-out does not disable stall checks.
Agent Roster
| Agent | Model | Role |
|---|
| critic | opus | Adversarial review — tries to break code |
| researcher | sonnet | Web research, docs, library investigation |
| explorer | haiku | Codebase navigation — read only, cheap |
Two Operational Modes
Full Pipeline (/build)
Use when correctness matters more than speed: security-critical paths, public APIs, data migrations. Full sequence: implement → critic loop → test → review → commit.
Lite Mode (default)
Use for everyday work: bug fixes, small features, single-file changes. Parent handles everything inline. No subagents unless using --strict.
The Adversarial Review Loop
parent builds → critic (FAIL) → parent fixes diff only → critic → ... → critic (PASS) → commit
Key rules:
- Parent fixes ONLY flagged issues — no bonus refactoring
- Critic reviews ONLY the new diff — not the whole codebase
- Hard limit: 3 iterations (default),
--loops N to override
- Critic integrity: The critic is NEVER told which iteration it is on or how many remain. Verdict based solely on code quality.
Cost Management
When to spawn subagents
Subagents multiply tokens 4-7x. Justified when focused context beats one bloated session. NOT justified for single-file tasks or simple bug fixes. Default to lite mode; escalate with --strict.
Token Efficiency Rules
- Output brevity: Completion reports under 30 lines. Structured, not prose.
- No redundant reading: Never include file contents in output. Downstream agents read files themselves.
- Diff-only reviews: Critic reviews the diff only — never re-reads the full codebase.
- No preamble: Start with structured output immediately.
Agent Routing Rules
- Explorer: Invoke before every non-trivial task. Cheap — use constantly. Read-only; never edits.
- Researcher: Before the build starts, not during. Use for external library docs, current best practices.
- Critic: Only via
/build or /review. Reviews diff only. Passes ONLY when no failure scenario found.
Common Failure Modes
| Failure | Symptom | Fix |
|---|
| Parent applies fixes mid-critic-loop | Bonus refactoring beyond flagged items | Fix only what critic flagged — nothing more |
| Critic loop won't converge | New issues each iteration | Stop → redesign approach |
| Explorer over-reads | Context bloat | Cap explorer at 20 tool calls; output paths only |
| Researcher mid-build | Build pauses for research | Invoke researcher before build, not during |
Writing Good Briefs
Every brief must answer:
- Scope — which files, domains, systems
- Constraints — what must not change or break
- Done condition — specific, testable outcome
- Known unknowns — edge cases, risks, dependencies
Quick Reference
Task type → Route
─────────────────────────────────────────────────────
Single-file / small fix → lite (just ask naturally)
Multi-file feature, hard to undo → /build <brief>
Feature planning → /plan <idea>
Harden existing code → /review <files>
Codebase question → explorer
Library/API research → researcher
Decision rule: "Could this break something across multiple systems?" Yes → /build. Otherwise → lite.
