# Spec Flow Instructions

> MUST use when working with spec files in `specs/` directories, or when commands reference this skill for conventions.

- Skill: `majiayu000/spec-flow-instructions` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/spec-flow-instructions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/spec-flow-instructions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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

| Type         | Format | Example                |
| ------------ | ------ | ---------------------- |
| Requirements | R-XXX  | R-001, R-002, R-003    |
| Resources    | RS-XXX | RS-001, RS-002, RS-003 |
| Tasks        | T-XXX  | T-001, T-002, T-003    |

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

```markdown
- (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

```markdown
### <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:

```markdown
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