plan-builder

---
name: plan-builder
description: "Engineering plan generator (15+5 sections). This skill should be used when the user asks to 'write a plan', 'build a plan', 'create sub-plan', '/plan-builder', '/a-dev feature', or needs an A-O structured plan graded against the 16/20 quality gate."
mode: [engineering]
effort: high
superpowers_pattern: [iron_law, red_flags, hard_gate]
see_also: [brainstorming, context-discovery, plan-reviewer, improve-codebase-architecture]
thinking_mode: adaptive
---

# Plan Builder

**Model**: ALWAYS Opus 4.7, max thinking effort, max output tokens. Never truncate.
**Announce:** "Building engineering plan using Atlas Dev plan-builder..."

<HARD-GATE>
NO IMPLEMENTATION STARTS WITHOUT A PLAN SCORING >= 12/15 ON THE QUALITY GATE.
A plan below 12/15 is a liability, not a blueprint.
Revise weak sections and re-score before Gate G1 approval.
</HARD-GATE>

**Iron Law**: `LAW-PLAN-001` (plan-gate-12-over-15). Override requires HITL AskUserQuestion. Source: `scripts/execution-philosophy/iron-laws.yaml`.

> **Section F (Files / Module sectioning) — depth-aware sectioning**: when listing critical files, prefer **deep-module units** (one entry per module that has small-interface + lots-of-implementation) over per-file flat enumeration. Use the Ousterhout vocabulary (Module / Interface / Depth / Seam / Adapter / Leverage / Locality) — see [improve-codebase-architecture/LANGUAGE.md](../improve-codebase-architecture/LANGUAGE.md). When the plan asks "should this be one file or three?", default to ONE deep module unless the deletion test fires (would deleting one of the three concentrate complexity in the others? if no — keep three; if yes — merge into one).

<red-flags>
| Thought | Reality |
|---|---|
| "This feature is too simple to need a plan" | Simple projects are where unexamined assumptions cause the most wasted work. The plan can be short, but it MUST exist and be approved. "Too simple to plan" precedes 90% of scope-drift incidents. |
| "Let me just start coding and see where it goes" | Coding without a plan = architecting in your prefrontal cortex under tool-use latency. You will burn 10x tokens exploring paths a 15-min plan would have rejected. |
| "Plan later, let me prototype first to see if it works" | "Prototype first" = "write production code I will pretend to throw away". You will adapt the prototype, not rewrite it. Prototyping without a plan is planning-by-accretion. |
| "I know the pattern from last sprint, same plan applies" | Patterns repeat but CONTEXT does not. Tables, personas, constraints, API shape — all different. Reusing a plan verbatim skips the discovery where the gotcha lives. |
| "Plan scored 10/15 but deadline is tight, let's ship it" | A plan below 12/15 has 3+ weak sections. Those sections become your incident retrospectives. Gate G1 at 12/15 is calibrated on historical data — below it, rework cost > plan-enrichment cost. |
</red-flags>

## Workflow

| Step | Action | HITL |
|------|--------|------|
| 1. Load | Read context discovery report + `.blueprint/plans/INDEX.md`. Extending? Load existing plan. Load `.blueprint/PLAN-TEMPLATE.md`. Check `.blueprint/designs/` for design docs (see Design Doc Integration below) | - |
| 2. Research | Objective research: factual questions only, NO intent in Explore prompts (see Research Objectivity below). WebSearch (2026+) + Context7 (lib docs) → feed Section C | - |
| 3. Brainstorm | AskUserQuestion with 2-3 approaches + comparison table | YES |
| 4. Draft | Fill all 15 sections (see below). N/A sections get 1-line justification | - |
| 4.5 Exec Strategy | For plans > 10 tasks: add execution strategy sections (task types, model alloc, parallelism, cost) | - |
| 5. Quality Gate | Score 20 criteria (gate >= 16/20). If < 16: enrich weak sections, max 2 iterations. Legacy /15 plans: gate >= 12/15 | - |
| 6. Save | `.blueprint/plans/{subsystem}.md` + update INDEX.md + present score. Wait: "go" or "change X" | YES |

## 15 Sections (A-O)

### Core (A-G)

| # | Section | Content |
|---|---------|---------|
| 🔍 A | VISION | WHY + problem + solution + personas + engineering chain impact |
| 📦 B | INVENTAIRE | Current files, tables, configs, hooks to reuse |
| 🏗️ C | ARCHITECTURE | Mermaid diagram + sourced decisions (Context7/WebSearch) |
| 💾 D | DB SCHEMA | CREATE/ALTER TABLE + indexes + Alembic migration |
| ⚙️ E | BACKEND | Service classes, method signatures, before/after for refactors |
| 🔌 F | API | Endpoints table: method, path, auth, request, response, errors |
| 🖥️ G | FRONTEND UX | Mermaid/ASCII mockup + components + hooks + UX convergence |

### Enterprise (H-L)

| # | Section | Content |
|---|---------|---------|
| 🎭 H | PERSONA IMPACT | Matrix: persona x impact x capability x UX x RBAC x test scenario |
| 🔒 I | SECURITY | RBAC table + OWASP checklist + data sensitivity |
| 🤖 J | AI-NATIVE | API for AI agents + structured logging + metrics + health |
| 🖥️ K | INFRASTRUCTURE | Hardware table + perf targets + cache + scaling strategy |
| ♻️ L | REUSABILITY | Multi-company + multi-discipline + config points (YAML import) |

### Execution (M-O)

| # | Section | Content |
|---|---------|---------|
| 📋 M | TRACEABILITY | Audit trail (who/when/what) + versioning + derivation tracking |
| 📅 N | PHASES | Table: phase, content, files, duration, dependencies. Mermaid gantt. |
| ✅ O | VERIFICATION | Backend + frontend + E2E persona + DB + perf + security commands |

## Design Doc Integration

When `.blueprint/designs/{feature}.md` exists (produced by brainstorming skill):

1. **Load** the design doc as pre-resolved context
2. **Pre-fill sections** from design doc content:
   - "Resolved Decisions" → Section A (Vision), Section C (Architecture)
   - "Patterns Found" → Section B (Inventory) — reusable code, anti-patterns to avoid
   - "Phase Sketch" → Section N (Phases) — follow the vertical structure as baseline
   - "Constraints" → Sections H-L (Enterprise)
3. **Resolve "Open Questions"** — research or ask user for remaining unknowns
4. **Do NOT re-ask** questions already resolved in the design doc
5. If no design doc found → proceed normally (brainstorming may not have been run)

## Research Objectivity

When launching Explore agents or sub-agents for research (Step 2):

**Rule**: Research agents must NOT know what feature is being built. They gather FACTS only.

**2-phase approach**:
1. **Generate research questions** (with ticket context): Frame as factual questions
   - GOOD: "How does the endpoint routing work in `backend/routes/`?"
   - GOOD: "What tables and indexes exist for the `instruments` domain?"
   - GOOD: "Trace the data flow from import CSV to material_catalog table."
   - BAD: "How should we implement the new spline feature?"
   - BAD: "What's the best approach for adding tenant filtering?"
2. **Send only questions** to Explore agents — exclude ticket, feature name, and user intent

**Opinion detection** (post-research): Scan research output for opinion words: "should", "recommend", "suggest", "better to", "consider using", "I think". If found → flag to user as potentially contaminated research, but don't block.

## Vertical Plan Constraint (Section N)

Each phase in Section N MUST be an independently testable end-to-end slice:
- Each phase touches at least 2 layers (e.g., DB+API, or API+FE)
- Each phase has a test checkpoint command (how to verify it works)
- **Anti-pattern**: 3+ consecutive same-layer phases (all DB → all API → all FE = HORIZONTAL, reject)
- If a Phase Sketch exists in the design doc, use it as the structural baseline

## Quality Gate (20 criteria, gate >= 16)

### Core Criteria (1-15) — same as before

| # | 1 pt if... | # | 1 pt if... |
|---|-----------|---|-----------|
| 1 | Vision explains WHY + chain impact | 9 | AI-native described |
| 2 | Inventory lists code + reusable hooks | 10 | Infra + perf targets |
| 3 | Architecture has diagram + sourced decisions | 11 | Reusability explained |
| 4 | Full-stack D+E+F+G present | 12 | Traceability + audit trail |
| 5 | Personas with test scenarios | 13 | Phases with files listed |
| 6 | UX convergent (refs ux-rules) | 14 | E2E verification with commands |
| 7 | Research done (Context7/WebSearch) | 15 | Patterns reused (refs existing code) |
| 8 | Security + RBAC covered | | |

### Execution Strategy Criteria (16-20) — NEW

| # | 1 pt if... |
|---|-----------|
| 16 | **Task Classification**: Each task in Section N has a type (architecture/implementation/testing/validation/lint/search) |
| 17 | **Parallelization**: Independent task groups identified with justification (no shared files/deps) |
| 18 | **Model Allocation**: Opus/Sonnet/Haiku/DET assigned per task with rationale (not "all Opus") |
| 19 | **Coordination Plan**: Dependency DAG documented, critical path identified, HITL gates placed |
| 20 | **Cost Estimate**: Token budget per model tier with total and vs-all-Opus comparison |

### Scoring Rules

- **New plans (2026-03-27+)**: Score on /20. Gate >= 16/20.
- **Legacy plans (pre-2026-03-27)**: Score on /15. Gate >= 12/15. Remain valid.
- **Plans < 10 tasks**: Criteria 16-20 optional (mark N/A with justification). Gate remains 12/15.
- **Plans >= 10 tasks**: Criteria 16-20 required. Gate >= 16/20.
- **Migration**: Existing plans do NOT need retroactive update. Only new/extended plans use /20.

## Plan Types (section depth by type)

| Section | Feature | Refactor | Bugfix |
|---------|---------|----------|--------|
| A-B | FULL | FULL | FULL (root cause) |
| C | FULL | LITE (diff) | N/A |
| D-F | IF applicable | IF applicable | N/A |
| G | FULL | LITE | IF applicable |
| H-L | FULL | LITE | N/A (except security) |
| M-O | FULL | FULL | FULL |

## Diagrams

Use **Mermaid** (preferred) for architecture (`graph TD`), phases (`gantt`), data flow (`sequenceDiagram`). Dashboard renders via MarkdownRenderer + Mermaid v11. Tables = GFM markdown.

## Extending Existing Plans

Load full plan → update relevant sections only → keep untouched intact → re-score → git diff shows changes.

## Commit

`plan({subsystem}): {description}`

## Mega Plans (`/atlas plan --mega`)

When `--mega` flag detected OR user says "programme", "mega plan", "multi-plan":

1. Switch to `templates/MEGA-PLAN-TEMPLATE.md` (M1-M16) instead of A-O format
2. Read `.blueprint/plans/INDEX.md` to discover existing sub-plans
3. For each sub-plan found: extract Section A (vision) + dependencies + effort
4. Auto-generate M2 Sub-Plan Registry from discovered sub-plans
5. Build M3 Dependency Graph (Mermaid + ASCII) from sub-plan dependencies
6. Calculate M6 Critical Path (longest weighted path through DAG)
7. Populate M5 Phase Timeline from existing mega plan phases
8. Score against 16 criteria (gate >=10/16)
9. Verify bidirectional links: every sub-plan references mega, mega references every sub-plan

**Quality gate**: 10/16 for programme + ALL sub-plans >= 12/15 individually.

**Output**: Save to `.blueprint/plans/{adjective-verb-noun}.md` (same naming convention).

## Workflow Feature Planning Mode (consolidated from workflow-plan-feature W5.3 2026-05-01)

When the request is for a **single-feature, <1 week** scope (triggers: "plan feature",
"plan this", "short plan", "quick plan"), use **Feature Mode** — a lighter variant
of the full 15-section plan optimized for moderate scope.

### Feature Mode vs Full Mode

| Dimension | Feature Mode (<1 week) | Full Mode (multi-wave) |
|-----------|------------------------|------------------------|
| Sections | 5-8 (subset of A-O) | All 15 (A-O) |
| Quality gate | >= 12/15 (legacy scoring) | >= 16/20 (with execution strategy) |
| Iron Law | LAW-PLAN-001 | LAW-PLAN-001 + LAW-WORKFLOW-002 (framing) |
| Estimated duration | ~60 min | 180+ min |
| Persona tags | engineer | engineer, architect |
| HITL | Quick review (Step 3 below) | Full brainstorm + score + approval |
| Use when | <1 week single-feature delivery | Multi-wave / mega plans / multi-phase |

### Feature Mode workflow steps (DAG with red-flags)

| Step | Name | Skill | Gate | Iron Law | Purpose | Depends on | Model |
|------|------|-------|------|----------|---------|------------|-------|
| 1 | Frame | task-framing | MANDATORY | LAW-WORKFLOW-002 | Confirm moderate-scope feature (if complex, escalate to Full Mode) | — | sonnet |
| 2 | Shortened plan (5-8 sections) | plan-builder (this skill) | MANDATORY | LAW-PLAN-001 | Context, scope, implementation steps, verification, risks. Not 15 sections — 5-8 sufficient. | 1 | opus |
| 3 | HITL approval | interactive-flow | HARD_GATE | — | Quick user review. AskUserQuestion on anything ambiguous. | 2 | sonnet |

### Feature Mode red-flags

| Thought | Reality |
|---|---|
| "Skip plan, just code it" | Feature = >1h. Framing rule says plan. 15 min now saves rework. |
| "Full 15-section for a 1-week feature" | Overkill. Shortened plan (5-8 sections) covers moderate scope adequately. Use Full Mode only for multi-wave. |
| "Feature Mode is just a smaller plan" | No — it's a single-feature scope distinction. Multi-wave plans MUST use Full Mode regardless of total hours. |

### Recommended sections for Feature Mode (subset of A-O)

| Required | Optional (include if applicable) |
|----------|----------------------------------|
| A (Vision), B (Inventaire), N (Phases), O (Verification) | C (Architecture, if non-trivial), E (Backend), F (API), G (Frontend) |

H-M sections are typically N/A for single-feature scope unless touching security
(I) or persona-impacting UX (H).

### Feature Mode success output

```json
{
  "workflow": "plan-feature",
  "mode": "feature",
  "status": "completed",
  "plan_path": ".blueprint/plans/feat-slug.md",
  "sections": 7,
  "hitl_approved": true,
  "estimated_hours": N
}
```

## BMAD Personas Overlay (sp7 — 2026-05-02)

Activate **before** Section drafting when plan has ≥10 tasks (default ON) or `--mega` flag.
Skip with `--no-bmad` (hotfix mode) or `--feature` (single-feature scope).

### Activation Logic

```
tasks_estimated >= 10  →  BMAD ON  (default)
--no-bmad flag         →  BMAD OFF
--feature flag         →  BMAD OFF
--mega flag            →  BMAD ON  (required for programme plans)
```

### Workflow Step (inserts between Step 2 Research and Step 3 Brainstorm)

**Step 2.5 — BMAD 6-Persona Pass** (when BMAD ON):
1. Build plan shell (Section A Vision only — enough for personas to review)
2. Dispatch 6 atlas-team agents in parallel (see briefings below)
3. Collect findings (max 60s timeout per agent — fail-open)
4. Synthesis: aggregate → deduplicate → prioritize → apply uncontested findings
5. Surface ≤3 contested findings to user via AskUserQuestion
6. Record in plan Section A frontmatter: `bmad_review: {date, personas_run, findings_total}`

### Agent Dispatch Briefings

| Persona | Agent | Model | Focus |
|---------|-------|-------|-------|
| Mary (BA) | `domain-analyst` | haiku | Business value + domain vocab check |
| Preston (PM) | `team-researcher` | haiku | PRD alignment + scope control |
| Winston (Arch) | `plan-architect` | opus | Section C architecture quality |
| Sally (PO) | `team-engineer` | sonnet | Section N vertical slicing |
| Simon (SM) | `team-coordinator` | sonnet | HITL gates + dependency DAG |
| Devon (Dev) | `team-engineer` | sonnet | Section O verification completeness |

All persona agents are READ-ONLY during BMAD pass. Full persona specs:
`skills/plan-builder/references/bmad-personas.md`

## Spec-Kit Constitution Gate (sp7 — 2026-05-02)

Runs AFTER 15-section draft and BEFORE quality gate (Step 5).

```
.blueprint/CONSTITUTION.md found?
  NO  → skip gate (advisory log)
  YES → check each MANDATORY rule against plan sections
         ALL pass → proceed to quality gate
         ANY fail → block + list violations + max 2 fix iterations
                    still failing → HITL via AskUserQuestion
```

ADVISORY violations collected and appended to plan Section I as auto-generated notes.
Full constitution gate spec: `skills/plan-builder/references/spec-kit-constitution.md`

## Kiro Living-Spec (sp7 — 2026-05-02)

After plan is saved to `.blueprint/plans/*.md`, register it with the living-spec system:

1. Hook `hooks/plan-edit-kiro-regen` fires automatically on every subsequent plan edit
   (PostToolUse Write|Edit — path-filtered to `.blueprint/plans/*.md`)
2. Hook detects changed sections and emits advisory re-gen suggestions
3. `memory/kiro-regen.log` records sync events

**Engineer action**: the hook is advisory — suggestions are printed, not auto-applied.
Run suggested commands (e.g., `/atlas to-issues`) at your discretion.

Full living-spec pattern: `skills/plan-builder/references/kiro-livespec.md`

## OpenSpec DAG Linker (sp7 — 2026-05-02)

After plan is saved, update (or create) `.blueprint/plans/_dag.yaml`:

1. Add plan entry with `id`, `file`, `status: draft`, `effort_hours`, `delivers[]`
2. Populate `depends_on[]` from Section N phase dependencies
3. Add integration points if plan shares DB tables/APIs with existing plans
4. Validate: `yq . .blueprint/plans/_dag.yaml > /dev/null` (exit 0 = valid)

DAG manifest enables Wave scheduling and critical-path analysis.
Schema reference: `skills/plan-builder/references/openspec-dag.md`

## .cursorrules Template (sp7 — 2026-05-02)

When `--cursor` flag is passed: generate `.cursorrules` at repo root after plan save.

Content derived from:
- Plan Section C (Architecture) → 3-line summary
- `.blueprint/CONSTITUTION.md` (MANDATORY rules) → bulleted constraints
- Plan Section F (API) → first 5 endpoints table
- Plan Section O (Verification) → top 3 verify commands

User is asked to confirm write via AskUserQuestion before writing.
Template: `skills/plan-builder/references/cursorrules-template.md`


## Effort tunability (CC 2.1.x)

This skill respects the `${CLAUDE_EFFORT}` template variable. The runtime effort budget influences depth, breadth, and rigor:

| Level | Behavior |
|---|---|
| `low` | Fast pass, surface-level (Haiku-tier) |
| `medium` | Default — balanced (Sonnet-tier) |
| `high` | Deeper, more thorough (Sonnet-tier with extended reasoning) |
| `max` / `xhigh` | Maximum quality — Opus-tier reasoning, "ultrathink" semantics |

Override at invocation: append `--effort=<level>` or set `${CLAUDE_EFFORT}=<level>` env var. The skill auto-detects and adapts.