jaisonerick/build-stories

Your task: break a spec into ordered stories sized for a single AI agent session, and create them as sub-issues under the spec issue in Linear.

Linear contract

Scripts live in ${CLAUDE_PLUGIN_DIR}/scripts/linear/. Required: LINEAR_API_KEY. If it isn't set, fetch it from 1Password: export LINEAR_API_KEY="$(op read op://Environments/Linear/credential)".

Created shape:

Issue   Spec vX.Y — short name        (parent)
├─ Sub-issue   001 — engineer — ...
├─ Sub-issue   002 — designer — ...
└─ Sub-issue   003 — engineer — ...

The numeric prefix on the title (NNN — agent — ...) makes ordering and agent-type visible at a glance — Linear has no story-index document, the parent's child list is the index.

Phase 0 — Resolve the spec issue

Argument is an identifier or free text. If text:

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/search.js" --type issue --query "<text>" --label "type/spec" --limit 5

Then:

node "${CLAUDE_PLUGIN_DIR}/scripts/linear/resolve-spec.js" "<identifier>" --require-spec-label

Capture: issue.id, issue.identifier, issue.description, project.id, team.key, existing sub-issues.

If the spec issue already has sub-issues, ask via AskUserQuestion:

• Append new stories
• Replace (and confirm — sub-issues will not be deleted automatically; the agent will list them and the user decides which to close manually)
• Abort

Phase 1 — Load Knowledge-Base & Architecture

1. Read the spec body (the issue description from resolve-spec.js). Pay special attention to Definition of Done — the final story or stories must directly satisfy it.
2. Read the spec architecture document. Find it in project.documents by title Spec vX.Y — Architecture. Use list-documents.js --title-match to confirm. Read its content.
3. Read the deliverable architecture document (Architecture on the same project) for cross-cutting decisions.
4. Read the project briefing on disk (path in the project's Context: line) for project type and code repository path.
5. Scan the existing workspace (and code repo if specified) to understand what's already built/written.

Phase 2 — Decompose into Stories

Break the spec into stories following these principles:

Sizing for AI Agents (NOT human teams)

• Optimize for AI agent context window: each story must be completable without overwhelming the agent
• A story that touches 15 files across 3 layers is too broad
• A story that creates one config file is too narrow
• Sweet spot: one cohesive concern per story

Agent Assignment

Every story specifies its agent — the agent type that will execute it:

For code projects:

• engineer — Backend, data layer, API endpoints, integrations, tests, wiring UI. Runs /execute-task.
• designer — Visual UI creation: new pages, components, layouts, design system. Runs /interface-design.

For non-code projects:

• engineer — The default executor. Runs /execute-task for any deliverable type (documents, analyses, research outputs).

The orchestrator uses this field directly as subagent_type when spawning agents.

The Design → Engineer Pipeline (Code Projects Only)

For features with UI, use paired stories:

1. Design story (agent: designer) — Creates visual components/layouts
2. Integration story (agent: engineer) — Wires design into codebase

Not every UI story needs pairing. Use judgment.

Testing in Stories (Code Projects)

Each engineer story must include testing acceptance criteria proportional to complexity:

• Complex logic: thorough unit tests
• Key components: at least one test pass
• Simple glue: no dedicated tests
• Integration stories: at least one integration test

Include a ## Testing Guidance section in each code story.

Verification in Stories (Non-Code Projects)

Each story should include clear acceptance criteria that can be verified by reading/reviewing the output:

• Completeness: does the deliverable cover everything specified?
• Quality: does it meet the standards described in the architecture?
• Accuracy: are facts, references, and claims correct?

Ordering

• Foundation/prerequisite stories come first
• For code: data layer → API → UI
• Design stories before their integration stories
• Each story produces a working increment
• Reflect the order in the numeric prefix of every sub-issue title (001 — ..., 010 — ..., 020 — ...).

Self-containment

• Include enough context in each story body that the executing agent doesn't need to read 10 other documents
• Inline the relevant architecture decisions

Phase 3 — Show the user the plan

Before creating any sub-issues, present the proposed story list to the user as a numbered table (number, agent, title, depends-on). Iterate via AskUserQuestion until they approve.

Phase 4 — Create Sub-Issues in Linear

For each approved story, create a sub-issue under the spec issue. Stage the body to /tmp/linear-spec/<spec-id>/NNN-slug.md and run:

cat /tmp/linear-spec/<spec-id>/NNN-slug.md | \
  node "${CLAUDE_PLUGIN_DIR}/scripts/linear/create-sub-issue.js" "<spec-identifier>" \
    --title "NNN — <agent> — <story title>" \
    --state "Backlog"

Story body template (sub-issue description):

**Agent**: `engineer` | `designer`
**Spec**: <link to parent spec issue, e.g. DIN-142>

## Summary
One paragraph describing what this story delivers.

## Prerequisites
- What must exist before starting (prior story identifiers, inputs, access)

## Deliverables
- What exists after completion (new files, endpoints, documents, analyses)

## Acceptance Criteria
- [ ] Concrete, verifiable condition 1
- [ ] Concrete, verifiable condition 2

## Implementation Guidance
Specific guidance on how to produce the deliverable. For code: files to create/modify, patterns to follow. For non-code: sources to use, structure to follow, quality standards.

## Testing Guidance (code projects)
What to test, at what level, and any fixtures needed.

## Architecture Context
Inline the relevant decisions from the spec architecture so the executor doesn't need to cross-reference.

## References
- [Spec architecture document](<architecture doc URL>)
- Parent spec: <DIN-XXX>

Capture each created sub-issue's identifier and URL — return them as a list to the user.

Phase 5 — Final Review

Present:

• Parent spec URL
• Created sub-issues (identifier, title, agent)
• Any uncertainty or risk
• Suggested next step: "Run /orchestrate <spec-identifier> to execute the spec, or /execute-task <story-identifier> for a single story."