/craft-docs

name: docs
description: "Generate or update project documentation using the crystallized doc-writer agent. Two-pass: brief (analysis + plan) then generate (write docs). Detects first-run vs update automatically."
argument-hint: "[continue | --scope=<path>]"

Docs

Generate quality GitHub documentation for any craft project. Uses the crystallized doc-writer agent for both analysis and writing. Two passes - brief then generate - with a human gate in between.

Project Root

Use `$CRAFT_PROJECT_ROOT` (set at session start) as the base path. If not set, resolve by walking up from PWD to find the nearest `.craft/.global-state`.

Set `PROJECT` to `${CRAFT_PROJECT_ROOT:-.}`.

Flow

Step 0: Determine Run Context

Parse args:

• **"continue"** - Resume from an existing brief. Jump to **Step 3**.
• **"--scope=path"** - Scope the analysis to a subdirectory. Store as `SCOPE`.
• **No args** - Full project analysis.

Step 1: Detect State

Check what already exists:

# Check for existing brief
BRIEF="$PROJECT/.craft/docs/brief.md"

# Check for existing docs
README=$(ls "$PROJECT"/README.md "$PROJECT"/README.MD 2>/dev/null | head -1)
DOCS_DIR=$(ls -d "$PROJECT"/docs/ 2>/dev/null)

Also check for craft-specific sources of truth:

• `$PROJECT/CLAUDE.md`
• `$PROJECT/.craft/design/locked.md`
• `$PROJECT/.craft/project.md`

**If an unapproved brief exists** (status: draft in frontmatter):

Use **AskUserQuestion**:

question: "Found a draft brief from {date}."
header: "Resume"
options:
  - label: "Continue with this brief"
    description: "Review and approve the existing brief"
  - label: "Start fresh"
    description: "Generate a new brief"

**If "Continue"** -> Jump to **Step 2e** (Present Brief). **If "Start fresh"** -> Continue to **Step 2** (Investigate).

**Determine mode based on what exists:**

• No README, no docs/ -> `MODE=first-run`
• README or docs/ exists -> `MODE=update`

Step 2: Investigate Documentation Health

Create the brief directory:

mkdir -p "$PROJECT/.craft/docs"

Step 2a: Gather Context

**For update mode**, gather git changes since the last docs run:

LAST_DOCS_DATE={date from existing brief frontmatter, e.g. 2026-04-17}
GIT_LOG=$(git log --oneline --since="$LAST_DOCS_DATE" -- . ':!.craft/cycles' ':!.craft/backlog')
GIT_DIFF_STAT=$(git diff $(git log --since="$LAST_DOCS_DATE" --format="%H" --reverse -- . | head -1)^..HEAD --stat -- . ':!.craft/cycles' ':!.craft/backlog' 2>/dev/null || echo "Unable to compute diff stat")

**Check for PR review findings:**

REVIEW_FINDINGS="$PROJECT/.craft/docs/review-findings.md"

If the file exists, read its contents. These are known doc-drift issues flagged by `craft:review`.

Step 2b: Dispatch Explore Agent

Read the doc standards reference file: `${CLAUDE_PLUGIN_ROOT}/commands/references/doc-standards.md` (from the plugin, not the project). This defines what the Explore agent should look for.

Dispatch an **Explore agent** via the Agent tool with `subagent_type: "Explore"`. The prompt adapts to mode.

**First-run prompt:**

You are investigating a project's documentation health. Your job is to find what's
stale, missing, or uncertain - NOT to write the brief. That happens later.

Read the doc standards reference first - it defines what "current" means and how
to handle uncertainty:

[Paste full contents of ${CLAUDE_PLUGIN_ROOT}/commands/references/doc-standards.md]

Project root: {PROJECT}
Scope: {SCOPE or "full project"}

{If REVIEW_FINDINGS exists:}
## Known Issues from PR Reviews
The following doc-drift findings were flagged by recent PR reviews. Investigate
each one and include them in your findings, attributed as "flagged by PR review":
{REVIEW_FINDINGS content}

Investigate:
1. Glob for ALL .md files (excluding node_modules, .git, .craft/cycles, .craft/backlog, .craft/research)
2. Read each doc and check claims against the codebase
3. Check CLAUDE.md, .craft/project.md, .craft/design/locked.md for source alignment
4. Look for undocumented subsystems or features

Report your findings using the format defined in the doc standards reference.
Group by confidence level (high first). Be honest about uncertainty.
Report in under 800 words.

**Update prompt:**

You are investigating documentation drift for a project. Your job is to find what's
stale since the last docs update - NOT to write the brief. That happens later.

Read the doc standards reference first - it defines what "current" means and how
to handle uncertainty:

[Paste full contents of ${CLAUDE_PLUGIN_ROOT}/commands/references/doc-standards.md]

Project root: {PROJECT}
Scope: {SCOPE or "full project"}

## Git Changes Since Last Docs Update ({LAST_DOCS_DATE})
### Commit Log
{GIT_LOG}
### Diff Stats
{GIT_DIFF_STAT}

Use these changes as your primary investigation guide. Every commit is a potential
documentation gap. For renames or terminology changes, grep for the OLD term to
find stale references.

{If REVIEW_FINDINGS exists:}
## Known Issues from PR Reviews
The following doc-drift findings were flagged by recent PR reviews. Investigate
each one and include them in your findings, attributed as "flagged by PR review":
{REVIEW_FINDINGS content}

Investigate:
1. Glob for ALL .md files (excluding node_modules, .git, .craft/cycles, .craft/backlog, .craft/research)
2. For each doc, check if the git changes made any of its claims stale
3. Check CLAUDE.md, .craft/project.md, .craft/design/locked.md for source alignment
4. Look for terminology drift between docs and current code

Report your findings using the format defined in the doc standards reference.
Group by confidence level (high first). Be honest about uncertainty.
Every existing doc should appear as either "current" or with specific staleness findings.
Report in under 800 words.

**Save the Explore agent's ID** for potential follow-up via SendMessage.

Step 2c: Surface Findings via AskUserQuestion

Read the Explore agent's fin