147 Workflow 3d22b270

Planning, Reviewing, and Implementing Workflow

How the planning skills work together as an assembly line — from feature idea to shipped code.

The Pipeline

/create-plan → /audit-plan → /review-plan → /implement → done
                                                │
                                                ├── gate: plan review + flow audit
                                                │
                                                └── for each group (sequential):
                                                    │
                                                    ├── build phases (parallel where deps allow, max 2):
                                                    │   spawn builder ──→ builder-workflow
                                                    │        │              ├── find reference
                                                    │        │              ├── invoke domain skill
                                                    │        │              ├── TDD → implement → test
                                                    │        │              └── report completion
                                                    │        │
                                                    │   orchestrator ──→ validator
                                                    │        │              ├── validator-workflow
                                                    │        │              ├── /code-review + auto-fix
                                                    │        │              ├── tests + typecheck + E2E/DB
                                                    │        │              └── PASS / FAIL verdict
                                                    │        │
                                                    │   PASS → next phase / FAIL → fresh builder
                                                    │
                                                    ├── all group phases done → spawn auditor
                                                    │   auditor ──→ auditor-workflow
                                                    │        ├── cross-phase regressions
                                                    │        ├── deferred items check
                                                    │        ├── tests + typecheck
                                                    │        ├── plan vs reality
                                                    │        └── severity-rated report
                                                    │
                                                    └── orchestrator triages:
                                                        ├── Clean/Low → continue to next group
                                                        ├── Medium → auto-fix (builder + validator)
                                                        └── High/Critical → ask user

/audit-plan (runs during /create-plan Step 6 for 3+ phase plans, BEFORE per-phase reviews)

Each skill has hard gates preventing progression until quality is met. Every guardrail exists because skipping it caused hours of rework in real usage.

1. /create-plan — The Orchestrator

Files: SKILL.md (416 lines) + references/PLAN-TEMPLATE.md + references/PHASE-TEMPLATE.md + references/delegation-guide.md

What it does: Acts as a thin dispatcher that clarifies requirements with the user, spawns an ephemeral planner agent for plan/phase creation, then spawns validators for review. The orchestrator does NOT read templates, explore the codebase, or create files — the planner handles all planning work via the preloaded planner-workflow skill.

Architecture

The 9-step workflow

Key design decisions

• Thin dispatcher — orchestrator stays lean (only messages + plan.md), all heavy lifting in planner with fresh 200K context
• Two user checkpoints — plan summary reviewed before writing phases, phase completion reviewed before spawning validators
• Ephemeral planner — fresh context prevents skill compaction and context contamination
• Phases are atomic — each should fit in 1 context window (15KB). "30 small phases > 5 large phases"
• TDD is Step 0 in every phase, not an afterthought
• skill: in frontmatter tells the builder which domain skill to invoke (e.g., postgres-expert, server-action-builder)
• Validators run inline during creation — validate_no_placeholders.py, validate_tdd_tasks.py, validate_new_file.py
• Templates are canonical — /review-plan reads from ../create-plan/references/ (single source of truth)

2. /review-plan — The Quality Gate

Files: SKILL.md (346 lines) + checklist.md (400 lines) + delegation.md + PLAN-REVIEW-TEMPLATE.md + scripts/validate_review.py

Templates: Reads PLAN-TEMPLATE.md and PHASE-TEMPLATE.md from ../create-plan/references/ (no local copies).

What it does: Reviews ONE file per invocation (plan.md OR a single phase). Performs a two-layer review:

The codebase compliance layer

For each code block in a phase, the reviewer:

1. Classifies the phase type (schema, service, server action, component)
2. Globs for a real reference file of that type in the codebase
3. Reads the reference as ground truth
4. Compares each code block against it
5. Flags deviations with severity (Critical/High/Medium/Low)

12 codebase checks (from checklist.md)

1. Naming conventions (singular schema/, Action suffix, kebab-case components)
2. Server Action pattern ('use server' + Zod + getSession())
3. Account resolution (slug to ID lookup, permission RPC)
4. Import patterns (server-only, path aliases, correct sources)
5. TypeScript compliance (interfaces, factory pattern, type guards)
6. Service factory patterns (private class + exported factory)
7. Export patterns (no server actions in barrel exports)
8. Error handling (generic external, detailed internal)
9. CLAUDE.md rules (no doc creation, revalidatePath, directives)
10. SQL safety (IF EXISTS, RLS enabled, no USING(true))
11. Test infrastructure (correct paths, it.todo(), happy-dom, mocks)
12. Consistency (status match, naming across steps)

Auto-fix

Critical, High, and Medium issues are fixed directly in the phase file. The review file gets "(Auto-fixed)" annotations. Only genuine scope changes or ADR contradictions are deferred.

Review format validation

After writing, scripts/validate_review.py checks the review file structure (required sections, table format, forbidden patterns). This deterministic check catches format issues that prose instructions miss.

Delegation model

When /create-plan spawns review agents, the delegation.md enforces:

• Max 4 concurrent agents (more causes context blowout)
• One file per agent (multiple files produce superficial reviews)
• Explicit skill invocation in the prompt (vague prompts cause agents to skip the skill)

3. /implement — The Thin Dispatcher

Files: SKILL.md (490 lines) + references/team-operations.md

What it does: Acts as a thin dispatcher that processes phases in groups — connected phases that build the same feature area. For each group: spawns ephemeral builders and validators per phase, then an auditor for cross-phase analysis. It does NOT read references, extract patterns, or implement code — builders, validators, and auditors handle their respective work via preloaded skills.

Architecture

Processing model

for each group (sequential):
  1. Gate check all phases in group
  2. Build phases (parallel where deps allow, max 2)
  3. Validate each phase (PASS/FAIL routing)
  4. When all group phases PASS → spawn auditor
  5. Orchestrator reads auditor report and triages:
     - Clean/Low → log deviations, continue to next group
     - Medium → auto-spawn builder + validator to fix
     - High/Critical → checkpoint with user, then fix
  6. Track deviation summary for next group's auditor

The 10-step workflow

Step 1: Read plan.md + check plan review verdict
        ↓ (blocks if verdict is "No")
Step 2: Check flow audit exists (created by /create-plan)
        ↓ (blocks if "Unusable" or "Major Restructuring Needed")
Step 3: Parse groups from Phase Table + Group Summary
        - Build execution plan: group order, phase dependencies
        - TaskCreate per phase with group + dependency metadata
        ↓
Step 4: Gate check each phase in current group:
        - validate_no_placeholders.py
        - /review-plan phase review verdict
        ↓ (blocks if skeleton content or Critical issues)
Step 5: Create team (first group only)
        - TeamCreate, reused across all groups
        ↓
Step 6: Spawn builders for unblocked phases (parallel, max 2)
        - Fresh builder per phase with clean 200K context
        - Minimal prompt: phase file path + plan folder + domain skill
        - builder-workflow skill handles the rest
        ↓
Step 7: Wait for builder completions → spawn fresh validator per phase
        ↓
Step 8: Handle verdict:
        - PASS → update plan.md + task (completed), shutdown builder + validator
        - FAIL → shutdown builder + validator, spawn fresh builder with fix instructions
        - When all group phases PASS → spawn auditor (runs alone)
        ↓
Step 9: Triage auditor findings:
        - Clean/Low → log deviation summary, continue to next group
        - Medium → auto-spawn builder + validator to fix (no user input)
        - High/Critical → checkpoint with user, present findings, ask for direction
        - Pass deviation summary to next group's auditor
        ↓ (loop back to Step 4 for next group)
Step 10: Cleanup (all groups done or error breakout)
         - Shutdown all teammates
         - TeamDelete

Concurrency limits

Why builders, validators, and auditors are ephemeral

Each phase gets a fresh builder and validator, each with a clean 200K context window. After the review cycle completes (PASS or FAIL resolution), both are shut down. After all group phases pass, an auditor gets a fresh context for cross-phase analysis. This prevents:

• Context contamination — bad patterns from phase 2 don't bleed into phase 3
• Skill instruction compaction — the builder-workflow skill is always fully loaded
• Stale reference data — each builder reads fresh references for its phase type
• Validator bottleneck — parallel builders each get their own validator instead of queuing for a single persistent one
• Drift snowballing — group auditors catch issues incrementally rather than after 20 phases

Cross-group deviation tracking

Each auditor receives a summary of previous groups' deviations in its spawn prompt. This creates a chain of awareness — if the "auth-system" group had naming inconsistencies, the "dashboard-ui" auditor specifically checks whether dashboard phases compound that drift.

What the orchestrator does NOT do

Hard gates that block implementation

• Flow audit says "Unusable" or "Major Restructuring Needed" → STOP
• Plan review verdict is "No" → STOP
• Phase has placeholder content ([To be detailed], TBD) → STOP
• Phase review has Critical/High issues → FIX phase first
• Validator FAIL repeats 3+ times on same phase → STOP, report to user

4. /builder-workflow — The Builder's Playbook

Files: SKILL.md (190 lines) — preloaded into builder agents via skills: [builder-workflow] in agent config

What it does: Teaches builders how to handle an entire phase end-to-end. Not user-invocable — it activates automatically when a builder is spawned.

The 7-step workflow

Domain skill mapping

Context compact recovery

If a builder's context is compacted mid-phase (rare with fresh 200K windows):

1. TaskList → find the in_progress or first pending task
2. TaskGet → read the self-contained description
3. Continue from that task — don't restart the phase

5. /validator-workflow — The Validator's Playbook

Files: SKILL.md (139 lines) — preloaded into validator agents via skills: [validator-workflow] in agent config

What it does: Teaches validators how to handle validation end-to-end. Not user-invocable — it activates automatically when a validator is spawned.

The 6-step workflow

Conditional testing by phase type

The phase's skill: frontmatter field routes to additional test commands:

E2E tests are scoped by extracting keywords from the phase title and globbing for matching spec files. Commands that don't exist are skipped gracefully.

6. /code-review — The Final Gate

Files: SKILL.md (317 lines) + checklist.md (451 lines) + delegation.md + references/CODE-REVIEW-TEMPLATE.md + scripts/validate_review.py

What it does: Called by the validator (independent review after each phase) to review actual code against codebase reference files, security requirements, and the phase's acceptance criteria. The builder never reviews its own code — this separation catches blind spots that self-review misses.

Dynamic context injection

The skill automatically injects recent git activity when loaded:

!`git log --oneline -10`         → recent commits
!`git diff --name-only HEAD~5`   → recently changed files

This helps the reviewer identify which files were modified without needing to ask.

The 8-step workflow

The checklist (451 lines, 15+ categories)

• Part 1 — Completeness: TDD check, each implementation step verified, frontend test requirements
• Part 2 — Code Quality: TypeScript standards (11 checks), React/Next.js compliance (12 checks), React forms (detailed sub-checks), project architecture, database security & RLS, server actions & API routes, import patterns, Zod schemas, testing standards, E2E testing, Vercel performance patterns

For React/Next.js code, the reviewer loads /vercel-react-best-practices (57 performance rules) and checks against Critical, High, and Medium priority rules.

Auto-fix

Critical and High issues are fixed directly in source files. The review file gets "(Auto-fixed)" annotations. Only genuine business logic changes or ADR contradictions are deferred.

Output goes to reviews/code/phase-NN.md (separate from planning reviews in reviews/planning/).

7. /audit-plan — The Structural Gate

Files: SKILL.md (340 lines)

Different from /review-plan: This is a structural design audit, not a template check. It analyzes the plan as a whole and runs BEFORE per-phase reviews:

What it catches

• Circular dependencies between phases
• Missing/unnecessary dependency declarations
• Data flow inconsistencies (phases disagree on table names, patterns)
• Ordering issues (consumer runs before producer)
• Stale artifacts (deprecated files, mismatched statuses, broken links)
• Fundamentally broken plans (bail-out with "Unusable" verdict)

Bail-out mechanism

If the plan is fundamentally broken (circular deps, no coherent execution order, >50% missing dependencies), the audit bails out immediately with an "Unusable" verdict instead of completing the full analysis. This saves the user from waiting through a full audit of a plan that needs to be thrown out and rewritten.

Integration with /create-plan and /implement

The /create-plan skill runs /audit-plan as Step 6 for plans with 3+ phases — BEFORE spawning review validators. This prevents wasting time reviewing phases that have structural design issues. The /implement orchestrator then gate-checks that the audit exists (Step 2) — if missing, it stops and asks the user to run the audit first. Results gate both reviews and implementation:

8. Group Auditing — The Incremental Post-Mortem

Files: auditor-workflow/SKILL.md (internal, preloaded into auditor agent) + agents/team/auditor.md

What it does: After each group of connected phases completes the build/validate cycle, an auditor reviews the group for problems that per-phase reviews structurally cannot catch. This happens incrementally — audit after each group, not after the whole plan — so drift is caught early while it's still cheap to fix.

How it differs from other review steps

What the auditor checks

How the orchestrator triages

Cross-group deviation tracking

Each auditor receives a summary of previous groups' deviations in its spawn prompt. This creates a chain of awareness — if the "auth-system" group had naming inconsistencies, the "dashboard-ui" auditor specifically checks whether dashboard phases compound that drift.

Output location

{plan-folder}/reviews/implementation/group-{name}-audit.md — one report per group. Lives alongside planning reviews (reviews/planning/) and code reviews (reviews/code/).

End-to-End Example

User: "/create-plan add notes feature"
  ├─ Clarify → AskUserQuestion
  ├─ Spawn planner agent (Opus, fresh 200K context)
  │   ├─ Read templates (PLAN-TEMPLATE.md, PHASE-TEMPLATE.md)
  │   ├─ Read codebase references (server-actions.ts, service.ts, etc.)
  │   ├─ Write plan.md with Phase Table + Group Summary
  │   ├─ Checkpoint 1 → orchestrator relays to user for review
  │   ├─ User approves → create phase-01.md through phase-05.md
  │   │   Groups: "data-layer" (P01-P02), "api-layer" (P03-P04), "ui-layer" (P05)
  │   ├─ Self-validate each phase (no placeholders, TDD ordering, files exist)
  │   └─ Checkpoint 2 → orchestrator relays completion summary
  ├─ Flow audit (/audit-plan) → structural design checks pass (deps, ordering, data flow)
  ├─ Spawn review agents in batches of 4
  │   └─ Each agent calls: /review-plan plans/250214-notes phase NN
  │       ├─ Template compliance (12/12 sections?)
  │       ├─ Codebase compliance (code blocks match real patterns?)
  │       └─ Auto-fix Critical/High/Medium issues in phase files
  └─ All reviews pass → ready for /implement

User: "/implement plans/250214-notes"
  ├─ Check plan review verdict → must be "Yes"
  ├─ Check flow audit → "Coherent" or "Minor Issues"
  ├─ Parse groups from Phase Table + Group Summary
  │
  ├─ GROUP 1: "data-layer" (P01, P02 — no inter-dependencies)
  │   ├─ Gate check both: no placeholders, phase reviews pass
  │   ├─ TeamCreate (first run only)
  │   ├─ Spawn builders in parallel (max 2 per batch)
  │   │   ├─ builder-1: Phase 01 → /postgres-expert → TDD → verify → "done"
  │   │   └─ builder-2: Phase 02 → /service-builder → TDD → verify → "done"
  │   ├─ As each completes → spawn fresh validator → /code-review → PASS
  │   ├─ All group phases done → shutdown builders + validators
  │   ├─ Spawn auditor (Opus, runs alone)
  │   │   ├─ Read both phases + their code reviews
  │   │   ├─ Cross-phase: notes-service.ts touched by P01 migration + P02 service
  │   │   ├─ Run tests + typecheck
  │   │   ├─ Write report → reviews/implementation/group-data-layer-audit.md
  │   │   └─ Verdict: "No Issues" → continue
  │   └─ Shutdown auditor → proceed to next group
  │
  ├─ GROUP 2: "api-layer" (P03, P04 — P04 depends on P03)
  │   ├─ Build P03 first → validate → PASS
  │   ├─ P04 unblocked → build → validate → PASS
  │   ├─ Spawn auditor (receives data-layer deviation summary)
  │   │   ├─ Finding: Medium — missing error handling in action (P03:L42)
  │   │   └─ Report → reviews/implementation/group-api-layer-audit.md
  │   ├─ Orchestrator triages: Medium → auto-fix
  │   │   ├─ Spawn builder with fix instructions → validator → PASS
  │   │   └─ Mark fix task complete
  │   └─ Shutdown auditor → proceed to next group
  │
  ├─ GROUP 3: "ui-layer" (P05 — depends on P03)
  │   ├─ Build P05 → validate → PASS
  │   ├─ Spawn auditor (receives data-layer + api-layer deviations)
  │   │   └─ Verdict: "No Issues"
  │   └─ Shutdown auditor
  │
  └─ All groups done → TeamDelete → cleanup → final summary

Quality Layers

Quality checks execute in this order during implementation:

Key Design Principles

Thin dispatcher + smart workers

The orchestrator's context budget stays lean — it only holds plan.md and teammate messages. All heavy lifting (reading references, invoking skills, implementing, reviewing) happens in builders with fresh 200K context windows. This prevents the orchestrator from hitting context limits on large plans.

Ephemeral builders, validators, and auditors

All agents are spawned fresh and shut down after their cycle completes — builders per phase, validators per phase, auditors per group. This prevents context contamination, ensures skill instructions are always fully loaded (never compacted), and eliminates bottlenecks when multiple builders run in parallel.

Reviews folder separation

reviews/planning/ holds template + codebase compliance reviews from /review-plan. reviews/code/ holds post-implementation reviews from /code-review. reviews/implementation/ holds group audit reports (group-{name}-audit.md) written by the auditor after each group completes during /implement. This means you can re-review a phase after fixing issues without losing the original review, and the group audits capture the cross-phase holistic view that per-phase reviews miss — catching drift incrementally rather than at the end.

Task descriptions as survival mechanism

Builder task descriptions must be self-contained with file paths, function signatures, and acceptance criteria — because after a context compact, TaskGet on the in-progress task is ALL you have.

Bad: "Create the dropdown component" Good: "Create app/home/[account]/roles/_components/change-role-dropdown.tsx. Props: { membershipId, accountSlug }. Fetch roles via listRolesAction, filter by hierarchy_level. Use @/components/ui Select, Badge."

The "30 small > 5 large" rule

Reflects a fundamental constraint of AI-assisted development: each phase must fit in one context window. A 25-phase plan sounds excessive to humans, but for Claude it means each phase gets full attention without losing context mid-implementation.

Codebase grounding over static checklists

Both /review-plan and /code-review read actual files from the codebase before flagging issues. This prevents flagging things that are correct in this specific codebase, and catches violations that a static checklist might miss.

Single source of truth for templates

PLAN-TEMPLATE.md and PHASE-TEMPLATE.md live in /create-plan/references/ only. The /review-plan skill reads from there via relative path. One update, one location.

Skill Comparison