You are an ADHD-friendly documentation generator. Detect what's needed, generate it all, validate, done.
Automates documentation generation by detecting changes and creating guides, refcards, and demos.
/plugin marketplace add Data-Wise/craft/plugin install data-wise-craft@Data-Wise/craftdocs/You are an ADHD-friendly documentation generator. Detect what's needed, generate it all, validate, done.
The ONE command for documentation:
"Just run it. It figures out what's needed, then does it."
┌─────────────────────────────────────────────────────────────┐
│ /craft:docs:update │
│ │
│ 1. sync (detect changes, classify docs needed) │
│ 2. generate (guide, demo, refcard - as needed) │
│ 3. check (validate + auto-fix) │
│ 4. changelog (if commits present) │
│ 5. summary │
└─────────────────────────────────────────────────────────────┘
# DEFAULT: Smart detection → Full execution of what's needed
/craft:docs:update # Detect changes → generate all needed docs
# FEATURE-SPECIFIC: Full cycle scoped to a feature
/craft:docs:update "sessions" # Document the "sessions" feature
/craft:docs:update "auth system" # Document the "auth system" feature
# FORCE: Do everything regardless of detection
/craft:docs:update --force # Full cycle even if nothing changed
# DRY-RUN: Preview what would happen
/craft:docs:update --dry-run # Show plan without executing
# SKIP PHASES
/craft:docs:update --no-check # Skip validation phase
/craft:docs:update --no-changelog # Skip changelog update
# Analyze recent changes
git diff --name-only HEAD~10
git log --oneline -10
# Classify what docs are needed
# (uses scoring algorithm from doc-classifier)
┌─────────────────────────────────────────────────────────────┐
│ Step 1/5: DETECTING CHANGES │
├─────────────────────────────────────────────────────────────┤
│ │
│ Analyzing 15 recent commits... │
│ │
│ Detected: │
│ • 5 new CLI commands (src/aiterm/cli/sessions.py) │
│ • 2 new hooks (session-register, session-cleanup) │
│ • 1 new module (src/aiterm/sessions/) │
│ │
│ Classification: │
│ Guide needed: ✓ (score: 8) - New module with commands │
│ Refcard needed: ✓ (score: 5) - 5 new commands │
│ Demo needed: ✓ (score: 6) - User-facing CLI workflow │
│ Mermaid needed: ✓ (score: 7) - Hook-based event system │
│ │
└─────────────────────────────────────────────────────────────┘
For each doc type that scored >= 3:
┌─────────────────────────────────────────────────────────────┐
│ Step 2/5: GENERATING DOCS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✓ Guide: docs/guide/sessions.md (275 lines) │
│ - Overview, Quick Start, How It Works │
│ - Commands (5), Configuration, Troubleshooting │
│ │
│ ✓ Refcard: docs/reference/REFCARD-SESSIONS.md (85 lines) │
│ - Essential commands, Common workflows │
│ │
│ ✓ Demo: docs/demos/sessions.tape (34 lines) │
│ - VHS tape for GIF recording │
│ │
│ ✓ Mermaid: embedded in guide │
│ - Hook workflow diagram │
│ │
│ ✓ CLI epilogs: Updated 5 commands │
│ ✓ commands.md: +45 lines │
│ ✓ REFCARD.md: +8 lines (sessions section) │
│ ✓ README.md: Added to features list │
│ ✓ CLAUDE.md: Updated "Just Completed" │
│ ✓ mkdocs.yml: Added 2 nav entries │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Step 3/5: CHECKING DOCS │
├─────────────────────────────────────────────────────────────┤
│ │
│ ✓ Fixed: 2 broken links (auto-fixed) │
│ ✓ Fixed: 1 nav entry (auto-added) │
│ ✓ All new docs validated │
│ │
│ No manual fixes needed. │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Step 4/5: UPDATING CHANGELOG │
├─────────────────────────────────────────────────────────────┤
│ │
│ Found 15 commits since last changelog update. │
│ │
│ Added to CHANGELOG.md: │
│ ### Added │
│ - Session coordination feature │
│ - `ait sessions live/current/task/conflicts/history` │
│ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ ✅ DOCUMENTATION UPDATE COMPLETE │
├─────────────────────────────────────────────────────────────┤
│ │
│ Feature: Session Tracking │
│ │
│ Generated: │
│ • docs/guide/sessions.md (NEW - 275 lines) │
│ • docs/reference/REFCARD-SESSIONS.md (NEW - 85 lines) │
│ • docs/demos/sessions.tape (NEW - VHS demo) │
│ │
│ Updated: │
│ • docs/reference/commands.md (+45 lines) │
│ • docs/REFCARD.md (+8 lines) │
│ • README.md (features list) │
│ • CLAUDE.md (status) │
│ • mkdocs.yml (navigation) │
│ • CHANGELOG.md (session coordination) │
│ │
│ Validated: │
│ • 3 issues auto-fixed │
│ • 0 manual fixes needed │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ NEXT STEPS: │
│ │
│ 1. Generate GIF (if demo created): │
│ cd docs/demos && vhs sessions.tape │
│ │
│ 2. Preview docs: │
│ mkdocs serve │
│ │
│ 3. Commit: │
│ git add docs/ mkdocs.yml CLAUDE.md README.md CHANGELOG.md│
│ git commit -m "docs: add session tracking documentation" │
│ │
└─────────────────────────────────────────────────────────────┘
When a feature name is provided, the cycle is scoped:
/craft:docs:update "auth"
┌─────────────────────────────────────────────────────────────┐
│ /craft:docs:update "auth" │
├─────────────────────────────────────────────────────────────┤
│ │
│ Feature: Authentication │
│ │
│ Scope: Files matching "auth" in name/path │
│ • src/auth/ │
│ • src/**/auth* │
│ • tests/**/test_auth* │
│ │
│ Detected: 3 commands, 1 module, OAuth integration │
│ │
│ Generated: │
│ • docs/guide/auth.md (NEW) │
│ • docs/reference/REFCARD-AUTH.md (NEW) │
│ • Updated 4 existing docs │
│ │
└─────────────────────────────────────────────────────────────┘
| Flag | Effect |
|---|---|
| (none) | Smart detection → generate needed → check → changelog |
"feature" | Scope to specific feature |
--force | Full cycle regardless of detection |
--dry-run | Preview plan without executing |
--no-check | Skip validation phase |
--no-changelog | Skip changelog update |
--no-guide | Skip guide generation |
--no-demo | Skip VHS demo generation |
--verbose | Detailed output |
--json | JSON output |
Doc types are generated based on classification scores:
| Factor | Guide | Refcard | Demo | Mermaid |
|---|---|---|---|---|
| New command (each) | +1 | +1 | +0.5 | +0 |
| New module | +3 | +1 | +1 | +2 |
| New hook | +2 | +1 | +1 | +3 |
| Multi-step workflow | +2 | +0 | +3 | +2 |
| Config changes | +0 | +2 | +0 | +0 |
| Architecture change | +1 | +0 | +0 | +3 |
| User-facing CLI | +1 | +1 | +2 | +0 |
Threshold: Score >= 3 triggers generation
Orchestrates these commands internally:
/craft:docs:sync - Change detection and classification/craft:docs:guide - Guide generation/craft:docs:demo - VHS tape generation/craft:docs:mermaid - Diagram generation/craft:docs:check - Validation and auto-fix/craft:docs:changelog - Changelog updates/craft:docs:claude-md - CLAUDE.md updates/craft:docs:nav-update - mkdocs navigationReplaces:
/craft:docs:feature - Use update "feature-name" instead/craft:docs:generate - Use update --force instead/updateCrées la documentation pour la fonctionnalité en cours. Mets à jour le readme global du projet si nécessaire. Lie les documents entre eux pour ne pas avoir de documentation orpheline. La documentation est générée dans les répertoire de documentation du projet.