docs

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")