spec-to-issues

---
name: spec-to-issues
description: Turns an approved spec or roadmap item into scoped, single-repo agent:implement issues with testable acceptance criteria and an explicit out-of-scope block. Use when asked to "break down this spec", "turn this into issues", "scope this roadmap item", "create implementation issues", or "plan the work for this feature". Use when a spec is approved and needs to become the tickets a fleet can pick up.
license: MIT
---

# Spec to issues

## When to use

- A spec or roadmap item is APPROVED and someone asks to turn it into work.
- You are handed a design doc and told to "make issues out of this".
- A feature touches more than one repo and needs to be split so each issue is
  single-repo and independently mergeable.
- Before any implementation firing runs: a good issue is what makes an
  autonomous run land cleanly instead of sprawling.

Do NOT use this to invent scope. If the spec is a draft or the goal is unclear,
stop and say so. Issues derived from a fuzzy spec produce fuzzy PRs.

## Procedure

1. Read the spec. Confirm it has the minimal shape (goal, current behavior,
   target behavior, acceptance criteria, out-of-scope). If it does not, see
   `references/spec-shape.md` and ask for the missing pieces before scoping.
2. Identify the repos the spec touches. One issue per repo. If a single repo's
   work is large, split it along a seam a reviewer can verify independently
   (an endpoint, a screen, a migration), never along "part 1 / part 2" of the
   same file.
3. Order the issues by dependency. If `your-backend` must ship an endpoint
   before `your-frontend` can call it, say so in each issue's first line
   ("Depends on: your-backend #NN") so the fleet does not start the dependent
   work early.
4. For each issue write:
   - A one-line title in the form `feat(<area>): <verb> <thing>`.
   - A short context paragraph: what the spec wants and why this slice exists.
   - Acceptance criteria as a checklist, each verifiable by a named command,
     endpoint, screen, or file. "Works correctly" is not a criterion; "GET
     /v1/widgets returns 200 with a paginated list" is.
   - A test line: what the PR must test (derive from the criteria).
   - An **Out of scope** block naming what this issue must NOT change. This is
     what keeps an autonomous run from wandering into unrelated code.
5. Label each issue `agent:implement` and set the single repo. Do not create a
   multi-repo issue; the fleet fires one repo per run.
6. Re-read the set as a whole: every acceptance criterion in the spec must be
   covered by exactly one issue, and no issue should carry criteria the spec
   never asked for.

## Output

A list of ready-to-file issues. For each: title, repo, context, acceptance
criteria checklist, test line, and an out-of-scope block. End with a coverage
line mapping each spec acceptance criterion to the issue that owns it, so a
reviewer can confirm nothing was dropped or invented. Never auto-file the
issues; present them for approval first.

Follow the caller's local output contract exactly. If the caller requests a
file, write that file. If the caller requests JSON, write valid JSON with the
requested top-level shape and no Markdown wrapper. The approval gate blocks
external API calls that create issues. It does not block writing the requested
local draft.

More agent context in luminik-io/alfred

13 other files this repository gives its agents.