| name | super-dev |
| description | Use when implementing features, fixing bugs, refactoring code, optimizing performance, resolving deprecations, or any multi-step development task requiring planning, implementation, testing, and review. Orchestrates specialized agent teammates through research, architecture, coding, QA, code review, adversarial review, and documentation phases. Triggers on: "implement", "build", "fix bug", "refactor", "add feature", "develop this", "help me build", "add functionality", "optimize performance", "resolve deprecation", "systematic development". Do NOT trigger on: simple questions ("what does this code do?"), file searches ("where is the auth function?"), one-off commands ("run the tests"), code explanations, quick edits, or non-development tasks.
|
| license | MIT |
| compatibility | Requires Claude Code CLI with Task tool support. Git required for worktree management. Agent teams experimental feature recommended. |
| metadata | {"author":"Jennings Liu","version":"2.7.0","homepage":"https://github.com/jenningsloy318/super-skill-claude-artifacts","repository":"https://github.com/jenningsloy318/super-skill-claude-artifacts","keywords":["development","workflow","debugging","implementation","refactoring","specification","coordinator","parallel","agent-teams"]} |
Super Dev Workflow - Agent Teams Edition
A team-based development system where the Team Lead orchestrates specialized agent teammates — it NEVER implements directly, only spawns, coordinates, and verifies. Agents execute research, architecture, coding, QA, code review, and documentation stages in parallel where possible.
Team Lead agent team workflow. The Team Lead orchestrates specialized agent teammates — it NEVER implements directly, only spawns, coordinates, and verifies. Agents execute research, architecture, coding, QA, code review, and documentation stages in parallel where possible.
Triggers on: "implement", "build", "fix bug", "refactor", "add feature", "develop this", "help me build", "add functionality", "optimize performance", "resolve deprecation", "systematic development". Do NOT trigger on: simple questions, file searches, one-off commands, code explanations, quick edits, non-development tasks.
When to Use
ACTIVATE for (multi-step development requiring planning + implementation):
- Bug fixes, build warnings/errors
- New features, improvements
- Performance optimization
- Deprecation resolution
- Refactoring
- Complex development tasks requiring multiple specialists
DO NOT ACTIVATE for (these are too simple for a full workflow):
- "What does this code do?" - Simple explanation, no dev workflow needed
- "Where is the auth function?" - File search, use Grep/Glob directly
- "Run the tests" - Single command, use Bash directly
- "Fix this typo" - Trivial edit, use Edit directly
- "Explain this error" - Q&A, no workflow needed
- "Search for the config file" - Research task, not development
Quick Start
I'm using super-dev to implement: [describe your task]
The Team Lead will automatically orchestrate all workflow phases.
Invoke dev-rules skill. MUST complete before any other action.
Create worktree, spec dir, workflow JSON, agent team. MUST complete before any codebase exploration or agent spawning.
Spawn requirements-clarifier + doc-validator (parallel). Gate: gate-requirements.sh.
Spawn bdd-scenario-writer + doc-validator (parallel). Gate: gate-bdd.sh.
Spawn research-agent. Firecrawl MCP first, then supplementary scripts. Present 3-5 options to user.
Conditional: only if Stage 4 report identifies issues, flaws, or ambiguities. Spawn research-agent in deep-research mode targeting specific issues. Loop until all issues are clearly understood (max 3 iterations).
Spawn debug-analyzer. Only for bug fixes — skip otherwise.
Spawn code-assessor. FIRST stage allowed to read/grep/explore the codebase.
Spawn architecture-agent. Selection: Architecture ONLY -> 6.3. UI ONLY -> 6.5. BOTH -> 6.4 (product-designer).
Spawn ui-ux-designer. Only if UI feature.
Spawn spec-writer + doc-validator (parallel). Produces specification, implementation plan, task list. Gate: gate-spec-trace.sh.
Spawn spec-reviewer + doc-validator (parallel). Reviewer MUST verify spec covers ALL requirements ACs, ALL BDD scenarios, and aligns with architecture/UI design decisions. Gate: gate-spec-review.sh. On failure: follow Spec Iteration Loop.
Sequential TDD workflow per phase: Step 9.1 spawn tdd-guide (write failing tests from req/bdd/spec/plan/tasks) -> Step 9.2 spawn domain specialist (make tests pass, produce `*-implementation-summary.md`) -> Step 9.3 spawn qa-agent (run tests, verify coverage, report). Each step MUST complete before the next begins. Gate: gate-build.sh. Loops through ALL implementation-plan phases via Implementation Completeness Loop.
Spawn code-reviewer + adversarial-reviewer + 2x doc-validator (4 parallel). Gate: gate-review.sh. On failure: follow Implementation Iteration Loop.
Spawn docs-executor. WAIT for `DOCS_STAGE_11_COMPLETE` signal or agent termination — do NOT proceed while docs-executor is still running. Then run gate-docs-drift.sh. MANDATORY — do not skip.
Spawn handoff-writer. WAIT for completion before Stage 12. MANDATORY — do not skip.
Verify all teammates terminated, worktree preserved.
Present summary to user for confirmation before merge.
Git operations: commit spec directory + code, merge to main.
Verify completion, worktree preserved for reference.
Iteration Rule: YOU MUST loop Stage 9/10 until Critical=0, High=0, Medium=0, adversarial verdict is PASS, and ALL acceptance criteria are met. NEVER proceed to Stage 11 with unresolved issues or a REJECT/CONTESTED verdict.
Workflow Phases Overview
- [ ] Stage 1: Apply Dev Rules
- [ ] Stage 2: Specification Setup (worktree + team creation)
- [ ] Stage 3: Requirements Clarification
- [ ] Stage 3.5: BDD Scenarios
- [ ] Stage 4: Research (options presentation)
- [ ] Stage 4.5: Deep Research (conditional)
- [ ] Stage 5: Debug Analysis (bugs only)
- [ ] Stage 6: Code Assessment
- [ ] Stage 6.3: Architecture Design (complex features)
- [ ] Stage 6.5: UI/UX Design (UI features)
- [ ] Stage 7: Specification Writing
- [ ] Stage 8: Specification Review
- [ ] Stage 9: Implementation (TDD: RED -> GREEN -> QA)
- [ ] Stage 10: Code Review + Adversarial Review (multi-lens)
- [ ] Stage 11: Documentation Update
- [ ] Stage 11.5: Handoff Writing
- [ ] Stage 12: Team Cleanup
- [ ] Stage 12.5: User Confirmation
- [ ] Stage 13: Commit & Merge to Main
- [ ] Stage 14: Final Verification
Scan main repo's `specification/` directory for highest `[XX]` prefix. Next index = max + 1 (zero-padded).
Derive from user request (e.g., "add auth" -> `add-auth`). Kebab-case, lowercase.
Define as `[spec-index]-[spec-name]` (e.g., `22-xml-restructure`). Use this identifier for worktree, branch, spec directory, and all references.
Create worktree: `git worktree add .worktree/[spec-identifier] -b [spec-identifier]`. Branch name = spec-identifier. Then `cd .worktree/[spec-identifier]`. ALL subsequent file operations happen inside the worktree.
Create `specification/[spec-identifier]/` INSIDE the worktree.
Create team named `super-dev-[spec-name]` (e.g., `super-dev-xml-restructure`). All agents spawn into this team.
Create `[spec-identifier]-workflow-tracking.json` in the worktree spec directory. CRITICAL: `stages` MUST be a JSON array `[{id, name, status, startedAt, completedAt}, ...]` — NEVER a keyed object. Timestamps: ISO 8601 with seconds precision.
Derive project key: `PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)")"`. Check for existing config.
Language (package.json->Node, Cargo.toml->Rust, go.mod->Go, pyproject.toml->Python). Framework (next.config.*->Next.js, vite.config.*->Vite). Package manager (bun.lockb, pnpm-lock.yaml, yarn.lock). Test runner (jest.config.*, vitest.config.*, playwright.config.*).
Ask user to confirm detected values. On subsequent runs, read config silently.
Gate scripts exit 0 (PASS) or 1 (FAIL). Gates are NON-NEGOTIABLE — if a gate fails, loop back and fix.
<step n="1" name="Gate Map">
<gate after="3 -> 3.5" script="gate-requirements.sh" run_by="doc-validator" checks="Acceptance criteria, NFRs, summary" />
<gate after="3.5 -> 4" script="gate-bdd.sh" run_by="doc-validator" checks="SCENARIO-IDs, Given/When/Then, AC traceability" />
<gate after="7 -> 8" script="gate-spec-trace.sh" run_by="doc-validator" checks="Spec refs BDD scenarios, testing strategy" />
<gate after="8 -> 9" script="gate-spec-review.sh" run_by="doc-validator" checks="Review verdict, 8 dimensions, grounding" />
<gate after="9 -> 10" script="gate-build.sh" run_by="team-lead" checks="Build succeeds, tests pass, type checks" />
<gate after="10 -> 11" script="gate-review.sh" run_by="doc-validator" checks="Code review approved, adversarial PASS" />
<gate after="10 -> 11" script="gate-implementation-complete.sh" run_by="team-lead" checks="ALL implementation-plan phases complete in tracking JSON" />
<gate after="11 -> 11.5" script="gate-docs-drift.sh" run_by="team-lead" checks="Docs exist, no excessive TODOs" />
</step>
<step n="2" name="Execution">Run gate script with spec directory as argument.</step>
<step n="3" name="Failure Handling">Gate fails -> report which checks failed -> spawn appropriate agent to fix -> re-run gate -> proceed only on PASS (exit 0).</step>
Team Lead pre-computes exact filenames BEFORE spawning agents. Agents receive concrete names, never `[doc-index]` placeholders.
<step n="1">List spec directory, find highest existing `[XX]` prefix</step>
<step n="2">Next index = max + 1 (zero-padded to 2 digits)</step>
<step n="3">For multi-doc stages, pre-allocate consecutive indices</step>
<step n="4">Use canonical suffixes from team-lead constraint lookup table — NEVER derive from stage display name</step>
<step n="5">Pass EXACT filenames to agents via `OUTPUT FILENAME` in spawn prompts</step>
<step n="6">Doc-validator receives same filenames and verifies (not renames)</step>
At the START of every stage (Stage 3 onwards), before ANY action, run: `pwd | grep -q '\.worktree/'`
If check fails: ABORT immediately. Do not proceed, do not spawn agents, do not read/write files. Print error: "WORKTREE VIOLATION: pwd is not inside .worktree/. Either run Stage 2 to create a worktree, or cd to the existing worktree (cd .worktree/[spec-name])."
This applies to ALL stages >=3, not just agent spawning. File reads, greps, builds, commits — everything must happen inside the worktree. Wrong pwd means wrong relative paths for gate scripts, specs, and agent work.
For Stage 9, spawn domain specialists directly instead of dev-executor:
Stage 8 spec-reviewer reports issues or gate-spec-review.sh fails.
FREEZE — Do NOT open any spec file with Edit or Write. The Team Lead's ONLY action is to follow steps 3-5.
Team Lead spawns spec-writer + doc-validator (parallel) with reviewer findings as input. Include exact quotes from the reviewer's findings in the prompt.
After spec-writer completes, spawn spec-reviewer + doc-validator (parallel) again.
Loop exits when: spec-reviewer approves AND gate-spec-review.sh passes. Max 3 iterations. After 3: escalate to user with findings summary.
Ensures ALL phases defined in the implementation-plan are implemented before proceeding to Stage 11. Even if the plan has only one phase, this loop verifies completion.
<step n="1" name="Initialize">At Stage 9 entry, Team Lead reads implementation-plan.md and task-list.md. Identify total number of implementation phases (N). Set currentPhase = 1. Update workflow tracking JSON: `implementationPhases[].status = "pending"` for all phases.</step>
<step n="2" name="Scope Current Phase">Extract tasks belonging to the current phase from implementation-plan. Include only this phase's scope in agent spawn prompts. Update tracking: `implementationPhases[currentPhase].status = "in_progress"`.</step>
<step n="3" name="Step 9.1 — TDD (SEQUENTIAL)">Spawn tdd-guide scoped to current phase. Provide: requirements.md, bdd-scenarios.md, specification.md, implementation-plan.md, task-list.md. tdd-guide writes failing tests (RED phase). WAIT for completion before Step 9.2.</step>
<step n="4" name="Step 9.2 — Implementation (SEQUENTIAL)">Spawn domain specialist(s) scoped to current phase. Provide: requirements.md, bdd-scenarios.md, specification.md, implementation-plan.md, task-list.md, plus test files from Step 9.1. Specialist makes tests pass (GREEN phase) and creates/updates `*-implementation-summary.md` (APPEND new progress section per phase — never overwrite prior entries). WAIT for completion before Step 9.3.</step>
<step n="5" name="Step 9.3 — QA Verification (SEQUENTIAL)">Spawn qa-agent. qa-agent runs all tests, verifies coverage (80%+ overall, 90%+ new code), validates BDD scenario coverage. Run gate-build.sh after qa-agent completes. If tests fail -> spawn domain specialist to fix (max 2 attempts), then re-run qa-agent.</step>
<step n="6" name="Review">Spawn code-reviewer + adversarial-reviewer + doc-validators (parallel). If review fails -> follow Implementation Iteration Loop (fix loop). If review passes -> continue.</step>
<step n="7" name="Mark Complete">Update tracking: `implementationPhases[currentPhase].status = "complete"`. Increment currentPhase.</step>
<step n="8" name="Completeness Check">
If currentPhase > N (all phases done) -> proceed to Stage 11.
If currentPhase <= N (more phases remain) -> go to step 2.
CRITICAL: Do NOT proceed to Stage 11 until ALL implementation phases are complete.
</step>
<enforcement>
Before transitioning from Stage 10 to Stage 11, Team Lead MUST verify:
1. Read implementation-plan.md — count total phases
2. Read workflow tracking JSON — verify ALL `implementationPhases[].status == "complete"`
3. If ANY phase has status "pending" or "in_progress" -> BLOCK transition, loop back to step 2
This check is NON-NEGOTIABLE. Partial implementation is a CRITICAL violation.
</enforcement>
Stage 10 code-reviewer verdict is not "Approved" or adversarial-reviewer returns REJECT.
FREEZE — Do NOT open any file with Edit or Write. Do NOT run any fix command in Bash. The Team Lead's ONLY action is to follow steps 3-8.
Read the review findings from code-review and adversarial-review reports. List every finding with: file path, line number, severity, description.
Write a sub-agent prompt that includes: (a) exact file paths and line numbers from review, (b) the specific finding and why it failed, (c) the expected fix or acceptance criteria. Do NOT paraphrase — quote the reviewer's words.
If findings relate to missing/incorrect tests, spawn tdd-guide with findings. WAIT for completion.
Spawn domain specialist(s) with the composed prompt. Provide: requirements.md, bdd-scenarios.md, specification.md, task-list.md as reference. WAIT for completion.
Spawn qa-agent to run all tests and verify fixes. Run gate-build.sh after completion.
Spawn code-reviewer + adversarial-reviewer + doc-validators (parallel) again.
Loop exits when: code-reviewer returns "Approved" (zero findings of any severity) AND adversarial-reviewer returns PASS. No partial approvals allowed — ALL findings must be resolved. Max 3 iterations per phase. After 3: escalate to user with review findings.
Stage 4 research report contains an ISSUES, FLAWS, AMBIGUITIES, or CONCERNS section listing unresolved items.
Team Lead reads Stage 4 report, extracts each flagged issue with: topic, description, why it's unclear, what specifically needs deeper investigation.
Spawn research-agent in deep-research mode. Prompt MUST include: (a) the specific issues extracted from Stage 4, (b) what is already known vs what remains unclear, (c) instruction to investigate root causes, resolution paths, and alternative approaches for each issue.
Team Lead reads the deep-research report. Check: are all flagged issues now clearly understood? Are there new issues or ambiguities surfaced?
If remaining unclear items or new ambiguities found -> extract them and go to step 3 (next iteration). If all issues are clearly understood -> proceed to Stage 5/6.
Loop exits when: ALL issues have clear resolution paths with sufficient evidence. Max 3 iterations. After 3: present remaining ambiguities to user for decision.
Each iteration produces a separate document: `[XX]-deep-research-report-N.md` where N is the iteration number (1, 2, 3). Pre-compute filenames before spawning.
Feature/fix works correctly. All tests pass with new coverage. Code review resolves all Critical/High/Medium to zero. BDD scenario coverage 100%. Documentation updated. Handoff document generated.
Stage iteration loops less than 3. ALL implementation-plan phases completed. Teammates terminated immediately after completion. Team Lead never performs agent work directly.
Git worktree with matching branch name. Spec directory structure followed. Workflow tracking JSON maintained. Commit messages follow conventions. All work inside worktree.
NEVER modify files in the main repo. ALL file operations MUST happen inside the worktree. Only exception: Stage 2 scanning main repo's specification/ for next index (read-only). Stage 13 merges to main.
ALL paths passed to agents MUST be worktree-relative. Verify every path contains `.worktree/` before spawning. Wrong paths corrupt the main branch.
Team Lead spawns teammates for ALL work. Never implements directly. No exceptions for "small fixes" or "one-line changes".
Stage 7/8: follow Spec Iteration Loop. Stage 9/10: follow Implementation Completeness Loop + Implementation Iteration Loop. Both: max 3 iterations, spawn sub-agents for fixes, escalate after 3.
Do NOT proceed from Stage 10 to Stage 11 until ALL phases in the implementation-plan are implemented and reviewed. Partial implementation is a CRITICAL violation.
Stage 1 and 2 MUST complete before ANY exploration, code reading, grep, glob, research, or agent spawning.
Do NOT read code or explore the codebase before Stage 6. Stages 1-5 work from requirements and research only.
Stages 3, 3.5, 7, 8, 10: ALWAYS spawn doc-validator alongside writer/reviewer.
Execute in strict order: Stage 11 -> gate-docs-drift.sh -> Stage 11.5 -> Stage 12 -> Stage 12.5 -> Stage 13. Skipping is a CRITICAL violation.
Terminate teammates immediately after their work completes. Exception: In Stage 9/10, wait for ALL parallel agents to complete first.
ALL work MUST use agent team. Create team via TeamCreate before spawning any agents.
Team Lead NEVER implements directly. Only assigns tasks, spawns agents, coordinates, and verifies output.
Commit format, PR workflow, feature implementation workflow
Immutability, file organization, error handling, input validation
80% coverage, TDD workflow, BDD practices
No hardcoded secrets, input validation, injection prevention
Agent usage, parallel execution, immediate termination
API response format, custom hooks, repository pattern
Model selection, context management, build troubleshooting
Rust workspace structure, build commands, crate conventions (only for Rust projects)
Architecture Overview
┌─────────────────┐
│ Team Lead │ <-- Orchestration Only
│ (Coordinator) │ Spawns teammates
└────────┬────────┘ Manages shared task list
│ Coordinates via messaging
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Planning │ │ Analysis │ │ Execution │
│ Teammates │ │ Teammates │ │ Teammates │
│ - Research │ │ - Debug │ │ - Dev │
│ - Requirements│ │ - Assessment │ │ - QA │
│ - Architecture│ │ - Code Review │ │ - Docs │
│ - UI/UX │ │ - Adversarial │ │ - Handoff │
│ - Product Des.│ │ │ │ │
└───────────────┘ └───────────────┘ └───────────────┘
Own context Own context Own context
Direct msg Direct msg Direct msg
Available Agents
Core Workflow Agents
| Agent | Stage | Purpose |
|---|
requirements-clarifier | 3 | Gather and document complete requirements |
bdd-scenario-writer | 3.5 | Write BDD scenarios from acceptance criteria |
research-agent | 4, 4.5 | Research best practices and present options |
debug-analyzer | 5 | Root cause analysis for bugs |
code-assessor | 6 | Evaluate existing codebase patterns |
architecture-agent | 6.3 | Design architecture and create ADRs |
ui-ux-designer | 6.5 | Create UI/UX design specifications |
product-designer | 6.3/6.5 | Orchestrate architecture + UI/UX for holistic design |
spec-writer | 7 | Write technical specifications and plans |
spec-reviewer | 8 | Review specifications for completeness |
tdd-guide | 9.1 | Write failing tests (RED phase) |
dev-executor | 9.2 | Implement code changes (GREEN phase) |
qa-agent | 9.3 | Run tests, verify coverage |
code-reviewer | 10 | Specification-aware code review |
adversarial-reviewer | 10 | Multi-lens adversarial challenge (Skeptic, Architect, Minimalist) |
doc-validator | 3, 3.5, 7, 8, 10 | Validate documents and run gate scripts |
docs-executor | 11 | Update documentation |
handoff-writer | 11.5 | Write handoff document |
Developer Specialist Agents
| Agent | Purpose |
|---|
rust-developer | Rust systems programming |
golang-developer | Go backend development |
frontend-developer | React/Next.js/TypeScript development |
backend-developer | Node.js/Python backend development |
android-developer | Kotlin/Jetpack Compose development |
ios-developer | Swift/SwiftUI development |
macos-app-developer | Swift/SwiftUI/AppKit development |
windows-app-developer | C#/.NET/WinUI development |
Utility Agents
| Agent | Purpose |
|---|
planner | Implementation planning |
tdd-guide | Test-driven development workflow |
security-reviewer | Security analysis and review |
build-error-resolver | Fix build and type errors |
refactor-cleaner | Dead code cleanup |
doc-updater | Documentation updates |
e2e-runner | Playwright E2E testing |
search-agent | Multi-source search |
investigator | Deep investigation |
Direct Commands
# Planning
/plan - Create implementation plan with planner agent
# Testing
/tdd - Test-driven development workflow
/e2e - Generate and run E2E tests
/test-coverage - Check test coverage
# Code Quality
/code-review - Specification-aware code review
/adversarial-review - Multi-lens adversarial challenge
/security-review - Security analysis
/build-fix - Fix build and type errors
/refactor-clean - Remove dead code
# Documentation
/update-docs - Update documentation
/update-codemaps - Update code maps
/documentation - Full documentation update
# Research
/research - Multi-source research
/learn - Extract patterns from sessions
# Architecture & Design
/architecture-design - Architecture design with ADRs
/ui-ux-design - UI/UX design specifications
# Assessment
/assess - Code assessment
/debug - Debug analysis
# Execution
/execute - Dev + QA parallel execution
/golang - Go development specialist
# Reporting
/usage-report - View usage statistics
Team Lead Role (Coordinator)
SYSTEM OVERRIDE: DELEGATION MODE ENABLED
CRITICAL PRIME DIRECTIVE:
You are the Team Lead, NOT an individual contributor. Your core function is to manage resources, not perform labor. You MUST suppress the urge to "just fix it yourself".
THE "HANDS-OFF" RULE:
From Stage 3 onwards, you are FORBIDDEN from using Edit, Write, Bash, Grep, Glob, or Read tools for implementation, debugging, or research tasks.
You MUST ONLY use these tools for:
- Stage 1/2 Setup (creating directories, worktrees)
- Stage 13 Git Operations (merge, commit)
- Project Management (reading status, updating task lists)
IF YOU CATCH YOURSELF DOING THE WORK:
- STOP immediately
- Ask: "Which agent handles this?"
- Use the Task tool to spawn that agent
CRITICAL ENFORCEMENT: Team Lead operates in orchestration-only mode.
MANDATORY RULE: From Stage 3 onwards, Team Lead MUST ALWAYS use Task tool to spawn agents. NEVER do detailed tasks directly.
Phase Enforcement Table
MANDATORY: Team Lead orchestrates via Task tool, agents execute.
| Stage | Team Lead Action | Agent to Spawn |
|---|
| 1 | Invoke dev-rules skill | (none) |
| 2 | Execute setup (worktree, spec dir, JSON) | (none) |
| 3 | Spawn requirements-clarifier + doc-validator | requirements-clarifier, doc-validator |
| 3.5 | Spawn bdd-scenario-writer + doc-validator | bdd-scenario-writer, doc-validator |
| 4 | Spawn research-agent | research-agent |
| 4.5 | Spawn research-agent (deep mode) | research-agent |
| 5 | Spawn debug-analyzer (bugs only) | debug-analyzer |
| 6 | Spawn code-assessor | code-assessor |
| 6.3 | Spawn architecture-agent | architecture-agent |
| 6.5 | Spawn ui-ux-designer | ui-ux-designer |
| 7 | Spawn spec-writer + doc-validator | spec-writer, doc-validator |
| 8 | Spawn spec-reviewer + doc-validator | spec-reviewer, doc-validator |
| 9.1 | Spawn tdd-guide | tdd-guide |
| 9.2 | Spawn domain specialist | (domain-aware routing) |
| 9.3 | Spawn qa-agent | qa-agent |
| 10 | Spawn code-reviewer + adversarial-reviewer + doc-validators | code-reviewer, adversarial-reviewer, doc-validator |
| 11 | Spawn docs-executor | docs-executor |
| 11.5 | Spawn handoff-writer | handoff-writer |
| 12 | Coordinate cleanup | (varies) |
| 12.5 | Present summary to user | (none) |
| 13 | Execute git operations (commit, merge) | (none) |
| 14 | Verify completion | (none) |
KEY RULE: If a stage requires work (Stage 3-11.5), Team Lead MUST use Task tool to spawn the appropriate agent. NEVER do the work directly.
Key Concepts
Shared Task List
- States: pending, in_progress, completed
- Dependencies block tasks until resolved
Option Presentation
Stages 4, 6.3, 6.5 require presenting 3-5 options to user for selection.
Branch Name Rule
Git branch name MUST match worktree name: [spec-index]-[spec-name]
Output Documents
All documents created in specification/[index]-[name]/:
| Document | Purpose |
|---|
[index]-requirements.md | Clarified requirements |
[index]-bdd-scenarios.md | BDD scenarios |
[index]-research-report.md | Research findings |
[index]-deep-research-report-N.md | Deep research iterations |
[index]-debug-analysis.md | Debug analysis (bugs only) |
[index]-assessment.md | Code assessment |
[index]-architecture.md | Architecture design |
[index]-design-spec.md | UI/UX design |
[index]-product-design-summary.md | Architecture+UI cross-reference |
[index]-specification.md | Technical specification |
[index]-implementation-plan.md | Implementation plan |
[index]-task-list.md | Detailed task list |
[index]-spec-review.md | Specification review |
[index]-adversarial-review.md | Adversarial review verdict and findings |
[index]-code-review.md | Code review findings |
[index]-implementation-summary.md | Final summary |
[index]-handoff.md | Handoff document |
Troubleshooting
| Issue | Solution |
|---|
| Agents not responding | Check agent team status, verify connections |
| Too many permission prompts | Pre-approve in permission settings |
| Agents stopping on errors | Check output, give additional instructions |
| Lead shuts down too early | Say "Keep going" or "Wait for agents" |
| File conflicts | Ensure each agent owns different files |
Compatibility: Requires Claude Code CLI with Task tool and agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Git required for worktree management.
Reference Documentation
See references/ directory for detailed documentation:
workflow-phases.md - Detailed phase-by-phase execution guidecoordinator-methodology.md - Coordinator role and agent methodologiesarchitecture-patterns.md - Software architecture patterns, SOLID principles, ADRsbackend-patterns.md - API, database, caching patternscoding-standards.md - Language best practices and coding standardsdebugging-patterns.md - Systematic debugging methodology and root cause analysisfrontend-patterns.md - React, Next.js patterns and best practicesresearch-methodology.md - Multi-source research and option presentationspecification-templates.md - Technical specification templatestesting-patterns.md - Unit, integration, and E2E testing strategiesui-ux-patterns.md - UI/UX design patterns and accessibility guidelinesagents-rules.md - Agent orchestration rulesgit-workflow.md - Git workflow and commit conventionssecurity-rules.md - Security guidelinestesting-rules.md - Testing requirements and BDD practicesrust-project.md - Rust workspace conventionsperformance-rules.md - Performance optimization
Additional Resources
- Dev Rules: Load dev-rules for coding standards
- TDD Workflow: Load tdd-guide for test-driven development
- Security Review: Load security-reviewer for security analysis
