spec

/ticket-flow:spec — Create item spec from template

Args: <kanban-id> (required, numeric) · <author> (optional, default: git config user.name, fallback $USER) · --auto (optional, position-independent — non-interactive full draft)

Examples:

• /ticket-flow:spec 94 → drafting author = git config user.name (e.g. Jane Doe)
• /ticket-flow:spec 80 agent → drafting author = agent
• /ticket-flow:spec 80a agent → for split sub-items (letter suffix allowed)
• /ticket-flow:spec 94 --auto → full autonomous draft, no questions, Kanban note → spec: review

Prerequisites

• The item must already exist as a tracked ticket: a bd issue (raw bd-id, or a kanban-<id> label for numeric ids).
• Items in ROADMAP.md are out of scope — triage them into bd first.
• Template: docs/specs/SPEC-TEMPLATE.md (in the project).

Steps

1. Find the item — resolve the bd issue, do not read KANBAN.md:

   source "${CLAUDE_PLUGIN_ROOT}/skills/kanban/bd-helper.sh"
   BD_ID="$(bd_id_for "$id")"   # raw bd-ids pass through; numeric ids scan kanban-<id> labels
   

   Empty BD_ID → error ("item # not tracked in bd").

2. Extract fields — from bd show "$BD_ID" --json: tag from issue_type (bug/feature/task→change), title, note from the bd notes field, cluster from a cluster-<marker> label if present (else -).

   No date is extracted in either mode — neither bd's display nor KANBAN.md's four columns (# · Tag · Title · Note) store a creation date. The frontmatter created: is set in step 6.

3. Build the slug:

   • Lowercase the title, map umlauts (ä→a, ö→o, ü→u, ß→ss), all special chars → -, collapse multiple - → single -, strip leading/trailing -
   • Max 50 chars, cut at word boundary
   • Examples: "Add user authentication" → add-user-authentication; "Refactor session-token-storage layer" → refactor-session-token-storage-layer

4. Target path: docs/specs/${id}-${slug}.md. If the file already exists → error ("Spec already exists: ") and no KANBAN update.

5. Read the template: Read docs/specs/SPEC-TEMPLATE.md.

6. Fill the frontmatter:

   ---
   id: <id>
   title: <title>
   tag: <tag>
   cluster: <cluster or "->
   created: <today>
   status: draft
   reference-fork: none
   subitems: false
   testable-surface: none
   ---
   

   id / title / tag / cluster are verbatim from the step-2 fields. created: is today's date (date +%F) — KANBAN.md stores no creation date, and the field records when this spec doc was written, which is today. The optional fields (reference-fork, subitems, testable-surface) default to the safe values above; interactive mode leaves them for the spec author to update, --auto populates them per the rules below.

7. Title heading in the template: replace # <Title> with # ${title} (no cluster marker).

8. Keep the rest verbatim — the spec author fills it in. The template's body sections are: Context, Acceptance Criteria, Out of Scope, Reference Fork (Cherry #7), Testable Surfaces (Cherry #1), Sub-Items (Cherry #6), References, Notes. (In --auto mode the agent fills the body instead — see Autonomous mode (--auto) below.)

9. Write the filled spec to the target path.

10. Surface the spec link + status marker — write to bd only. Do not touch KANBAN.md (a board snapshot is available on demand via /ticket-flow:board):