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

Spec Template (spec.md)

---
spec:
  title: "<Title Case>"
  slug: "<kebab-case>"
---

## Overview

<Brief description of what this specification accomplishes>

## Requirements

- (R-001) <Requirement description>

## Resources

<Resource entries will be added here as RS-XXX>

## Open Questions

<Questions identified during refine_spec that need user input>

## Tasks

<Tasks will be generated during create_tasks>

Resource Template (for resources)

---
resource:
  id: "RS-XXX"
  title: "<Resource Name>"
  source: "<URL or path>"
  spec_slug: "<SPEC_SLUG>"
  supports_requirements: [R-XXX]
---

# <Resource Name>

## Source

<URL or path to the resource>

## Summary

<2-3 sentences: what this resource is and why it matters for this spec>

## Key Insights

<Core concepts, patterns, and mental models relevant to spec requirements>

## Spec Alignment

<How this resource supports specific requirements, cite R-XXX IDs>

## Implementation Blueprint

<Practical entry points, code patterns, and setup requirements>

## Risks & Considerations

<Limitations, pitfalls, and alternatives to consider>

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 the Resource Template above. 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 using the Spec Template above
• • 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