doccraft

Close a story end-to-end — flip its status to a terminal value and reconcile every downstream artifact in one pass: the backlog Status cell, the docs/queue.md row, the parent epic table (when the project uses epics), then a queue-audit reconcile. Use whenever the user says "close", "mark done", "ship", "finish", "complete", or "resolve" a story / ticket / backlog item, or moves work to a terminal state (done, done-no-promote, abandoned, absorbed). Reach for this instead of hand-editing the story file alone — a half-applied close (status flipped but queue/backlog/epic left stale) is exactly the drift this skill exists to prevent. Works for single-root and monorepo projects.

Configure doccraft for this project by tailoring doccraft.json — the vocabulary, id format, queue labels, and session-wrap settings. Two modes: Analyse mode reads the project tree and proposes values for all key fields with reasoning, applying on approval; Edit mode applies a targeted change (e.g. "add area:telemetry") and validates against the embedded schema before writing. Never calls npx — the embedded schema matches the installed doccraft version.

Reconcile the dependency graph, pick-next queue, and backlog status across docs/stories/, docs/queue.md, and docs/backlog.md. Use after adding or editing a story (especially one with depends_on), after reshuffling priorities, or when the user asks "what can I work on next", "what's unblocked", "sanity-check the queue", "check my story dependencies", "fix the queue order", or "what parallel work is ready". In Agent mode (the tool can write files), apply objective mechanical fixes in the same turn and report what changed; in Ask / read-only mode, emit a proposal instead. Stop and report — never guess — on directed cycles, unknown depends_on ids, duplicate ids, or ambiguous editorial reorders.

Author or update product stories (a.k.a. planning docs, backlog items, tickets, specs) as Markdown under docs/stories/ with a YAML frontmatter contract (id, status, impact, urgency, depends_on, tags, openspec). Use this whenever the user is creating a story, reprioritising work, writing acceptance criteria, linking a story to OpenSpec or an ADR, or editing anything under docs/stories/ — even if they call it a spec, ticket, backlog row, or planning doc.

Close a story end-to-end — flip its status to a terminal value and reconcile every downstream artifact in one pass: the backlog Status cell, the {{DOCS_DIR}}/queue.md row, the parent epic table (when the project uses epics), then a queue-audit reconcile. Use whenever the user says "close", "mark done", "ship", "finish", "complete", or "resolve" a story / ticket / backlog item, or moves work to a terminal state (done, done-no-promote, abandoned, absorbed). Reach for this instead of hand-editing the story file alone — a half-applied close (status flipped but queue/backlog/epic left stale) is exactly the drift this skill exists to prevent. Works for single-root and monorepo projects.

Reconcile the dependency graph, pick-next queue, and backlog status across {{DOCS_DIR}}/stories/, {{DOCS_DIR}}/queue.md, and {{DOCS_DIR}}/backlog.md. Use after adding or editing a story (especially one with depends_on), after reshuffling priorities, or when the user asks "what can I work on next", "what's unblocked", "sanity-check the queue", "check my story dependencies", "fix the queue order", or "what parallel work is ready". In Agent mode (the tool can write files), apply objective mechanical fixes in the same turn and report what changed; in Ask / read-only mode, emit a proposal instead. Stop and report — never guess — on directed cycles, unknown depends_on ids, duplicate ids, or ambiguous editorial reorders.

Author or update product stories (a.k.a. planning docs, backlog items, tickets, specs) as Markdown under {{DOCS_DIR}}/stories/ with a YAML frontmatter contract (id, status, impact, urgency, depends_on, tags, openspec). Use this whenever the user is creating a story, reprioritising work, writing acceptance criteria, linking a story to OpenSpec or an ADR, or editing anything under {{DOCS_DIR}}/stories/ — even if they call it a spec, ticket, backlog row, or planning doc.

After a design, research, business, or prioritisation thread, evaluate whether the conversation produced durable insight worth capturing in docs/, then propose only the artifacts that are clearly justified (ADR, research note, reference doc, business update, story, backlog/queue edit). Use when the user says "wrap this session", "propose docs artifacts", "what should we capture", "summarize this into docs", "end-of-session", or similar close-out phrasing. If nothing warrants capture, say so in one sentence and stop. Never write files unless the user explicitly asks to create or update them in the same turn — propose drafts only.

Update the installed doccraft skills and openspec instructions to the latest release. Reads the version stamp from doccraft.json, fetches the migration manifest via npx doccraft@latest llm, and either updates silently (dominant path — no migration entries) or summarises and gates on approval (assisted path — migration entries present). Never fabricates steps the manifest did not declare.

Update the installed doccraft skills and openspec instructions to the latest release. Reads the version stamp from doccraft.json, fetches the migration manifest via npx doccraft@latest llm, and either updates silently (dominant path — no migration entries) or summarises and gates on approval (assisted path — migration entries present). Never fabricates steps the manifest did not declare.

Configure doccraft for this project by tailoring doccraft.json — the vocabulary, id format, queue labels, and session-wrap settings. Two modes: Analyse mode reads the project tree and proposes values for all key fields with reasoning, applying on approval; Edit mode applies a targeted change (e.g. "add area:telemetry") and validates against the embedded schema before writing. Never calls npx — the embedded schema matches the installed doccraft version.

After a design, research, business, or prioritisation thread, evaluate whether the conversation produced durable insight worth capturing in {{DOCS_DIR}}/, then propose only the artifacts that are clearly justified (ADR, research note, reference doc, business update, story, backlog/queue edit). Use when the user says "wrap this session", "propose docs artifacts", "what should we capture", "summarize this into docs", "end-of-session", or similar close-out phrasing. If nothing warrants capture, say so in one sentence and stop. Never write files unless the user explicitly asks to create or update them in the same turn — propose drafts only.

Author or update architecture decision records (a.k.a. ADRs, design decisions, architecture decision log entries) under docs/adr/ as NNN-kebab-case.md with Nygard-style Context, Decision, Consequences, and an explicit Status. Use whenever the user is recording a new decision, superseding an old one, capturing a rejected option so the team doesn't revisit it, or editing anything under docs/adr/ — even if they call it a design note, tech decision, or RFC outcome.

Author or update architecture decision records (a.k.a. ADRs, design decisions, architecture decision log entries) under {{DOCS_DIR}}/adr/ as NNN-kebab-case.md with Nygard-style Context, Decision, Consequences, and an explicit Status. Use whenever the user is recording a new decision, superseding an old one, capturing a rejected option so the team doesn't revisit it, or editing anything under {{DOCS_DIR}}/adr/ — even if they call it a design note, tech decision, or RFC outcome.