@esthernandez/vibe-doc 0.2.1 → 0.2.3

package/skills/generate/SKILL.md

@@ -0,0 +1,391 @@
+---
+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.
+---
+
+# Vibe Doc Generate Skill
+
+Conversational pipeline to select documentation gaps and generate complete documents.
+
+**Shared behavior:** Read `skills/guide/SKILL.md` for state management, CLI patterns, checkpoints, and output formatting.
+
+---
+
+## Entry: Check for Existing Scan
+
+**First step: verify state exists**
+
+```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 user to **Scan skill** and exit.
+
+---
+
+## Conversational Flow
+
+### 1. Present Gap Summary & Offer Choices
+
+Read state and show gaps:
+
+```
+Documentation Gaps
+━━━━━━━━━━━━━━━━━━
+
+Required (Deployment Blockers) — 3 missing:
+  □ Threat Model
+  □ Architecture Decision Records
+  □ Runbook (Deployment & Operations)
+
+Recommended (Should Do) — 4 missing:
+  □ API Specification
+  □ Deployment Procedure
+  □ Data Model Documentation
+  □ Security Hardening Guide
+
+Optional (Nice to Have) — 3 missing:
+  □ Changelog
+  □ Contributing Guide
+  □ Performance Benchmarks
+
+Which would you like to generate?
+
+[required] → Start with all Required docs
+[pick] → Let me choose specific gaps
+[single <name>] → Generate one doc now
+[all] → Generate everything
+```
+
+**User chooses:**
+- `required` → Go to step 2a (Generate Required, one at a time)
+- `pick` → Go to step 2b (Selection menu)
+- `single Threat Model` → Go directly to step 3 for that doc
+- `all` → Go to step 2a with all gaps pre-selected
+
+---
+
+### 2a. Sequential Generation — One at a Time
+
+For each selected gap, execute the generation workflow:
+
+1. **Ask synthesis questions** (2-3 targeted questions for this doc type)
+2. **Capture answers** (save to temporary JSON)
+3. **Run generation command**
+4. **Present results** (file paths, confidence summary)
+5. **Confirm before moving to next doc**
+
+**For example, generating a Threat Model:**
+
+```
+Threat Model Synthesis
+━━━━━━━━━━━━━━━━━━━━━━
+
+I found security discussion in your artifacts, but I need 2 more details:
+
+1. Beyond authentication and data encryption, are there other sensitive 
+   operations? (payments, PII access, admin functions, integrations?)
+
+2. Are there known external dependencies or services your app relies on?
+   (Third-party APIs, databases, cache layers?)
+
+[Capture answers and save to temp JSON]
+
+Generating threat model...
+```
+
+Then run:
+
+```bash
+cd <project-path> && npx vibe-doc generate threat-model \
+  --format both \
+  --answers '{"externalDeps":["Firebase","Stripe"],"sensitiveOps":["payment","admin"]}'
+```
+
+**If generation succeeds:**
+
+```
+✓ Threat Model generated
+
+Files created:
+  • docs/generated/threat-model.md (2,400 words)
+  • docs/generated/threat-model.docx
+
+Confidence summary:
+  • Attack surface (High) — extracted from code + interview
+  • Threat scenarios (Medium) — based on patterns, flagged for review
+  • Mitigations (Medium) — industry standard, review for your stack
+  • Compliance mapping (High) — HIPAA requirements auto-linked
+
+Next: Review the markdown file, then approve or regenerate.
+
+[approve] → Save and move to next doc
+[revise] → Ask different questions and regenerate
+[skip] → Move to next gap without saving
+```
+
+**If user approves:**
+- Move to next selected doc (repeat step 2a)
+
+**If user revises:**
+- Ask follow-up questions
+- Re-run generation with new answers
+
+**If user skips:**
+- Mark gap as deferred
+- Move to next doc
+
+---
+
+### 2b. Selection Menu (If User Picks)
+
+Show all gaps as a checklist:
+
+```
+Which docs would you like to generate? (Mark with [x])
+
+Required:
+  [x] Threat Model
+  [ ] Architecture Decision Records
+  [ ] Runbook
+
+Recommended:
+  [x] API Specification
+  [ ] Deployment Procedure
+  [ ] Data Model Documentation
+
+Optional:
+  [ ] Changelog
+  [ ] Contributing Guide
+
+[done] → Generate the 2 checked docs
+[add all required] → Select all Required docs
+[clear] → Start over
+```
+
+After selection, confirm:
+
+```
+You've selected 2 docs to generate. Estimate time: 10-15 minutes.
+
+Ready to start?
+[yes] → Begin generation
+[no] → Go back and adjust
+```
+
+Then proceed to step 2a (Sequential Generation).
+
+---
+
+### 3. Synthesis Questions — Doc Type Specifics
+
+For each document type, ask targeted questions to fill extraction gaps.
+
+**Use breadcrumb heuristics from `skills/guide/references/breadcrumb-heuristics.md`.**
+
+**Example questions per doc type:**
+
+| Doc Type | Sample Questions |
+|----------|------------------|
+| **Threat Model** | What sensitive operations exist? Known external dependencies? Attack vectors you're concerned about? |
+| **ADRs** | Major architecture decisions made? Tradeoffs considered (monolith vs. microservices)? Tech stack choices? |
+| **Runbook** | Deployment frequency? Health checks and alerts? Rollback procedure? On-call escalation? |
+| **API Spec** | Authentication method? Rate limiting? Pagination? Error codes? Versioning strategy? |
+| **Deployment Procedure** | CI/CD pipeline stages? Approval gates? Rollback trigger? Monitoring post-deploy? |
+| **Test Plan** | Coverage targets? Manual vs. automated split? Test environments? Performance benchmarks? |
+| **Data Model** | Data retention requirements? PII classification? Schema versioning? Backup/restore? |
+
+**Question delivery format:**
+
+```
+Threat Model — Question 1 of 2
+
+[Question text]
+
+Your answer: [capture user input]
+```
+
+---
+
+### 4. Generation Command
+
+After collecting answers, save to JSON and run CLI:
+
+```bash
+ANSWERS_JSON='{"externalDeps":["..."],"sensitiveOps":["..."]}'
+cd <project-path> && npx vibe-doc generate threat-model \
+  --format both \
+  --answers "$ANSWERS_JSON"
+```
+
+**Parse output:**
+- Extract file paths (e.g., `docs/generated/threat-model.md`)
+- Extract confidence scores per section
+- Extract source attributions
+
+---
+
+### 5. Present Results
+
+Show what was created:
+
+```
+✓ Threat Model generated
+
+Files:
+  markdown:  docs/generated/threat-model.md (2,400 words)
+  docx:      docs/generated/threat-model.docx
+
+Content breakdown:
+  • Executive summary
+  • Attack surface inventory (extracted from code + your input)
+  • Threat scenarios (attack trees, entry points)
+  • Mitigations and controls
+  • Compliance checklist (HIPAA §164.308 mapping)
+
+Confidence by section:
+  ✓ Attack surface (94%) — High confidence
+  ⚠ Mitigations (72%) — Medium, please review
+  ✓ Compliance (88%) — High confidence
+
+Source attributions included in document.
+
+Next step: Review the markdown, then either:
+[approve] → Mark as complete and generate more docs
+[revise] → Ask different questions and regenerate
+[skip] → Move to next gap
+```
+
+---
+
+### 6. Document Review Checkpoint
+
+Ask user to review before moving on:
+
+```
+Before we move to the next doc, take a moment to review what was generated.
+
+Open: docs/generated/threat-model.md
+
+Things to check:
+  • Does the attack surface match your app?
+  • Are mitigations practical for your stack?
+  • Any confidence flags (marked ⚠) that need manual review?
+
+[approve] → Document is good, move to next gap
+[revise] → I'll ask different questions and regenerate
+[edit] → I'll open the markdown so you can edit manually
+[skip] → Skip this doc for now, move to next
+```
+
+---
+
+### 7. Completion Summary
+
+After all selected docs are generated:
+
+```
+Generation Complete ✓
+━━━━━━━━━━━━━━━━━━━━
+
+Generated: 3 documents
+  ✓ Threat Model
+  ✓ API Specification
+  ✓ Runbook
+
+Files saved to: docs/generated/
+
+Coverage improved: 28% → 57% (4 of 7 Required docs)
+
+What's next?
+
+[more] → Generate more docs
+[check] → Run CI validation
+[done] → Finish (docs are ready to review)
+```
+
+---
+
+## Error Handling
+
+### No Scan Exists
+
+```
+I don't see a project profile yet. Run the Scan skill first to:
+  • Analyze your artifacts
+  • Classify your app type
+  • Identify documentation gaps
+
+Then come back here to generate docs.
+```
+
+### Generation Command Fails
+
+```
+Generation failed: [error message]
+
+This could mean:
+  • The answers you provided didn't match expected format
+  • The doc template is missing or corrupted
+  • A file system error occurred
+
+Options:
+[retry] → Try again with same questions
+[different] → Ask different synthesis questions
+[manual] → Skip this doc and move to next
+```
+
+### Low Confidence Sections
+
+If a section has <70% confidence:
+
+```
+⚠ Low Confidence Flag: "Mitigations" section (68% confidence)
+
+This section was generated from limited artifact information and may need 
+manual review or revision. I've marked it with flags in the document.
+
+Suggestions:
+  • Review "Mitigations" manually and adjust
+  • Re-generate with more specific answers to synthesis questions
+  • Leave as-is (it's a starting point, not final)
+
+[revise] → Ask different questions and regenerate
+[continue] → Keep this version, move to next doc
+```
+
+---
+
+## State & Output
+
+**Read from `.vibe-doc/state.json`:**
+- Classification (to select appropriate doc types)
+- Gaps list (to show what's available to generate)
+- Generation history (to track what's been done)
+
+**Write to `.vibe-doc/state.json`:**
+- Generated doc metadata (file paths, timestamps, confidence scores)
+
+**Files created in user's project:**
+- `docs/generated/<doc-type>.md` — markdown version
+- `docs/generated/<doc-type>.docx` — docx version
+- `docs/generated/.history/<doc-type>-<timestamp>.md` — version history
+
+---
+
+## Synthesis Questions Reference
+
+Full question sets per doc type are in `skills/guide/references/breadcrumb-heuristics.md`.
+
+Each skill consults that reference to build context-appropriate questions for each gap type.
+
+---
+
+**Last updated:** 2026-04-11 | **Version:** 1.0

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