SpecFlow

Plan First, Build Better

AI coding tools are fast. Too fast. Without structure, you end up with code that works but nobody understands, decisions that get lost, and prompts you repeat because you forgot what you already tried.

SpecFlow is an opinionated methodology for AI-assisted development. It forces you to think before you prompt, document as you build, and preserve the reasoning that makes code maintainable.

The core principle: the bottleneck in AI-assisted development is not implementation speed, it is specification clarity.

The Five Phases

Intent: Define what you are building and why. Capture goals, constraints, success criteria, and non-goals before writing any code.
Roadmap: Break the problem into phases with clear deliverables and dependencies. Each phase should be completable in one focused session.
Tasks: Translate each roadmap phase into atomic tasks. Mark which tasks are human decisions vs. AI-assisted implementation.
Execute: Work through tasks systematically with your AI tool. Use SpecStory to capture the reasoning and decisions as you go.
Refine: Review outputs against your original intent. Update the roadmap based on what you learned. Document changes for future reference.

Phase 1: Intent

The intent document is the most important artifact in SpecFlow. It prevents scope creep, aligns AI outputs with your goals, and gives you something to check against when you are deep in implementation.

Write your intent document before opening your editor.

# Project Intent: [Name]

## Vision
[1-2 sentences. What are you building?]

## Problem Statement
[What specific problem does this solve? Who has this problem?]

## Success Criteria
- [ ] [Measurable outcome 1]
- [ ] [Measurable outcome 2]
- [ ] [Measurable outcome 3]

## Constraints
- Technical: [Stack limitations, API restrictions, performance requirements]
- Time: [Deadline or time budget]
- Resources: [Team size, budget, dependencies on others]

## Non-Goals
[What this project will NOT do. Be explicit.]

## Open Questions
[Decisions you need to make but have not made yet]

Rules for a good intent document:

Success criteria must be testable. "Works well" is not a criterion. "Loads in under 2 seconds" is.
Non-goals are as important as goals. They prevent scope creep and give you permission to say no.
Open questions are honest. If you do not know something, write it down instead of pretending you do.

Phase 2: Roadmap

A roadmap breaks your intent into phases you can actually execute. Each phase should have a clear goal, concrete deliverables, and explicit dependencies.

Do not plan more than 3-5 phases. If you need more, your project is too big or your phases are too small.

# Roadmap: [Project Name]

## Phase 1: [Name] ([Time estimate])
**Goal**: [One sentence describing what this phase accomplishes]
**Deliverables**:
- [Concrete output 1]
- [Concrete output 2]
**Dependencies**: None

## Phase 2: [Name] ([Time estimate])
**Goal**: [One sentence]
**Deliverables**:
- [Concrete output 1]
- [Concrete output 2]
**Dependencies**: Phase 1 complete

## Phase 3: [Name] ([Time estimate])
**Goal**: [One sentence]
**Deliverables**:
- [Concrete output 1]
- [Concrete output 2]
**Dependencies**: Phase 2 complete

Rules for a good roadmap:

Each phase should be completable in 1-4 hours of focused work.
Deliverables are nouns, not verbs. "User authentication module" not "implement authentication."
Dependencies must be explicit. If Phase 3 needs Phase 1 but not Phase 2, say so.

Phase 3: Tasks

Tasks are the atomic units of work. Each task should be small enough to complete in one AI session and specific enough that you know when it is done.

The key insight: not every task should go to AI. Some tasks require human judgment. Label them explicitly.

## Phase 1 Tasks

### Task 1.1: [Name] [AI-Assisted]
**Input**: [What you need before starting]
**Action**: [Specific prompt or work to do]
**Output**: [What "done" looks like]
**Verification**: [How you confirm it works]

### Task 1.2: [Name] [Human Decision]
**Decision needed**: [What you need to decide]
**Options**: [List alternatives]
**Criteria**: [How you will choose]
**Output**: [Documented decision with rationale]

### Task 1.3: [Name] [AI-Assisted]
**Input**: [What you need]
**Action**: [What to do]
**Output**: [What done looks like]
**Verification**: [How to confirm]

Rules for good tasks:

AI-assisted tasks need specific prompts, not vague directions.
Human decision tasks need options and criteria, not just "figure it out."
Every task needs a verification step. If you cannot verify it, the task is too vague.

Phase 4: Execute

This is where you actually build. Work through tasks in order, respect dependencies, and capture everything with SpecStory.

Effective AI Prompting

Every prompt to your AI tool should include:

Context: Where you are in the project (phase, task number)
Specific ask: Exactly what you need right now
Constraints: Technical requirements, style preferences, limitations
Output format: How you want the response structured

I am working on [Project Name], currently in Phase [X], Task [Y].

## Context
[Paste relevant parts of your intent and roadmap]

## Current Task
[Paste the task definition]

## Specific Request
[What you need the AI to do right now]

## Constraints
- [Technical constraint 1]
- [Technical constraint 2]
- [Style preference]

## Expected Output
[Describe the format: code file, explanation, list of options, etc.]

Capture Reasoning with SpecStory

As you execute, SpecStory automatically saves your AI conversations to .specstory/history/. This is not optional overhead; it is the mechanism that preserves your decisions.

When you finish a task:

Verify the output matches the task definition
Review the conversation in .specstory/history/
If you made important decisions, ensure they are captured in the transcript

For terminal agents (Claude Code, Codex, Cursor CLI, Droid CLI, Gemini CLI), run your session through SpecStory:

specstory run claude   # or cursor / codex / droid / gemini

Commit .specstory/history/ alongside your code. Your future self and teammates will thank you.

Phase 5: Refine

After each phase, step back and evaluate. Do not just move to the next phase because you finished the tasks.

Questions to ask after each phase:

Does the output match the original intent? (Pull up your intent document and check.)
What did you learn that changes the roadmap?
Are there new constraints or open questions to document?
Should any success criteria be updated?

When to update your documents:

Small adjustments: Update task details, keep roadmap unchanged
Medium changes: Revise phase goals or reorder phases
Large pivots: Revisit the intent document, possibly redefine success criteria

Document what changed and why. This is where SpecStory pays off: you have a record of the reasoning that led to changes.

Full Example: CLI Task Manager

Here is a complete SpecFlow walkthrough for a small project.

Intent

# Project Intent: CLI Task Manager

## Vision
A command-line todo application that stores tasks locally and supports
priorities, due dates, and simple filtering.

## Problem Statement
I want a fast, keyboard-driven task manager that works offline and
integrates with my terminal workflow. Existing GUI apps break my flow.

## Success Criteria
- [ ] Add, complete, and delete tasks from command line
- [ ] Assign priority (high/medium/low) and optional due date
- [ ] List tasks with filters (by priority, by due date, completed/pending)
- [ ] Data persists between sessions in a local file
- [ ] Installable via npm or single binary

## Constraints
- Technical: Node.js, no external database, single JSON file storage
- Time: Complete in one weekend (8-10 hours)
- Resources: Solo developer

## Non-Goals
- No sync across devices
- No collaboration features
- No mobile or web interface

## Open Questions
- JSON vs SQLite for storage? (Leaning JSON for simplicity)

Roadmap

# Roadmap: CLI Task Manager

## Phase 1: Foundation (2 hours)
**Goal**: Project setup and core data model
**Deliverables**:
- Initialized Node.js project with TypeScript
- Task data model and JSON storage module
- Basic CLI argument parsing
**Dependencies**: None

## Phase 2: Core Commands (3 hours)
**Goal**: Implement add, list, complete, delete
**Deliverables**:
- `task add "description"` command
- `task list` command with table output
- `task done <id>` and `task delete <id>` commands
**Dependencies**: Phase 1

## Phase 3: Filtering and Priorities (2 hours)
**Goal**: Add priority, due dates, and filtering
**Deliverables**:
- Priority flag on add: `task add "desc" --priority high`
- Due date flag: `task add "desc" --due 2024-01-15`
- Filter flags: `task list --priority high --pending`
**Dependencies**: Phase 2

## Phase 4: Polish and Package (1.5 hours)
**Goal**: Error handling, help text, npm packaging
**Deliverables**:
- Helpful error messages for invalid input
- `--help` output for all commands
- package.json configured for npm publish or npx usage
**Dependencies**: Phase 3

Sample Task Breakdown (Phase 2)

## Phase 2 Tasks

### Task 2.1: Add Command [AI-Assisted]
**Input**: Storage module from Phase 1
**Action**: Implement `task add "description"` that creates a task with
           auto-generated ID and saves to JSON
**Output**: Working add command, task appears in storage file
**Verification**: Run `task add "Test"`, check JSON file contains task

### Task 2.2: List Command [AI-Assisted]
**Input**: Storage module, sample tasks in JSON
**Action**: Implement `task list` that reads JSON and displays as table
**Output**: Formatted table output showing ID, description, status
**Verification**: Add 3 tasks, run `task list`, confirm all appear

### Task 2.3: Complete Command [AI-Assisted]
**Input**: Working add and list commands
**Action**: Implement `task done <id>` that marks task complete
**Output**: Task status changes to "done" in storage
**Verification**: Add task, complete it, list shows updated status

### Task 2.4: Delete Command [AI-Assisted]
**Input**: Working list command
**Action**: Implement `task delete <id>` that removes task from storage
**Output**: Task removed from JSON file
**Verification**: Add task, delete it, list no longer shows it

Execute with SpecStory

cd cli-task-manager
specstory run claude

In the session:

I am building a CLI Task Manager. Currently in Phase 2, Task 2.1.

Context: Node.js + TypeScript project with a storage module that
reads/writes tasks.json. Task interface: { id, description, status,
createdAt }.

Task: Implement `task add "description"` command.

Constraints:
- Use commander.js for CLI parsing (already installed)
- Generate ID with nanoid
- Status defaults to "pending"
- createdAt is ISO timestamp

Expected output: The add command implementation in src/commands/add.ts

After completing all Phase 2 tasks, commit both the code and the SpecStory history:

git add src/ tasks.json .specstory/
git commit -m "Phase 2: Core commands (add, list, done, delete)"

Common Pitfalls

Skipping Intent

Symptom: Requirements keep changing mid-build. You are not sure when you are done. Fix: Spend 15 minutes on the intent document before anything else. If you cannot write clear success criteria, you are not ready to build.

Over-Planning

Symptom: You have been planning for hours and have not written any code. Fix: Time-box planning. Intent: 15 minutes. Roadmap: 15 minutes. Tasks for Phase 1: 10 minutes. Then start executing.

Vague Tasks

Symptom: AI outputs do not match what you wanted. You keep reprompting. Fix: Every task needs specific inputs, actions, outputs, and verification steps. If your task says "implement authentication," it is too vague.

Ignoring Dependencies

Symptom: You build Phase 3 features but Phase 2 is broken. Integration is painful. Fix: Complete phases in order. Do not skip ahead because something seems easy.

Not Capturing Reasoning

Symptom: You finished the feature but cannot explain why you made certain choices. Onboarding new teammates is painful. Fix: Use SpecStory. Commit .specstory/history/. Review transcripts before marking phases complete.

Quick Reference

SpecFlow Quick Reference
========================

1. INTENT    - What + Why + Success Criteria + Non-Goals
2. ROADMAP   - 3-5 Phases with goals, deliverables, dependencies
3. TASKS     - Atomic units with input/action/output/verification
4. EXECUTE   - Work systematically, capture with SpecStory
5. REFINE    - Check against intent, update docs, commit history

Prompting Formula:
  Context + Specific Ask + Constraints + Expected Output

Time Budget (small project):
  Intent: 15 min | Roadmap: 15 min | Tasks: 10 min/phase | Execute: bulk of time

Remember: The bottleneck is specification clarity, not implementation speed.