@esthernandez/vibe-doc 0.2.2 → 0.3.0

package/skills/generate/SKILL.md

@@ -0,0 +1,359 @@
+---
+name: generate
+description: >
+  This skill should be used when the user mentions "generate docs",
+  "write my documentation", "fix my gaps", "create a runbook",
+  "write the threat model", "generate missing docs", or wants to
+  produce technical documentation from their project artifacts.
+  Runs an autonomous-first workflow: reads project files, synthesizes
+  as much as possible without asking, then interviews the user only
+  for the sections that genuinely need human judgment.
+---
+
+# Vibe Doc Generate Skill
+
+Autonomous-first pipeline: read the project, fill what you can, then ask the user only for the sections that need human judgment.
+
+**Shared behavior:** Read `skills/guide/SKILL.md` for state management, CLI patterns, checkpoints, and output formatting.
+
+---
+
+## Design Intent
+
+The old model was **agent-interviewed, user-informed**: the agent asked 2-3 synthesis questions per doc type and the user answered them all. That's overkill for factual docs whose content lives in the codebase.
+
+The new model is **autonomous-first**:
+
+1. **Read the project files directly** — README, CLAUDE.md, package.json, SKILL files, source entry points, git history, CI configs
+2. **Synthesize confidently** from what you read — fill in template sections where you have strong evidence
+3. **Interview only for the gaps** — ask targeted questions for the sections where code can't tell you the answer (security judgment, business intent, operational context the team knows but hasn't written down yet)
+4. **Present the result** — show the user what you filled in, what you left as NEEDS INPUT, and let them review
+
+The CLI (`vibe-doc generate <doctype>`) still produces the deterministic scaffold. This skill layers intelligence on top: same scaffold, but the agent keeps going and fills it in from the codebase before handing off to the user.
+
+---
+
+## Entry: Verify Scan State
+
+```bash
+if [ ! -f "<project-path>/.vibe-doc/state.json" ]; then
+  echo "No project profile found. Run the Scan skill first."
+  exit 1
+fi
+```
+
+If state doesn't exist, redirect to the **Scan skill** and exit.
+
+---
+
+## Main Flow
+
+### 1. Present Gaps and Confirm Selection
+
+Read state and show gaps grouped by tier:
+
+```
+Documentation Gaps — <Category>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Required (ship blockers) — N missing:
+  □ README
+  □ Install Guide
+  □ Skill/Command Reference
+
+Recommended (should do) — M missing:
+  □ ADRs
+  □ Test Plan
+  □ Changelog / Contributing
+
+Which would you like to generate?
+
+[required] Start with all Required docs (runs autonomous fill in parallel)
+[pick]     Let me choose specific docs
+[<name>]   Single doc by name
+[all]      Every missing doc, Required + Recommended + Optional
+```
+
+**Do not default to "all"** unless the user asks for it. More docs = slower, more tokens, more noise.
+
+---
+
+### 2. Route by Count
+
+- **Single doc selected** → go to **Section 3: Autonomous Fill (single doc)**
+- **Multiple docs selected** → go to **Section 4: Parallel Dispatch (multiple docs)**
+
+---
+
+### 3. Autonomous Fill (Single Doc)
+
+Follow these steps, in order, for each doc to generate.
+
+#### 3a. Run the CLI for the scaffold
+
+```bash
+cd <project-path> && npx vibe-doc generate <docType> --format both
+```
+
+This produces `docs/generated/<docType>.md` with deterministic-extractor fields pre-filled and `NEEDS INPUT` comments marking the gaps.
+
+Read the scaffold back so you can edit it in place.
+
+#### 3b. Gather source material
+
+Read the files most relevant to this doc type. Use the hint table below; add files based on what the scan inventory shows.
+
+| Doc Type | Read These Files |
+|----------|------------------|
+| **readme** | `package.json`, `CLAUDE.md`, any existing `README.md`, main source entry file (e.g., `src/index.ts`), `docs/` summaries |
+| **install-guide** | `package.json` (engines, scripts, bin), any existing `INSTALL.md`, CI configs (`.github/workflows/*.yml`), install-related scripts |
+| **skill-command-reference** | every `skills/*/SKILL.md`, every `commands/*.md`, `.claude-plugin/plugin.json` |
+| **changelog-contributing** | `git log --oneline -100`, any existing `CHANGELOG.md`, any existing `CONTRIBUTING.md`, `package.json` version history |
+| **adr** | `CLAUDE.md`, commit messages with "decision:" or "arch:" prefixes, any `docs/adr/` or `docs/decisions/` folder |
+| **runbook** | `package.json` scripts, `Dockerfile`, `.github/workflows/*.yml`, any `scripts/` folder, any deploy config |
+| **api-spec** | Route/controller source files, `openapi.yaml`, `swagger.json`, any existing API docs |
+| **deployment-procedure** | `.github/workflows/*.yml`, `Dockerfile`, deploy scripts, cloud infra configs (terraform, cdk, pulumi) |
+| **test-plan** | Test files, test runner configs (`jest.config.*`, `pytest.ini`), CI test stages |
+| **data-model** | Schema/migration files, ORM model files, database config |
+| **threat-model** | Auth code, permission logic, sensitive-data handling, external API clients, secrets config |
+
+For each file, extract what's relevant to the template's sections. Ignore irrelevant content.
+
+#### 3c. Fill the template autonomously
+
+Open the scaffold at `docs/generated/<docType>.md`. For each `NEEDS INPUT` comment:
+
+1. **Can you synthesize this section from what you read?** If yes, replace the empty block (or the `{{user.*}}` placeholder still sitting there) with real content. Remove the `NEEDS INPUT` comment to signal the section is filled.
+2. **Do you need human judgment?** If yes, leave the `NEEDS INPUT` comment in place. These will become the questions you ask the user in the next step.
+
+**Rules for autonomous fills:**
+
+- **Cite your sources inline** — at the end of a section you wrote, add a markdown comment: `<!-- Source: package.json, README.md -->`. This lets the user verify your work quickly.
+- **Don't fabricate.** If a section would require making something up (an SLA target you don't see, a rollback procedure that isn't documented), leave it as NEEDS INPUT. Confident content only.
+- **Prefer brevity over padding.** A 3-sentence section filled from real evidence beats a 3-paragraph section of boilerplate.
+- **Match the existing doc's voice.** Read at least one existing doc in the repo (README is usually a good reference) to calibrate tone.
+
+Write the filled-in doc back to `docs/generated/<docType>.md`.
+
+#### 3d. Interview the user for remaining gaps
+
+Present a summary:
+
+```
+✓ Autonomous pass complete — docs/generated/<docType>.md
+
+Filled from codebase:
+  • <section A> — from <source files>
+  • <section B> — from <source files>
+  • <section C> — from <source files>
+
+Still need your input:
+  • <section X> — <why the agent couldn't fill it>
+  • <section Y> — <why the agent couldn't fill it>
+
+I'll ask about those two now. If you'd rather fill them yourself
+later, say "defer" and I'll leave the NEEDS INPUT comments.
+```
+
+Then ask **one question at a time** for each remaining gap. Each question should be specific, reference the context, and accept short answers:
+
+```
+Question 1 of 2: <section X>
+
+<one-sentence explanation of what this section is for>
+
+From what I read, you have <X, Y, Z>. What's the <specific thing>?
+```
+
+Capture each answer and update the doc in place. When all questions are answered, remove the `NEEDS INPUT` comments for those sections.
+
+#### 3e. Present for review
+
+```
+✓ <docType>.md is ready for review.
+
+Coverage:
+  • Sections filled autonomously: N
+  • Sections filled from your answers: M
+  • Sections still marked NEEDS INPUT: 0 (or K if deferred)
+
+Open: docs/generated/<docType>.md
+
+[approve]  Move to next doc (or finish if last)
+[revise]   Ask different questions / read more files / regenerate
+[edit]     I'll wait while you edit manually, then approve
+[defer]    Mark remaining gaps as NEEDS INPUT and move on
+```
+
+---
+
+### 4. Parallel Dispatch (Multiple Docs)
+
+When the user selects multiple docs, **dispatch one subagent per doc type in parallel** using the Task tool. This is the recommended path — it's faster and each agent gets a focused slice of the codebase to read.
+
+#### 4a. Plan the dispatch
+
+For each selected doc, build a subagent prompt that covers Section 3a-c (scaffold + read sources + fill autonomously). Do **not** include the conversational interview (Section 3d) in the subagent prompt — that happens in the main agent after all subagents return, so questions don't interleave.
+
+Subagent prompt template:
+
+```
+You are generating documentation for a <Category> project at <project-path>.
+
+Task: Produce a fully-filled `docs/generated/<docType>.md` from the project's
+existing artifacts. Do NOT ask the user questions — fill only what you can
+confidently synthesize from source files, and leave NEEDS INPUT comments for
+anything you can't.
+
+Steps:
+1. Run: `cd <project-path> && npx vibe-doc generate <docType> --format both`
+2. Read the generated scaffold at docs/generated/<docType>.md
+3. Read these source files: <from the hint table, plus inventory-specific adds>
+4. For each NEEDS INPUT section in the scaffold:
+   - If you can fill it confidently from what you read, replace it with real
+     content and add an inline <!-- Source: ... --> comment
+   - If you can't, leave the NEEDS INPUT comment so the main agent can ask the user
+5. Write the updated doc back to docs/generated/<docType>.md
+6. Report back with: (a) which sections you filled, (b) which sections still
+   need human input, (c) anything suspicious you noticed in the artifacts
+
+Do not dispatch further subagents. Do not run the interview. Return findings
+to the main agent.
+```
+
+#### 4b. Dispatch in parallel
+
+Use the Task tool to fire all subagents in the same message. Each subagent runs independently and edits its own doc.
+
+#### 4c. Collect results
+
+When all subagents return, aggregate their findings:
+
+```
+✓ Autonomous pass complete — <N> docs
+
+docs/generated/readme.md
+  Filled: overview, install, usage, license
+  Needs input: configuration (no .env.example found)
+
+docs/generated/install-guide.md
+  Filled: prerequisites, install steps, verification
+  Needs input: troubleshooting (no existing error documentation)
+
+docs/generated/skill-command-reference.md
+  Filled: all sections (found 8 SKILL files and 4 command definitions)
+  Needs input: none — ready to ship
+
+Total: <X> sections filled autonomously, <Y> need your input.
+```
+
+#### 4d. Sequential interview for gaps
+
+Now run the interview phase (Section 3d) **sequentially** across all docs — for each doc that has unfilled gaps, ask its questions one at a time, update the doc, move to the next. Don't interleave questions across docs; the user needs to stay focused on one doc at a time.
+
+#### 4e. Present all docs for review
+
+```
+Generation complete ✓
+
+Ready for review:
+  • docs/generated/readme.md             (0 gaps remaining)
+  • docs/generated/install-guide.md      (0 gaps remaining)
+  • docs/generated/skill-command-reference.md  (0 gaps remaining)
+
+Coverage improved: <before>% → <after>% (<n> Required docs satisfied)
+
+Open each file to review. When you're ready, you can promote them to the
+repo root (README.md, INSTALL.md, etc.) or keep them in docs/generated/
+as a staging area.
+
+[approve-all]  Done, docs are good
+[revise <name>]  Re-run autonomous fill on one doc with different focus
+[promote]     Move files from docs/generated/ to the repo root
+```
+
+---
+
+## When to Fall Back to the Pure Interview Flow
+
+The autonomous-first flow works well for docs whose content lives in the codebase. It works **less well** for docs where the substance is judgment, intent, or future plans — specifically:
+
+- **Threat Model** — requires security reasoning the agent shouldn't invent
+- **ADRs for decisions not yet documented** — the "why" is in someone's head
+- **Deployment Procedure for an app that hasn't deployed yet** — no evidence exists
+- **Data Model for a pre-alpha app** — no schema yet
+
+For these, default to a **short autonomous pass** (fill only what's obviously there) and spend most of the time in the interview phase. Lean on the synthesis questions from `skills/guide/references/breadcrumb-heuristics.md`.
+
+---
+
+## Anti-Patterns
+
+- **Never fabricate.** If you don't have evidence, leave NEEDS INPUT. A scaffold with honest gaps is better than a polished doc that's half hallucination.
+- **Never cite sources you didn't read.** Inline source comments must point to files the agent actually opened.
+- **Don't auto-promote generated files.** `docs/generated/` is a staging area. Moving files to the repo root (README.md, INSTALL.md, CHANGELOG.md) is always an explicit user action.
+- **Don't ask questions the code already answers.** Before asking a question, re-verify you couldn't have derived it from a file you haven't read yet.
+- **Don't interleave questions across docs** in the parallel path. One doc at a time for the interview phase, even if the autonomous passes ran in parallel.
+
+---
+
+## Error Handling
+
+### CLI scaffold generation fails
+
+```
+The scaffold step failed: <error>
+
+This usually means:
+  • The doc type isn't registered (check `vibe-doc templates list`)
+  • The template file is missing from the install
+  • A filesystem error blocked writing to docs/generated/
+
+[retry] Try again
+[skip]  Skip this doc and move to the next
+```
+
+### Autonomous pass runs out of context
+
+If reading too many source files would exceed a reasonable context budget, narrow the scope:
+
+- Read only the top 10-15 files most relevant to the doc type
+- Prefer summary files (READMEs, CLAUDE.md, SKILL.md) over large source files
+- Skim rather than read exhaustively — you're looking for evidence, not comprehension
+
+### Subagent returns with everything marked NEEDS INPUT
+
+If a subagent couldn't fill any sections, it probably got the wrong doc type or the repo genuinely has no evidence. Options:
+
+- Fall back to the pure interview flow for that doc
+- Skip that doc (not everything should be generated for every project)
+- Ask the user to point the agent at the right files manually
+
+---
+
+## State & Output
+
+**Read from `.vibe-doc/state.json`:**
+- Classification (to pick the right doc types)
+- Gaps list (to know what's missing)
+- Artifact inventory (to know which files to read during autonomous pass)
+
+**Write to:**
+- `docs/generated/<docType>.md` — the filled-in doc (autonomous + interview results)
+- `docs/generated/<docType>.docx` — DOCX version from the CLI scaffold pass
+- `.vibe-doc/state.json` — generation history (file paths, timestamps)
+
+**Files the agent should NOT modify:**
+- Repo-root docs (README.md, INSTALL.md, CHANGELOG.md) — promotion is explicit user action
+- Source code — docs generation is read-only on the codebase
+- `.vibe-doc/state.json`'s `classification` or `gapReport` blocks — those are owned by scan/check skills
+
+---
+
+## Synthesis Questions Reference
+
+When the interview phase is needed, question sets per doc type live in `skills/guide/references/breadcrumb-heuristics.md`. Each breadcrumb's `gapQuestions` field is a pre-written list of targeted questions for that doc type — use them as a starting point and adapt to what you already filled in.
+
+---
+
+**Last updated:** 2026-04-15 | **Version:** 2.0 (autonomous-first)

package/skills/guide/AGENT_GUIDE.md

@@ -0,0 +1,318 @@
+# Agent Guide — How to Use Vibe Doc Skills
+
+**This is for agents.** When a user invokes a Vibe Doc skill, read the corresponding SKILL.md file and follow its conversational pipeline exactly.
+
+---
+
+## Quick Reference
+
+| Skill | File | Purpose | User-Facing? |
+|-------|------|---------|--------------|
+| **scan** | `scan/SKILL.md` | Scan artifacts, classify app, report gaps | YES |
+| **generate** | `generate/SKILL.md` | Generate selected documentation | YES |
+| **check** | `check/SKILL.md` | Validate Required docs exist and are current | YES |
+| **guide** | `guide/SKILL.md` | Shared behavior (reference only) | NO |
+
+---
+
+## Skill Invocation Pattern
+
+When a user says something like:
+- "Scan my project for documentation gaps"
+- "Help me generate missing docs"
+- "Check if my docs are current"
+
+The agent should:
+
+1. **Identify the skill:** Map user request to scan/generate/check
+2. **Read the SKILL.md:** Open the corresponding file and read the full conversational flow
+3. **Follow the pipeline:** Execute step-by-step as defined in the SKILL.md
+4. **Reference guides:** Consult `skills/guide/references/` when needed (see below)
+5. **Maintain state:** All skills interact with `.vibe-doc/state.json` via CLI commands
+6. **Respect checkpoints:** Pause and ask for user confirmation at critical gates
+
+---
+
+## Step-by-Step: Scan Skill
+
+User: "Scan my project for documentation gaps"
+
+1. **Read** `skills/scan/SKILL.md`
+2. **Section 1 — Entry Gate:**
+   - Greet user
+   - Present two paths: "Add context first" or "Start scanning"
+   - Wait for choice
+3. **If Path A (Add context):**
+   - Go to section 2 (Intake Interview)
+   - Ask 6 questions, save answers
+4. **If Path B (Cold start):**
+   - Jump to section 3 (Run Scan)
+5. **Section 3 — Run Scan:**
+   - Execute: `cd <project-path> && npx vibe-doc scan .`
+   - If fails: show error, suggest next steps, exit
+   - If succeeds: proceed
+6. **Section 4 — Present Classification:**
+   - Read `.vibe-doc/state.json` to get classification
+   - Show it to user in formatted output
+   - Checkpoint: ask user to confirm/revise/dispute
+7. **Section 5 — Present Gap Report:**
+   - Show summary (counts by tier)
+   - Checkpoint: ask how to proceed (walkthrough/generate/check/exit)
+8. **Section 6 — Interactive Walkthrough (optional):**
+   - If user picked walkthrough, go through gaps 1-by-1
+   - For each gap: show rationale, what was found, what's missing
+   - Ask: generate now, skip, or see details
+9. **Section 7 — Completion:**
+   - Show final summary
+   - Offer next steps (generate, save, check)
+
+---
+
+## Step-by-Step: Generate Skill
+
+User: "Help me generate the missing documentation"
+
+1. **Read** `skills/generate/SKILL.md`
+2. **Entry check:**
+   - Verify `.vibe-doc/state.json` exists
+   - If not: redirect to Scan skill and exit
+3. **Section 1 — Show Gaps:**
+   - Read state
+   - Display gaps organized by tier
+   - Ask: generate Required/pick specific/generate all
+4. **Section 2a — Sequential Generation:**
+   - For each selected gap:
+     - Consult `skills/guide/references/breadcrumb-heuristics.md` for the doc type
+     - Extract the "Gap Questions" section
+     - Ask user those 2-3 questions
+     - Save answers to temporary JSON
+     - Execute: `cd <project-path> && npx vibe-doc generate <docType> --format both --answers '<json>'`
+     - Parse output: show file paths, confidence per section
+     - Checkpoint: approve/revise/skip
+5. **Section 7 — Completion:**
+   - Show summary of what was generated
+   - Offer: generate more/check/done
+
+---
+
+## Step-by-Step: Check Skill
+
+User: "Check if my documentation is current"
+
+1. **Read** `skills/check/SKILL.md`
+2. **Section 1 — Run Check:**
+   - Execute: `cd <project-path> && npx vibe-doc check .`
+3. **Section 2 — Present Results:**
+   - If pass: celebrate, show status, offer next steps
+   - If fail: show what's missing/stale, suggest fixes
+4. **Section 3 — Checkpoint:**
+   - Ask: regenerate/scan/review/exit
+5. **CI Integration:**
+   - If user asks about CI/CD, show the example in section "CI/CD Integration"
+
+---
+
+## When to Consult Reference Guides
+
+### Use `classification-taxonomy.md` when:
+- Classifying an ambiguous application (could be Web App OR API)
+- Determining what docs are appropriate for a category
+- Explaining why a context modifier matters
+
+**Example:** User says "My app is both a web app and an API." Consult taxonomy to explain primary vs. secondary categories.
+
+### Use `documentation-matrix.md` when:
+- Explaining which docs are Required vs. Recommended for their app type
+- Showing why a doc tier changed (due to modifiers)
+- Justifying a doc as "required for HIPAA compliance"
+
+**Example:** Generate skill shows "Test Plan is Recommended for your Web App. However, because you're Customer-Facing, it's elevated to Required."
+
+### Use `breadcrumb-heuristics.md` when:
+- Generating a specific document (to get synthesis questions)
+- Explaining confidence levels (why a section was low-confidence)
+- Helping user understand what the scanner looks for
+
+**Example:** Generate skill for "Threat Model" doc → consult breadcrumb-heuristics to extract Gap Questions → ask user "Beyond authentication and data encryption, what other sensitive operations exist?"
+
+---
+
+## State Management
+
+All skills operate on `.vibe-doc/state.json` in the mounted project folder.
+
+**Never edit this file directly.** Always use CLI commands:
+
+```bash
+# Scan produces/updates:
+npx vibe-doc scan <path>
+
+# Generate updates:
+npx vibe-doc generate <docType> --format both --answers <json>
+
+# Check reads (no modifications):
+npx vibe-doc check <path>
+```
+
+**State structure** (from `guide/SKILL.md`):
+```json
+{
+  "profile": {
+    "primaryCategory": "string",
+    "secondaryCategories": ["string"],
+    "deploymentContexts": ["string"],
+    "confidence": 0.0-1.0
+  },
+  "scan": {
+    "timestamp": "ISO8601",
+    "artifacts": [],
+    "gitHistory": {},
+    "codeStructure": {}
+  },
+  "gaps": {
+    "required": [],
+    "recommended": [],
+    "optional": []
+  },
+  "generated": {
+    "docs": [],
+    "timestamps": {}
+  }
+}
+```
+
+---
+
+## Error Handling
+
+When a CLI command fails, **always:**
+
+1. Show the error message to the user
+2. Explain what was being attempted
+3. Suggest concrete next steps
+4. Offer fallback options (if any)
+
+See each SKILL.md's "Error Handling" section for specific error patterns and responses.
+
+---
+
+## Checkpoint Pattern (Critical)
+
+Vibe Doc uses checkpoints to ensure user control at critical gates:
+
+1. **Present findings clearly** (summary first, then details)
+2. **Show the decision** (what's being asked, why it matters)
+3. **Offer explicit choices** (yes/no/revise/skip/etc.)
+4. **Wait for confirmation** (do NOT proceed without user response)
+
+Examples of checkpoints:
+- Classification confirmation ("Does this match your project?")
+- Gap walkthrough start ("Would you like to walk through gaps one by one?")
+- Document approval ("Approve this doc before moving to next?")
+- Generation selection ("You've selected 2 docs. Ready to start?")
+
+---
+
+## Output Formatting Standards
+
+From `guide/SKILL.md`:
+
+**Headers:** Use Markdown. Structure output with H1, H2, H3.
+
+**Lists:** Bullet points for options/findings, numbered for steps.
+
+**Code blocks:**
+```bash
+cd /project && npx vibe-doc scan .
+```
+
+**Checkpoints:** Use clear formatting with options in brackets:
+```
+[yes] → Proceed to next step
+[no] → Go back and adjust
+```
+
+**Status indicators:** Use consistent symbols:
+- ✓ Complete/Found
+- ✗ Missing/Failed
+- ⚠ Warning/Low confidence
+- → Next step/redirect
+
+---
+
+## Example: Full Scan → Generate → Check Flow
+
+```
+User: "Help me document my project"
+
+Agent reads: skills/scan/SKILL.md
+Agent runs scan pipeline (sections 1-7)
+Output: gaps listed, user prompted next steps
+
+User: "Let's generate the required docs"
+
+Agent reads: skills/generate/SKILL.md
+Agent checks state, shows gaps, lets user pick
+For each gap:
+  - Agent reads: breadcrumb-heuristics.md (for that doc type)
+  - Agent asks synthesis questions
+  - Agent runs generate CLI
+  - Agent shows results + checkpoint
+
+User: "Before I commit these, can you verify everything?"
+
+Agent reads: skills/check/SKILL.md
+Agent runs check pipeline
+Output: pass/fail status, recommendations
+
+Done!
+```
+
+---
+
+## Tone & Style
+
+All skills follow 626Labs communication style:
+- **Direct and clear** — no filler, respect user's time
+- **Technical but accessible** — explain concepts in plain language
+- **Action-oriented** — lead with what to do, not why
+- **Responsive to energy** — match user's pace (quick/thoughtful)
+
+From `guide/SKILL.md`:
+- Professional, direct, no filler
+- Technical but accessible
+- Checkpoint before proceeding
+- Structured output (headers, lists, code blocks)
+
+---
+
+## Testing Your Implementation
+
+When integrating these skills, verify:
+
+1. **Scan skill:**
+   - Entry gate works (context vs. cold)
+   - Classification resolves correctly
+   - Gap report shows Required/Recommended/Optional
+   - Interactive walkthrough processes gaps one by one
+
+2. **Generate skill:**
+   - State check works (redirects if no scan)
+   - Synthesis questions asked and saved
+   - CLI commands execute and produce files
+   - Checkpoints work at each approval point
+
+3. **Check skill:**
+   - CLI returns correct exit codes (0/1)
+   - Output is CI-safe (no prompts)
+   - Suggestions for fixes are clear
+
+4. **Reference docs:**
+   - Agents can consult taxonomy for edge cases
+   - Matrix accurately maps categories to doc types
+   - Breadcrumbs provide useful synthesis questions
+
+---
+
+**Last updated:** 2026-04-11  
+**For:** Agents implementing Vibe Doc skills