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 < 500ms | ✓ met | Measured avg 180ms under load |
| FR-007 | Refresh token rotation | ✗ not met | Not implemented — see note |

**Compliance Status: PARTIAL** ← update to VERIFIED when all requirements met

Statuses: ✓ met | ✗ not met | ~ partial | pending

Cannot mark a node complete while compliance status is PARTIAL or pending.

---

Planning Gate

Written into roadmap.md, checked before execution starts:

## Planning Gate
- [ ] spec.md created and approved by user
- [ ] roadmap.md lists ALL phases (even future stubs) with effort estimates
- [ ] plan.md exists for every phase
- [ ] plan.md exists for every task in current phase (detailed, not stubs)
- [ ] Stub plan.md exists for tasks in future phases
- [ ] If using a non-template spec: Spec Format Assessment completed and user approved either revision or proceeding with listed risks
- [ ] User has reviewed and approved the plan structure

**Gate Status: NOT CLEARED**

Update to Gate Status: CLEARED and begin Pass 2 only when all boxes are checked.

---

Scope Change Protocol

If during execution you discover work that was not in the plan:

1. PAUSE execution (do not just do it)
2. Classify: is this in-scope per spec?
   - Clearly out of scope → document in findings.md, report to user, skip
   - In-scope but unplanned → add to appropriate plan.md, then continue
   - Conflicts with spec → STOP, report immediately, wait for user
3. If plan was updated: check if Planning Gate needs re-review
4. Resume execution

Never silently expand scope. Every discovered task must go through this protocol.

---

Error Protocol (3-Strike)

Attempt 1: Diagnose root cause → targeted fix
Attempt 2: Different approach — different method, different library
Attempt 3: Question assumptions — rethink from scratch
After 3 failures: STOP. Report to user: what you tried, exact error, your hypothesis.

Log every error immediately in the current plan.md's Errors table. Never repeat a failed action without changing the approach.

---

The 2-Action Rule

After every 2 view / browser / search operations, write key findings to findings.md. Multimodal content (screenshots, PDFs, browser output) does not persist — capture it as text immediately.

---

Step Completion Checklist

Before marking ANY step as done, the agent MUST:

1. Execute the step's Verification command/check
2. Confirm the output matches expected result
3. If verification fails → do NOT mark done → apply Error Protocol
4. If verification passes → mark step done, record evidence in plan.md

Before marking ANY node complete, the agent MUST:

1. Re-read the current plan.md
2. Verify ALL steps are marked done
3. Fill the Spec Compliance table with evidence
4. Confirm Compliance Status is VERIFIED (not PARTIAL, not PENDING)
5. Only THEN advance the Active Task/Phase pointer

---

Critical Rules Summary

Rule	What it means
Spec first	No plan without a spec; no execution without an approved spec
Plan completely first	All phases exist before execution; current phase fully detailed before starting it
No silent drift	Every undocumented task must go through Scope Change Protocol
Small files	>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

# 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