super-dev

name	super-dev
description	Multi-step development orchestrator for implementing features, fixing bugs, refactoring, optimizing performance, and resolving deprecations
author	Jennings Liu
version	2.7.0
license	MIT

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.

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. 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 using template from `${CLAUDE_PLUGIN_ROOT}/templates/reference/workflow-tracking-template.json`. 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 `${CLAUDE_PLUGIN_DATA}/projects/${PROJECT_NAME}/config.json`. 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. Write config to `${CLAUDE_PLUGIN_DATA}/projects/${PROJECT_NAME}/config.json` (include `project.path` for collision detection). On subsequent runs, read config silently. Gate scripts in `${CLAUDE_PLUGIN_ROOT}/scripts/gates/` 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">`bash ${CLAUDE_PLUGIN_ROOT}/scripts/gates/<gate-name>.sh <spec-dir>`</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. Every modification to super-dev-plugin files requires patch version bump in plugin.json and marketplace.json. 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) Plugin root: `${CLAUDE_PLUGIN_ROOT}` — agents, commands, rules, contexts, skills, templates, scripts Plugin data: `${CLAUDE_PLUGIN_DATA}` — global stats, learned patterns, autoresearch results Compatibility: Requires Claude Code CLI with Task tool and agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Git required for worktree management.