vibe-squire

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.

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.

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.

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.

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.