Spec Flow Instructions

Spec Flow Instructions Skill

A 5-step workflow for specification-driven development.

Workflow

1. initialize_spec — Create spec from description with requirements and resource placeholders
2. create_resource — Analyze external resources, create detailed analysis files (repeatable)
3. refine_spec — Refine requirements, prompt user to resolve ambiguities, loop back if more resources needed
4. create_tasks — Generate concrete implementation tasks (code changes, tool calls, actions)
5. execute_task — Implement one task at a time (repeatable)

File Structure

specs/<SPEC_SLUG>/
├── spec.md                    # Main specification file
└── resources/
    └── <resource-slug>.md     # Resource analysis files

Templates

• templates/spec.md — Use for new specs. Includes sections for Overview, Requirements, Resources, Tasks, and Questions.
• templates/resource.md — Use for resource analysis files. Includes frontmatter and sections for Summary, Key Insights, Spec Alignment, Implementation Blueprint, and Risks.

ID Allocation

Rules:

• Sequential numbering starting from 001
• Never backfill gaps (if R-001, R-003 exist → next is R-004)
• Preserve existing IDs when updating, show traceability for merged items: (R-002) [merged into R-003]
• Mark obsolete requirements with [obsolete] tag, preserving their content: (R-002) [obsolete] Original requirement text here

Slug Generation

Convert Title Case to kebab-case:

• "AI Agent Chat" → ai-agent-chat
• "React Native Gifted Chat" → react-native-gifted-chat

Traceability

• Tasks reference requirements: "Addresses R-001 and R-002"
• Resources align with requirements: "Supports R-003"
• Every active requirement must map to at least one task

Resource Entry Format

- (RS-XXX) **<Name>** — Source: <url/path> — Analysis: `resources/<slug>.md` — Summary: <2-3 sentences>

Resource Analysis

Use template at templates/resource.md. Section guidance:

• Summary: What this resource is and why it matters for this spec (2-3 sentences)
• Key Insights: Problem it solves, core abstractions, usage patterns, integration points
• Spec Alignment: How it supports requirements (cite R-XXX), relevant vs irrelevant parts, gaps filled or created
• Implementation Blueprint: Entry points (APIs, CLIs, SDKs), code patterns, proof-of-concept approach, dependencies
• Risks & Considerations: Limitations, performance concerns, maintenance considerations, alternatives

Task Format

### <Task Title> (T-XXX) [pending]

#### Overview

Addresses R-XXX by... [explanation and approach]

#### Acceptance Criteria

- [verifiable outcome]
- [demo-able result]

#### Implementation Details

- **Files to modify**: `path/to/file.ts`
- **Functions to change**: `functionName()`
- **Patterns to follow**: Similar to existing implementation
- **Integration**: Use specific hooks, context, APIs
- **Testing**: How to verify

Status tags: [pending], [in-progress], [done], [blocked <reason>]

Execution Summary Format

Append to task after execution:

Execution Summary (T-XXX):
Files Changed (N):

- path/to/file.ts
  Acceptance Criteria:
- Criterion 1: PASS
- Criterion 2: PASS
  Tests: [results]
  Notes: [any observations]

Definition of Done Patterns

initialize_spec

• specs/<slug>/ directory created
• spec.md created from templates/spec.md
• resources/ subdirectory created
• Requirements derived from description
• Resource placeholders for mentioned URIs/paths only

create_resource

• Analysis file at specs/<slug>/resources/<resource-slug>.md
• All analysis sections completed
• supports_requirements field populated in frontmatter
• Parent spec Resources section updated with summary
• Resource ID assigned (sequential, no backfill)

refine_spec

• Spec and all resource analyses reviewed
• Problems and inconsistencies identified
• Ambiguities recorded in Open Questions section
• User prompted for each open question (use AskUserQuestion tool)
• Questions section updated with answers or cleared when resolved
• Overview refined for clarity
• Requirements refined to be concrete and testable

create_tasks

• Codebase inspected for patterns and file structure
• Every requirement (R-XXX) covered by at least one task
• Tasks include specific file paths, function names, patterns
• Acceptance criteria are verifiable
• Task dependencies marked when present

execute_task

• Task analyzed and current codebase understood
• Code changes implemented per task spec
• Follows existing code patterns
• All acceptance criteria verified
• Testing completed as specified
• No breaking changes to unrelated functionality
• Execution summary appended to task