Spec planner

spec-planner

Transforms specifications into a validated spec-graph plan. The graph — not markdown — is the source of truth. This skill enforces a strict procedure; follow each step in order.

Required Skill Dependencies

STOP. Before proceeding with this skill, you MUST load the spec-graph skill.

The spec-graph skill provides the schema knowledge required to operate spec-graph correctly:

• Valid entity types and their ID prefixes (REQ, DEC, ACT, RSK, PLN, PHS, etc.)
• Valid relation types per layer (mitigates, has_criterion, covers, belongs_to, etc.)
• Edge matrix: which (from_type, to_type, relation_type) combinations are allowed
• Validation rules: what makes a graph valid across arch/exec/mapping layers

Without spec-graph skill loaded, you will hit INVALID_INPUT and INVALID_EDGE errors and waste tokens guessing at the schema. This is non-negotiable.

To load it, invoke the skill tool with name="spec-graph" before continuing.

Prerequisites

• spec-graph CLI installed and available in PATH
• Project directory where .spec-graph/ will live (or already exists)

Core Principles

1. Zero interpretation: Never invent requirements. Flag ambiguities instead of guessing.
2. Full coverage: Every extracted requirement must map to at least one phase via covers.
3. Phase continuity: Phase N+1 depends only on phases ≤ N. No circular dependencies.
4. Phase ID ordering: PHS IDs MUST match execution order numerically. PHS-001 executes first, PHS-002 second, etc. Never assign PHS IDs arbitrarily — the numeric suffix IS the execution sequence.
5. Binary acceptance: Every exit_criteria in phase metadata must be testable as pass/fail.
6. Phase buildability: Every phase, when completed, MUST leave the project in a state where it builds without errors OR the dev server runs successfully. No phase may end with broken compilation or runtime boot failures.
7. Phase test integrity: Every phase, when completed, MUST have all tests passing. No test failures are allowed. Tests may only be skipped with explicit user confirmation — the skip reason must be recorded in exit_criteria metadata.
8. Query before create: Always check existing graph state before creating entities or relations.
9. Compute first: Run validate after every batch of mutations.
10. Graph-native output: New plans create TSK entities and no Markdown plan files. Never auto-import, delete, or reinterpret existing Markdown.

---

Procedure

Step 0: Information Gathering

Do not proceed until sufficient information is collected.

Minimum requirements:

• Project purpose / scope
• Core features or functional requirements
• Technical stack / constraints (language, framework, infra)
• Priority signals (must-have vs nice-to-have) if available

If input is a spec document, read it fully before proceeding.

If input is natural language and lacks the above, ask targeted questions:

I need a few more details before creating the plan:

1. [specific missing info]
2. [specific missing info]

What's the scope boundary — what is explicitly OUT of scope?

Do not ask more than 3 questions at once. Iterate if needed.

Step 1: Input Analysis

Extract from the input:

• Requirements (REQ): functional and non-functional
• Decisions (DEC): technology choices, architectural decisions, policies
• Acceptance Criteria (ACT): testable conditions for requirements
• Risks (RSK): known risks with likelihood/impact

Additionally, if the input explicitly mentions:

• API endpoints, interfaces, event contracts → register as API
• State machines, state transitions → register as STT
• Test scenarios → register as TST
• Open questions → register as QST
• Assumptions → register as ASM

Rule: Only register what is explicit in the input. Never infer entities that aren't stated.

Step 2: spec-graph Initialization

# Check if .spec-graph/ exists
ls .spec-graph/ 2>/dev/null

# If not, initialize
spec-graph init

If .spec-graph/ already exists, check for active plans:

spec-graph entity list --type plan --status active

If an active plan exists, inform the user:

An active plan already exists: PLN-XXX "[title]"
Creating a new plan requires archiving the existing one. Proceed?

Wait for user confirmation. On confirmation:

spec-graph entity update PLN-XXX --status deprecated

Step 3: Register arch Entities

Register extracted entities. Query before creating to avoid duplicates.

Note: --id is now optional for single creates (auto-generated, capture from .entity.id). However, this batch planning workflow uses explicit --id so that IDs can be cross-referenced in subsequent relation add commands within the same pass. Keep explicit IDs here.

# Check existing
spec-graph entity list --type requirement --layer arch

# Register requirements
spec-graph entity add --type requirement --id REQ-001 \
  --title "..." \
  --description "..." \
  --metadata '{"priority":"must","kind":"functional"}'

# Register decisions
spec-graph entity add --type decision --id DEC-001 \
  --title "..." \
  --metadata '{"rationale":"...","date":"YYYY-MM-DD"}'

# Register acceptance criteria and link to requirements
spec-graph entity add --type criterion --id ACT-001 \
  --title "..." \
  --metadata '{"given":"...","when":"...","then":"..."}'
spec-graph relation add --from REQ-001 --to ACT-001 --type has_criterion

# Register risks
spec-graph entity add --type risk --id RSK-001 \
  --title "..." \
  --metadata '{"likelihood":"medium","impact":"high"}'

# Register arch-internal relations
spec-graph relation add --from REQ-001 --to DEC-001 --type constrained_by
spec-graph relation add --from REQ-002 --to REQ-001 --type depends_on

Step 4: Create PLN + PHS + TSK Entities

Determine phase count based on project scale:

Scale	Signals	Phases
Small	1-2 modules, <10 endpoints	2-4
Medium	Multiple modules, auth/DB, 3-5 integrations	4-7
Large	Multi-service, CI/CD, monitoring	6-12

# Create plan (--status active is required for phase next to work)
spec-graph entity add --type plan --id PLN-001 \
  --title "..." \
  --status active

# Create phases (all as draft)
spec-graph entity add --type phase --id PHS-001 \
  --title "Phase 1 - ..." \
  --metadata '{"goal":"...","order":1,"exit_criteria":["criterion 1","criterion 2"]}'

spec-graph entity add --type phase --id PHS-002 \
  --title "Phase 2 - ..." \
  --metadata '{"goal":"...","order":2,"exit_criteria":["criterion 1","criterion 2"]}'

# Create graph-native tasks (all start as draft)
spec-graph entity add --type task --id TSK-001 \
  --title "Implement phase foundation" \
  --description "Implement the first independently verifiable unit of phase work." \
  --metadata '{"order":1,"instructions":["Implement the scoped unit."],"acceptance":["The scoped behavior passes verification."],"must_not":[],"references":[],"qa":[{"command":"go test ./...","expected":"exit 0","evidence":""}]}'

spec-graph entity add --type task --id TSK-002 \
  --title "Integrate phase behavior" \
  --description "Integrate the phase behavior after the foundation is complete." \
  --metadata '{"order":2,"instructions":["Integrate the scoped behavior."],"acceptance":["Integration verification passes."],"must_not":[],"references":[],"qa":[{"command":"go test ./...","expected":"exit 0","evidence":""}]}'

Task metadata is a closed six-field contract. order must be positive; instructions, acceptance, and qa must be non-empty; must_not and references are required and may be empty. Each QA item requires command, expected, and evidence; evidence stays empty until resolution, when it must identify a repository-relative regular file. Unknown keys are rejected.

PHS ID = execution order: The numeric suffix of PHS IDs determines execution sequence. PHS-001 is always first, PHS-002 always second. Do NOT assign IDs out of order (e.g., PHS-003 before PHS-001). If you reorder phases, renumber the IDs to match.

Rules for exit_criteria:

• Must be binary pass/fail
• MANDATORY for every phase: Must include "Project builds without errors OR dev server starts successfully". This is non-negotiable — a phase that leaves the project in a non-buildable/non-runnable state is invalid regardless of feature completeness.
• MANDATORY for every phase: Must include "All tests pass (no failures)". Tests may only be skipped if the user explicitly confirms the skip — record the skip reason in exit_criteria.
• No subjective language ("looks good", "works well")

Phase buildability constraint: When decomposing work into phases, ensure each phase's scope is self-contained enough that the project remains buildable/runnable after completion. If a feature requires multiple phases to become buildable, use techniques like:

• Feature flags or dead-code paths that compile but aren't reachable
• Interface stubs that satisfy type-checking
• Conditional compilation or build tags
• Never leave dangling imports, unresolved types, or missing implementations that break the build

Step 5: exec Relations

# Assign phases to plan
spec-graph relation add --from PHS-001 --to PLN-001 --type belongs_to
spec-graph relation add --from PHS-002 --to PLN-001 --type belongs_to

# Set ordering
spec-graph relation add --from PHS-001 --to PHS-002 --type precedes

# Assign tasks to their phase and encode dependent→prerequisite ordering
spec-graph relation add --from TSK-001 --to PHS-001 --type belongs_to
spec-graph relation add --from TSK-002 --to PHS-001 --type belongs_to
spec-graph relation add --from TSK-002 --to TSK-001 --type task_depends_on

Parallel-eligible phases: if two phases have no dependency, do NOT add precedes between them.

Step 6: Canonical Task Mapping (covers)

Map every arch entity to at least one task. Once a phase has any task, the union of child task mappings is the phase scope; direct phase mappings are forbidden.

spec-graph relation add --from TSK-001 --to REQ-001 --type covers
spec-graph relation add --from TSK-001 --to REQ-002 --type covers
spec-graph relation add --from TSK-002 --to REQ-003 --type covers

Coverage rule: Every active arch entity (REQ, DEC, ACT, RSK, and any registered API/STT/TST) must be covered by at least one phase. No orphaned arch entities.

Step 7: Validate

Run full 3-layer validation:

spec-graph validate --layer arch
spec-graph validate --layer exec
spec-graph validate --layer mapping
spec-graph validate --layer exec --check task_graph
spec-graph validate --layer mapping --check task_scope
spec-graph phase context PHS-001

If any check fails:

1. Parse the JSON error output
2. Identify the failing check and affected entities
3. Fix (add missing relations, correct ordering, resolve conflicts)
4. Re-validate

Do not proceed until all three layers pass.

phase context must return the plan, phase, ordered task contracts, prerequisites, task mappings, effective scope/delivery, blockers, and ready/blocked task IDs. This is the executor/verifier handoff. Do not generate a Markdown plan alongside it.

Legacy Isolation

The direct phase covers path is only for pre-existing taskless phases or explicitly supplied existing Markdown. Preserve those files and direct mappings byte-for-byte. Do not create tasks by reinterpreting Markdown, and do not mix direct phase mappings with task mappings.

Step 8: Persistent Instructions

Check for persistent instructions files in project root:

ls AGENTS.md CLAUDE.md .cursorrules .github/copilot-instructions.md 2>/dev/null

If found: Check if spec-graph section already exists. If not, append:

## spec-graph

This project uses spec-graph for requirements and phase management.

- `.spec-graph/` directory is the source of truth
- Before implementation: `spec-graph phase context <PHS-ID>` to check tasks and effective scope
- After implementation: `spec-graph validate` to verify
- Before changes: `spec-graph impact <ID>` for impact analysis
- Phase lifecycle: draft → active → resolved

If not found: Inform the user:

No persistent instructions file found (AGENTS.md, CLAUDE.md, etc.).
For other agents to recognize spec-graph in this project, creating one is recommended.
Create AGENTS.md with spec-graph instructions?

Act on user response.

---

Error Handling

Exit Code	Meaning	Action
0	Success	Proceed
1	Runtime error	Check stderr, retry
2	Validation failure	Parse output, fix, re-validate
3	Invalid input	Check arguments/schema, fix, retry

---

Anti-Patterns

1. Inventing requirements: Never add entities not present in the input. Flag gaps instead.
2. Skipping validation: Never proceed past Step 7 without all checks passing.
3. Over-registration: Don't register API/STT/TST unless explicitly stated in input.
4. Ignoring existing graph: Always query before creating. Duplicates corrupt the graph.
5. Vague exit_criteria: "Works correctly" is not testable. Be specific.
6. Markdown output: Never generate Markdown for a new plan or convert legacy Markdown implicitly.
7. Mixed mapping: Never add direct phase mappings after tasks belong to the phase.