Spec Writer

When to Use

Invoke for:

• Starting work on a story group — "set up spec-writer for X", "create change folder for X"
• Archiving a completed feature — "archive feat-X" (only when explicitly instructed by dev after all sub-issues are confirmed closed)

Explicit use only — always an explicit act: the user names this skill, or dev calls it.

Entry detection — before creating, check openspec/changes/<feat-name>/ in the project repo:

Principles

Change folder location: openspec/changes/<change-name>/ inside the project repo. The change name is kebab-cased with the change type as prefix: feat- for a story group ("Onboarding" → feat-onboarding), fix- for a bug, chore- for non-feature work. Stories live in a specs/ subdirectory within the change folder.

Bug fixes and other changes with no story group: write proposal.md with **Story group:** none (<where the bug was found>), and write specs/stories.md from the bug itself: one story for the broken behaviour from the user's side, plus one for the regression guard if the fix adds one. Everything else is unchanged.

Artifacts and their sources:

Layers come from the project, never from this skill: the layer names and their order in the repository's AGENTS.md, or the rules in openspec/config.yaml if it has them. If the project names no layers, ask the user once and suggest they add them to AGENTS.md.

Conversation flow:

1. Confirm which story group this change covers
2. Derive proposal.md and specs/stories.md from discovery artifacts — no questions needed
3. Invoke arch-review to produce design.md, or for a bounded change write the short design note yourself
4. Write tasks.md with ordered implementation steps broken by layer
5. Output the change folder path

Archive action: Receives an explicit archive instruction from dev (never self-triggers). Moves openspec/changes/<feat-name>/ → openspec/changes/archive/<feat-name>/. Does not verify issue state — dev handles that before invoking.

proposal.md template:

# Proposal: <Feature Name>
**Change:** <feat-name>
**Story group:** <Onboarding | Core Loop | Edge Cases>
**Date:** YYYY-MM-DD

## Scope
[1-3 sentences: what this change builds]

## Rationale
[1-3 sentences: which job stories drive this, why now]

## Out of scope
[Explicit exclusions — YAGNI]

specs/stories.md template:

# Specs: <Feature Name>

## Story 1
When [situation], I want to [motivation], so I can [outcome].

### Acceptance criteria
- [ ] [one checkbox per verifiable behavior derived from the outcome]

## Story 2
When [situation], I want to [motivation], so I can [outcome].

### Acceptance criteria
- [ ] [one checkbox per verifiable behavior derived from the outcome]

Each story gets its own section with acceptance criteria directly below it.

tasks.md template:

# Tasks: <Feature Name>
**Change:** <feat-name>
**Date:** YYYY-MM-DD

## :<first-layer>
- [ ] [task]

## :<next-layer>
- [ ] [task]

One section per project layer, in the project's order. Omit layer sections that have no tasks for this story group.

sprint-contract.md template:

# Sprint Contract: <Feature Name>
**Change:** <feat-name>
**Date:** YYYY-MM-DD
**Derived from:** specs/stories.md

## :<layer-name>
- [ ] [concrete testable assertion derived from acceptance criteria]
- [ ] [concrete testable assertion]

Never write a Cross-review: line into the contract: dev adds it in Phase 4 from a real review result, and its presence is what tells dev the review ran.

Layer names are taken from tasks.md headings. One section per layer present in tasks.md.

Constraints

• When invoked with a Scope Brief (from dev), keep proposal.md and tasks.md inside it: its Explicitly out of scope items go in the proposal as non-goals, and its Also update items become tasks
• design.md is written verbatim from arch-review output — never reformatted or summarized (a bounded change's short design note is the exception)
• Checkboxes in tasks.md and specs/stories.md stay unticked: they are the plan, and sprint-contract.md is the record of what was verified. Reviewers shouldn't flag unticked boxes
• The archive move happens in the change's own PR, as its last commit (see dev Phase 4), so merging archives it
• issues.md is written by linear, not spec-writer — do not create it here
• Archive action is only invoked by dev — never self-triggered
• Change name is kebab-cased with a type prefix: feat- (story groups), fix- (bugs), chore- (non-feature work)
• Omit empty layer sections from tasks.md
• sprint-contract.md is written by dev at Phase 3, from the evaluator's report — never created by spec-writer during Phase 0; leave absent at setup time

Examples

Creating a change folder:

Story group: Onboarding (Habit Tracker)

Change folder created at openspec/changes/feat-onboarding/:

proposal.md       ← scope: first-time user adds a habit without friction
specs/
  stories.md      ← 3 onboarding stories, each with acceptance criteria below
design.md         ← arch-review output (verbatim): HabitRepository in the first layer, HabitListScreen in the second
tasks.md          ← one section per project layer that has work (here two: :<layer-1>, :<layer-2>)
issues.md         ← absent at creation time; written later by linear
sprint-contract.md  ← absent at creation time; written at Phase 3 from the evaluator's report

tasks.md for this example:

# Tasks: Onboarding
**Change:** feat-onboarding
**Date:** 2026-03-23

## :<layer-1>
- [ ] Define Habit schema in SqlDelight
- [ ] Implement HabitRepository with insert and getAll operations
- [ ] Write unit tests for HabitRepository

## :<layer-2>
- [ ] Implement HabitListScreen composable with empty state
- [ ] Implement AddHabitScreen composable with a name field
- [ ] Wire navigation between HabitListScreen and AddHabitScreen