Spec Driven Planning

Spec-Driven Planning

Specify → Plan completely → Execute → Verify against spec. In that order. Every time.

---

When NOT to Use

• Simple tasks with clear, unambiguous requirements (use planning-with-files instead)
• Single-file changes or typo fixes
• Tasks under ~10 tool calls or 3 steps
• Quick fixes where requirements need no clarification
• When all you need is a session plan, not a project plan

Exception: If .planning/ exists, or the user references an existing spec, roadmap, or plan, use Reference Mode below even for small tasks. Do not start the full two-pass workflow unless the task changes scope, conflicts with the spec, or lacks enough plan coverage.

---

Relationship to spec-driven-development (skill)

This skill picks up where the spec-driven-development skill leaves off.

spec-driven-development owns the SPECIFY phase: surfacing assumptions, reframing requirements, and writing the initial spec with human review. THIS skill owns everything AFTER the spec is approved: decomposing it into a hierarchical plan, executing with compliance verification, and managing scope changes.

IF NO SPEC EXISTS when this skill loads — load spec-driven-development first and complete its Specify phase. Then return here to plan.

Key boundary:

• Before spec approval: spec is a LIVING document (spec-driven-development)
• After spec approval: spec is IMMUTABLE without explicit user instruction (this skill, via Scope Change Protocol)

---

FIRST: Restore Context

Before doing anything else, check for existing planning files:

ls .planning/ 2>/dev/null && echo "planning dir found" || echo "new project"

If .planning/ exists:

1. Read .planning/spec.md
2. Read .planning/roadmap.md
3. Resolve the active path (see § Active Path below)
4. Read only the plan files along the active path
5. Read .planning/progress.md (last session entry only)

Then continue from where work left off. Do NOT re-plan what is already planned.

If .planning/ does NOT exist, or spec.md is missing:

1. Load the spec-driven-development skill
2. Complete its Specify phase to create and approve the spec
3. Then return here to build the plan hierarchy

---

Reference Mode for Existing Planned Projects

If .planning/ exists, or the user references an existing spec, roadmap, or plan, use this skill as project memory even for small tasks such as bug fixes, code review, single-file edits, quick questions, or minor refactors.

In Reference Mode:

1. Read spec.md, roadmap.md, the active path plans, and the latest progress.md entry.
2. Use them to identify relevant files, requirements, prior decisions, and verification checks.
3. Do not create a new full plan unless the task changes scope, conflicts with the spec, or lacks enough plan coverage.
4. If the requested change conflicts with the spec, stop and report the conflict before editing.

---

Directory Layout

{project_root}/
└── .planning/
    ├── spec.md            ← Project specification (IMMUTABLE after approval)
    ├── roadmap.md         ← Top-level view: all phases, planning gate, active pointer
    ├── findings.md        ← Research & discoveries (global, written throughout)
    ├── progress.md        ← Session log (global, chronological)
    └── work/
        ├── 01-{phase}/
        │   ├── plan.md                  ← Phase plan
        │   ├── 01-{task}/
        │   │   ├── plan.md              ← Task plan
        │   │   └── 01-{subtask}/
        │   │       └── plan.md          ← Subtask plan (unlimited depth)
        │   └── 02-{task}/
        │       └── plan.md
        └── 02-{phase}/
            └── plan.md

Naming rule: NN-kebab-slug where NN is zero-padded execution order. Examples: 01-backend, 03-auth-module, 02-db-schema

All files go in .planning/. Never put planning files in project root or source directories.

---

Two-Pass Workflow

Pass 1 — Planning (write ZERO production code during this pass)

1. Create spec.md (draft from user input) or confirm existing spec
2. Present spec to user → get explicit approval
3. Create roadmap.md with ALL phases listed (even future ones as stubs)
4. Create plan.md for EACH phase
5. Create plan.md for each task in the CURRENT phase (detailed)
6. Create stub plan.md for tasks in future phases (just goal + status: pending)
7. Summarise the full plan for the user
8. Get user approval → Planning Gate clears

Rule: Pass 2 cannot begin until the Planning Gate is CLEARED.

If user says "just start coding", respond: "I need 10–15 minutes to plan first. It will save much more time during execution. Let me create the spec and plan quickly."

Pass 2 — Execution (follow the plan; do not drift)

For each task (in order):
  1. Read the active path chain (spec + roadmap + phase plan + task plan)
  2. Execute steps listed in task plan.md
  3. After completing each step: mark it done in task plan.md
  4. After completing all steps: fill Spec Compliance table in plan.md
  5. Verify all listed requirements are met
  6. Mark task complete; advance Active Task pointer
  7. Update progress.md

---

Active Path

Each level tracks one pointer to the currently active child. Together they form the active path.

roadmap.md          →  Active Phase: 02-authentication
  02-authentication/plan.md  →  Active Task: 01-user-model
    01-user-model/plan.md    →  Active Subtask: none   (leaf node)

To resolve active path:

grep "^Active Phase:" .planning/roadmap.md
# → 02-authentication

grep "^Active Task:" .planning/work/02-authentication/plan.md
# → 01-user-model

grep "^Active Subtask:" .planning/work/02-authentication/work/01-user-model/plan.md
# → none (leaf — this is where current work happens)

When a task completes:

1. Update its plan.md status to complete
2. Update the parent's Active Task: pointer to the next task
3. If all tasks in a phase complete, mark phase complete, advance Active Phase: in roadmap.md

---

What to Read at Each Moment

Context windows are limited. Load only what you need:

| Situation | What to read | |-----------|--------------| | Starting a new session | spec.md + roadmap.md + active path chain + last progress.md entry | | Working on a specific task | Only that task's plan.md | | Making a technical decision | Current plan.md + spec.md (relevant section) | | Spec compliance check | spec.md + current plan.md compliance table | | After an error | Current plan.md errors table only | | Discovering something useful | Write to findings.md immediately |

Never load the entire plan tree at once.

---

Project Specification (spec.md)

The spec is the single source of truth. Rules:

• Create spec.md before any other file
• Get explicit user approval before marking it approved
• Never modify spec.md without explicit user instruction
• Every phase and task plan must reference which spec requirements it addresses (FR-NNN, NFR-NNN)
• Completed work must be verifiable against spec requirements
• Every post-approval change to spec.md must increment the Version field and add an entry in the Change Log table — this ensures auditability of spec changes after approval

Handling non-template specs

If the user provides a specification that does not match this skill's template, do NOT silently normalize it or proceed as if it were complete.

Before building the roadmap, produce a Spec Format Assessment:

• Which required template sections are present, missing, renamed, or ambiguous
• Which extra sections exist and whether they affect scope, implementation, verification, risks, or constraints
• What risks the differences create for completeness, testability, scope control, or future handoff
• Whether requirements can be mapped to stable IDs such as FR-001, NFR-001, and AC-001 without changing meaning

Then ask the user to choose one path:

1. Complete or revise the specification using spec-driven-development
2. Explicitly approve proceeding with the non-template or incomplete spec and accept the listed risks

Planning Gate cannot be cleared until this assessment is complete and the user has approved one of the two paths.

Handling spec changes during execution

| Type of change | Action | |----------------|--------| | Minor clarification | Update spec.md, note change, continue | | New scope added | Update spec.md + affected plans, re-check Planning Gate | | Scope removed | Mark affected plans cancelled (do not delete history) | | Conflict with in-progress work | STOP execution, report to user, wait for instruction | | Major spec change | Treat as new Planning Pass for affected phases |

---

Decomposition Depth Guide

Decompose until each leaf node is ≤ 1 focused work session (≈ 20 tool calls or ≈ half a day).

| Level | Name | Example | Typical size | |-------|------|---------|--------------| | 0 | Roadmap | Full project | All phases | | 1 | Phase | "Backend API" | 3–8 tasks | | 2 | Task | "User authentication" | 3–10 steps or subtasks | | 3 | Subtask | "JWT token generation" | 3–10 steps | | 4+ | Sub-subtask | "Sign with RS256" | ≤ 5 steps, leaf node |

There is no nesting limit. Keep decomposing until the leaf is small enough to hold in working memory during execution.

Size signal: If a plan.md has more than 80 lines of actual content, decompose it further.

---

Spec Compliance

Before marking any node complete, fill the compliance table in its plan.md:

## Spec Compliance
| Req ID | Requirement Summary | Status | Verification |
|--------|---------------------|--------|--------------|
| FR-003 | Users can log in with email+password | ✓ met | `npm test auth` → 12/12 pass |
| NFR-001 | Login response 80 lines of content = decompose further |
| Compliance gate | Cannot mark complete without a filled compliance table |
| Re-read before decide | Before any significant decision, re-read current plan.md + spec relevance |
| Log all errors | Every error in the plan file. Never repeat. |
| Active path only | Never load the full plan tree into context |

---

## 5-Question Reboot Test

If you can answer all five, your context is solid:

| Question | Answer source |
|----------|---------------|
| What is the project spec? | `.planning/spec.md` |
| Where am I in the roadmap? | `Active Phase:` field in `.planning/roadmap.md` |
| What am I working on now? | `Active Task:` field in current phase plan.md |
| What have I discovered? | `.planning/findings.md` |
| What have I done? | Last session in `.planning/progress.md` |

---

## Quick Start

```bash
# 1. Initialize planning directory
mkdir -p .planning/work

# 2. Copy templates
#    Replace $SKILL_DIR with the actual path where this skill is installed
#    in your current environment (e.g. ~/.hermes/skills/spec-driven-planning/)
cp $SKILL_DIR/templates/spec.md      .planning/spec.md
cp $SKILL_DIR/templates/roadmap.md   .planning/roadmap.md
cp $SKILL_DIR/templates/findings.md  .planning/findings.md
cp $SKILL_DIR/templates/progress.md  .planning/progress.md

# 3. Fill spec.md → get user approval → fill roadmap.md
# 4. Create phase directories and plan.md files
mkdir -p .planning/work/01-first-phase
cp $SKILL_DIR/templates/plan.md .planning/work/01-first-phase/plan.md

# 5. Clear Planning Gate → begin execution

---

Templates

See templates/ directory:

| File | Use for | |------|---------| | spec.md | Project specification (create once) | | roadmap.md | Top-level roadmap with all phases | | plan.md | Phase plan, task plan, or subtask plan — same template for all levels | | findings.md | Research & discoveries | | progress.md | Session log |

---

Anti-Patterns

| Don't | Do instead | |-------|------------| | Start coding before planning | Clear the Planning Gate first | | Put everything in one plan file | Use the hierarchy — one plan.md per node | | Modify spec autonomously | Only on explicit user instruction | | Load the entire plan tree | Read only the active path chain | | Mark complete without verification | Fill the compliance table first | | Add undocumented scope | Scope Change Protocol | | Repeat failed actions | Log error, change approach | | Write external content to spec.md | External content goes in findings.md only | | Collapse later phases into "TBD" | Even stubs must exist in roadmap.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: johnnykor82
• Source: johnnykor82/spec-driven-planning
• License: MIT

Install and usage instructions live in the source repository linked above.