alexei-led/spec-plan

spec plan — create an epic with vertical-slice tasks

CLI at scripts/specctl. Turn a requirement (or idea) into an EPIC-*.md + a set of independently grabbable TASK-*.md files with dependencies, blockers, and acceptance criteria.

Role: technical planner. Goal: epic + tasks. Out of scope: implementation code.

Input

The user's input is one of:

• REQ-id — read requirement, create epic + tasks
• EPIC-id — refine existing epic
• "<idea text>" — only when the idea is already concrete: ask 3–5 quick questions, then plan. For open-ended or unvalidated ideas, use the brainstorming-ideas skill first; for deep PRD-quality requirements, use the spec-interview skill instead.

If empty, ask: "What should I plan? Give me a REQ id or describe the feature."

Step 0: Setup

scripts/specctl init 2>/dev/null || true
mkdir -p .spec/epics .spec/tasks

Step 1: Load context

• REQ id → scripts/specctl show REQ-<id> and read the file.
  • If REQ-id not found: tell the user "REQ-<id> does not exist. Run spec-status to list requirements." Stop.
• EPIC id → scripts/specctl show EPIC-<id> — refinement; may add/update tasks.
  • If the epic already has in-progress or done tasks, warn: "EPIC-<id> has tasks in progress. Adding tasks may create dependency conflicts. Proceed?" Require explicit confirmation.
• Idea text → ask 3–5 quick questions.

Step 2: Research (optional)

Ask the user a multi-choice question: "Should I explore the codebase first?"

• Yes, quick scan — find patterns and conventions
• No, I know the codebase — skip

If yes, delegate codebase exploration to a research/exploration agent if the runtime supports it. The prompt: "Find existing patterns, conventions, and code relevant to <requirement summary>. Look for similar implementations, reusable code, and architectural patterns."

Capture from the research:

• File paths + line refs
• Existing patterns to follow
• Code to reuse
• Architectural conventions

Step 3: Create the plan

Build vertical-slice tasks: each is a tracer bullet (narrow but complete path through the system), M-sized (3–5 files / 3–5 criteria) is the target, ordering via blocked-by, tests in the same slice as the behavior. For the full vertical-slice rules, task sizing, dependency rules, and the pre-write mental-model checklist, read references/planning-rules.md.

Step 4: Present plan for approval

Before writing files, show the plan:

## Proposed plan for <requirement>

### Epic: EPIC-<slug>
<overview>

### Tasks (in order):

1. TASK-<slug>-1: <title>
   - Size: M
   - Files: <expected files>
   - Blocked by: none
   - Open questions: none | <specific blocker>
   - Verifiable: <demo/check/test>

2. TASK-<slug>-2: <title>
   - Size: M
   - Files: <expected files>
   - Blocked by: TASK-<slug>-1
   - Verifiable: <demo/check/test>

Ask multi-choice: "Does this plan look right?"

• Yes, create files
• Needs changes (user explains)
• Too detailed — simplify
• Not detailed enough — add more tasks

Wait for approval before writing.

Step 5: Write files

Epic file

---
id: EPIC-<slug>
status: open
priority: <from REQ or normal>
implements: REQ-<slug>
created: <date>
tasks:
  - TASK-<slug>-1
  - TASK-<slug>-2
---

# <Title>

## Overview

<What this epic accomplishes>

## Approach

<High-level technical approach. Reference existing patterns: "Follow pattern at src/auth.ts:42".>

## Quick commands

\`\`\`bash
make build
make test
make lint
\`\`\`

## Acceptance

- [ ] All REQ criteria met
- [ ] Tests pass
- [ ] No lint errors

## References

- Requirement: REQ-<slug>
- <Other refs from research>

Task files

For each task:

---
id: TASK-<slug>-N
status: todo
priority: normal
epic: EPIC-<slug>
blocked-by: [TASK-<slug>-X] # or []
size: M
---

# <Task title>

## Description

<What to build — WHAT, not HOW. Describe the end-to-end behavior this vertical slice delivers.>

## Notes

- Blockers or open questions: <none | specific human decision / access / manual check needed>
- Out of scope: <adjacent behavior not included>

## Files

- `path/to/file.ts` — <what changes>

## Approach

<High-level approach. Reference patterns: "Follow pattern at src/example.ts:15".>

## Acceptance

- [ ] <observable criterion 1>
- [ ] <observable criterion 2>
- [ ] Success-path test exists if code behavior changed
- [ ] Error or edge-case test exists when relevant
- [ ] Tests pass

Step 6: Validate & complete

scripts/specctl validate
scripts/specctl status

Show summary:

Created:
- EPIC-<slug> with <N> tasks
- Tasks: TASK-<slug>-1, TASK-<slug>-2, ...

Next steps:
1. Start work: use the `spec-work` skill — `spec-work EPIC-<slug>`
2. Review plan: read .spec/epics/EPIC-<slug>.md

Golden rule: no implementation code

Plans describe WHAT, not HOW.

• Allowed: signatures, interfaces, pattern references with file:line, API notes from docs.
• Forbidden: complete function implementations, copy-paste-ready code blocks (>10 lines), "here's what you'll write" snippets.

Implementation happens in the spec-work skill.