feat(v3.32.0): Plan-Validate-Execute Pipeline — 3-command AI-first workflow
New workflow for production teams: dynamic agent teams, ADR learning loop, automated execution from PRD to merged PR. Added: - guide/workflows/plan-pipeline.md — complete workflow guide (philosophy, non-prescriptive AI-first, No Bandaids first principles, ADR learning loop, CLAUDE.md 120-line discipline, /clear context reset, cost profile) - examples/commands/plan-start.md — 5-phase planning with 12-agent dynamic pool (trigger-based selection, Tier 0 Solo → Tier 4 Full Spectrum, planning-coordinator synthesis, auto-transition to validate) - examples/commands/plan-validate.md — 2-layer validation (structural inline + 8 specialist agents), ADR-aware auto-fix (Bucket A ~95% auto-resolve, Bucket B human input → new rule), issue persistence in metrics JSON - examples/commands/plan-execute.md — worktree → TDD scaffold → level-based parallel agents → drift detection → quality gate → smoke test → PR squash merge → post-merge metrics → cleanup - examples/agents/planning-coordinator.md — Opus synthesis agent: merges multi-agent reports into coherent task graph, resolves conflicts via ADR precedence, verifies plan completeness before output - examples/agents/integration-reviewer.md — Opus runtime validator: connection params, async/sync consistency, env var completeness, library API correctness (WebFetch), OTEL pipeline validation Updated: - machine-readable/reference.yaml — 16 new indexed keys - CHANGELOG.md — v3.32.0 entry with 6 detailed items - VERSION, README.md, guide/cheatsheet.md, guide/ultimate-guide.md — bumped to 3.32.0 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
07c3c42b03
commit
7bda706da2
12 changed files with 1349 additions and 15 deletions
180
examples/commands/plan-start.md
Normal file
180
examples/commands/plan-start.md
Normal file
|
|
@ -0,0 +1,180 @@
|
|||
---
|
||||
name: plan-start
|
||||
description: "5-phase planning command: PRD analysis, design review, technical decisions, dynamic research team, metrics. Produces a complete implementation plan + ADRs before any code is written."
|
||||
---
|
||||
|
||||
# Plan Start — 5-Phase Planning
|
||||
|
||||
Analyze the request and produce a complete implementation plan through structured phases. No code is written. Every significant decision is recorded. Run `/clear` after this command before running `/plan-validate`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: PRD & Design Analysis
|
||||
|
||||
### Step 1.1 — PRD Analysis
|
||||
|
||||
*Skip if no PRD exists (refactor, infra change, bug fix).*
|
||||
|
||||
Read all PRD files and `docs/INFORMATION_ARCHITECTURE.md` if present. Scan the codebase to understand current implementation status.
|
||||
|
||||
Surface findings in 3 buckets:
|
||||
|
||||
**Missing requirements** — acceptance criteria that are absent or incomplete
|
||||
**Ambiguous requirements** — items with multiple valid interpretations
|
||||
**Compliance concerns** — security, data privacy, API contract implications
|
||||
|
||||
For each finding: present options with concrete pros/cons. Discuss with user. Record every decision in the plan file under a `## Decisions` section before moving on. Do not proceed past unresolved ambiguities.
|
||||
|
||||
### Step 1.2 — Design Analysis
|
||||
|
||||
*Skip if no UI changes are in scope.*
|
||||
|
||||
Read: `DESIGN_SYSTEM.md`, existing UX ADRs, CLAUDE.md UX rules.
|
||||
|
||||
Produce specs for:
|
||||
- **Screen inventory**: new/modified screens, route placement, component reuse audit
|
||||
- **State catalog**: empty, loading, populated, error, and partial states for every interactive element
|
||||
- **Interaction specs**: user flows (happy path + alternates), focus/keyboard behavior
|
||||
- **Animation specs**: map each interaction to existing keyframes or specify new ones, include `prefers-reduced-motion` fallbacks
|
||||
- **Responsive behavior**: breakpoints, web/mobile divergence decisions
|
||||
- **Accessibility**: WAI-ARIA pattern selection, live regions, error visibility
|
||||
|
||||
Create Design ADRs for significant UX decisions (choice of interaction pattern, new animation convention, platform divergence). Record minor layout choices directly in the plan file.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Technical Analysis
|
||||
|
||||
Spawn 1-2 Explore agents for targeted codebase research. Run them in the background via Task tool.
|
||||
|
||||
While agents run, check:
|
||||
- Existing ADRs in `docs/adr/` — if 3+ ADRs confirm a decision → auto-resolve without asking
|
||||
- PATTERNS.md — apply confirmed patterns directly
|
||||
|
||||
When agents return: present architecture decisions with 2-3 options each, concrete pros/cons, and a recommendation. Ask for user input on each unresolved decision.
|
||||
|
||||
For each significant decision:
|
||||
1. Create `docs/adr/ADR-XXXX.md` using standard Nygard format (Context / Decision / Status / Consequences)
|
||||
2. Update `docs/adr/PATTERNS.md` with the new observation
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Scope Assessment
|
||||
|
||||
Apply trigger rules to determine which research agents are needed. Present the proposed team with justification for each inclusion.
|
||||
|
||||
**Research agent pool:**
|
||||
|
||||
| Agent | Trigger | Model |
|
||||
|-------|---------|-------|
|
||||
| `code-explorer` | Always | Sonnet |
|
||||
| `arch-researcher` | Changes touch 2+ architectural layers | Sonnet |
|
||||
| `database-analyst` | Any DB schema change | Sonnet |
|
||||
| `security-analyst` | Auth, payments, PII, RBAC, rate limiting | Opus |
|
||||
| `test-analyzer` | Non-trivial feature (not just a bug fix) | Sonnet |
|
||||
| `cross-platform-specialist` | Web + mobile parity required | Sonnet |
|
||||
| `native-app-specialist` | Tasks touch mobile/native UI package | Sonnet |
|
||||
| `design-system-researcher` | UI changes in scope | Sonnet |
|
||||
| `dependency-researcher` | New packages being added | Sonnet |
|
||||
| `devops-specialist` | Docker, env vars, CI/CD changes | Sonnet |
|
||||
| `integration-researcher` | New services, libraries, OTEL config | Opus |
|
||||
| `planning-coordinator` | Always, when 2+ agents selected | Opus |
|
||||
|
||||
**Tier labels** (descriptive, not prescriptive):
|
||||
- Tier 0 (0 agents): Solo — inline research, no spawning
|
||||
- Tier 1 (1-3 agents): Focused
|
||||
- Tier 2 (4-6 agents): Standard
|
||||
- Tier 3 (7-9 agents): Comprehensive
|
||||
- Tier 4 (10+ agents): Full Spectrum
|
||||
|
||||
Tell the user: "I recommend a **[Tier N - Label]** team: [agent list with one-line justification each]. Want to add or remove any agents?"
|
||||
|
||||
Wait for approval before Phase 4.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Research & Plan Creation
|
||||
|
||||
**Tier 0**: Conduct inline research. Write plan directly without spawning agents.
|
||||
|
||||
**Tier 1+**: Spawn approved agents in parallel using Task tool (run_in_background: true). For each agent, provide:
|
||||
- Its specific research scope
|
||||
- The relevant files/areas to investigate
|
||||
- The questions it needs to answer
|
||||
|
||||
Monitor agents via TaskOutput polling loop. Report progress: "3/6 agents complete..."
|
||||
|
||||
When all agents return: if `planning-coordinator` was spawned, send it all agent reports and have it synthesize the final plan. Otherwise, synthesize directly.
|
||||
|
||||
**Plan file structure** (`docs/plans/plan-{name}.md`):
|
||||
|
||||
```markdown
|
||||
# Plan: {feature-name}
|
||||
Created: {date} | Branch: {branch-name} | Tier: {N}
|
||||
|
||||
## Summary
|
||||
One paragraph: what this implements and why.
|
||||
|
||||
## Decisions
|
||||
Decisions recorded during Phase 1 (PRD analysis).
|
||||
|
||||
## Architecture
|
||||
ADRs created, patterns applied, architectural choices made.
|
||||
|
||||
## Tasks
|
||||
Ordered task list with layers (1 = foundation, 2 = depends on 1, etc.)
|
||||
|
||||
### Layer 1
|
||||
- [ ] Task A — description, files affected, acceptance criteria
|
||||
- [ ] Task B — description, files affected, acceptance criteria
|
||||
|
||||
### Layer 2
|
||||
- [ ] Task C — depends on A — description, files affected, acceptance criteria
|
||||
|
||||
## Test Plan
|
||||
How each task will be verified. TDD tasks marked explicitly.
|
||||
|
||||
## Integration Verification
|
||||
Smoke test commands to run post-execution (if backend/services in scope).
|
||||
|
||||
## Out of Scope
|
||||
What this plan explicitly does not address.
|
||||
```
|
||||
|
||||
Commit: plan file + ADR files + agent report manifests.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Finalize Metrics
|
||||
|
||||
Record timestamps, phase durations, agent counts, and cost estimates in `docs/plans/metrics/{name}.json`. Commit.
|
||||
|
||||
---
|
||||
|
||||
## Auto-Transition
|
||||
|
||||
If Phase 1 produced no unresolved ambiguities and Phase 2 produced no unresolved decisions: auto-start `/plan-validate` without asking.
|
||||
|
||||
If any human discussion occurred: ask "Ready to validate this plan?" before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/plan-start
|
||||
```
|
||||
|
||||
Provide the feature description or point to a PRD file when prompted. The command handles the rest interactively.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use for any non-trivial feature: anything touching more than 2 files, involving architecture decisions, or where a planning mistake would be expensive to undo.
|
||||
|
||||
For simple changes (typos, trivial refactors): use `/plan` mode instead.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Plan-Validate-Execute Pipeline](../../guide/workflows/plan-pipeline.md)
|
||||
- [Planning Coordinator Agent](../agents/planning-coordinator.md)
|
||||
- [ADR Writer Agent](../agents/adr-writer.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue