feat: gstack integration + repo health audit

.claude/skills/document-release/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: document-release
+description: |
+  Post-ship documentation sync for intent-blueprint-docs. After code changes, automatically
+  updates CLAUDE.md, README, CHANGELOG, and all project docs to match what shipped. Flags
+  stale documentation and applies factual corrections.
+  Use when documentation is out of date after a release, or after running /ship.
+  Trigger with "/document-release" or "update docs after release".
+  Make sure to use this skill whenever documentation needs to be synced after code changes.
+allowed-tools: "Read,Write,Edit,Glob,Grep,Bash(git:*),Bash(gh:*)"
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: Apache-2.0
+compatible-with: claude-code
+tags: [documentation, release, sync, changelog]
+model: inherit
+---
+
+# Document Release
+
+<!-- Portions adapted from gstack (https://github.com/garrytan/gstack) -->
+<!-- Original: MIT License, Copyright (c) Garry Tan -->
+
+Post-ship documentation update workflow. Reads all project docs, cross-references the diff,
+updates docs to match what shipped, and polishes CHANGELOG voice.
+
+## Overview
+
+After `/ship` commits code and creates a PR, documentation often lags behind. This skill
+audits every documentation file in the project, cross-references it against the diff, and
+applies factual corrections automatically. Risky or subjective changes are flagged for
+human review. Adapted from gstack's document-release workflow.
+
+## Prerequisites
+
+- On a feature branch with commits (typically run after `/ship`)
+- `gh` CLI authenticated (for PR body updates)
+
+## Instructions
+
+### Step 0: Detect Base Branch
+
+1. `gh pr view --json baseRefName -q .baseRefName`
+2. `gh repo view --json defaultBranchRef -q .defaultBranchRef.name`
+3. Fallback: `main`
+
+### Step 1: Pre-flight & Diff Analysis
+
+1. Verify on a feature branch (abort if on main/master)
+2. Gather context:
+   ```bash
+   git diff <base>...HEAD --stat
+   git log <base>..HEAD --oneline
+   git diff <base>...HEAD --name-only
+   ```
+3. Discover all documentation files:
+   - `*.md` files in root and first two directory levels
+   - Exclude: `.git/`, `node_modules/`, `completed-docs/`, `99-Archive/`
+4. Classify changes: new features, changed behavior, removed functionality, infrastructure
+
+### Step 2: Per-File Documentation Audit
+
+Read each documentation file and cross-reference against the diff:
+
+**README.md:**
+- Features and capabilities match the diff?
+- Install/setup instructions still valid?
+- Examples and demos accurate?
+
+**CLAUDE.md:**
+- Project structure section matches actual file tree?
+- Listed commands and scripts accurate?
+- Build/test instructions match package.json?
+
+**CHANGELOG.md:**
+- Latest entry covers all changes on this branch?
+- Voice is user-forward, not commit-message style?
+
+**000-docs/ files:**
+- Cross-reference against diff for stale content
+- Check file paths and version references
+
+**Any other .md files:**
+- Read, determine purpose, check against diff
+
+Classify updates as:
+- **Auto-update** — Factual corrections clearly from the diff
+- **Ask user** — Narrative changes, section removal, large rewrites
+
+### Step 3: Apply Auto-Updates
+
+Make factual corrections using Edit tool. For each change, output a one-line summary:
+"README.md: updated template count from 20 to 22"
+
+**Never auto-update:** README introduction, project positioning, security model descriptions.
+
+### Step 4: Ask About Risky Changes
+
+For each risky update, ask user with options including "Skip — leave as-is."
+
+### Step 5: CHANGELOG Voice Polish
+
+**CRITICAL — NEVER CLOBBER CHANGELOG ENTRIES.**
+
+Only polish wording within existing entries. Never delete, reorder, or replace.
+- "You can now..." not "Refactored the..."
+- Lead with what the user can do, not implementation details
+- Use Edit tool with exact old_string matches — never Write to overwrite
+
+### Step 6: Cross-Doc Consistency Check
+
+1. README feature list matches CLAUDE.md description?
+2. CHANGELOG version matches VERSION file?
+3. Every doc file reachable from README or CLAUDE.md?
+4. Auto-fix factual inconsistencies, ask about narrative contradictions
+
+### Step 7: Commit & Output
+
+If no files were modified: "All documentation is up to date."
+
+Otherwise:
+1. Stage modified docs by name (never `git add -A`)
+2. Commit: `docs: update project documentation for vX.Y.Z`
+3. Push to current branch
+4. Update PR body with documentation section (if PR exists)
+
+## Output
+
+```
+Documentation health:
+  README.md        [Updated] (added new skill to feature list)
+  CLAUDE.md        [Current] (no changes needed)
+  CHANGELOG.md     [Voice polished] (3 entries reworded)
+  CONTRIBUTING.md  [Updated] (fixed build command)
+  000-docs/        [Current] (all 10 docs consistent)
+  VERSION          [Already bumped] (v2.1.0 by /ship)
+```
+
+## Examples
+
+### After a Feature Release
+
+**Input:**
+```
+/document-release
+```
+
+**Output:**
+```
+Analyzing 8 files changed across 5 commits. Found 15 documentation files to review.
+
+Documentation health:
+  README.md        [Updated] (added /review-docs to skills table, updated count 4->5)
+  CLAUDE.md        [Updated] (added .claude/skills/ to project structure)
+  CHANGELOG.md     [Voice polished] (2 entries reworded for user-forward voice)
+  CONTRIBUTING.md  [Current] (no changes needed)
+
+Committed: docs: update project documentation for v2.1.0
+Pushed to: feat/gstack-integration
+PR body updated with Documentation section.
+```
+
+## Edge Cases
+
+- If on main branch, abort
+- If no PR exists, skip PR body update
+- If CHANGELOG was not modified on this branch, skip voice polish
+- If VERSION doesn't exist, skip version checks
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| On main branch | Wrong branch | Abort with message |
+| No changes to commit | Docs already current | Output "up to date" message |
+| PR body update fails | No PR or auth issue | Warn and continue (changes are in commit) |
+| CHANGELOG clobbered | Write tool used instead of Edit | Restore from git and re-apply with Edit |

.claude/skills/document-release/evals/evals.json

@@ -0,0 +1,5 @@
+[
+  {"name": "post_ship_sync", "prompt": "Update docs after shipping v2.1.0", "assertions": ["Audits all markdown files", "Applies factual corrections", "Polishes changelog voice"]},
+  {"name": "nothing_to_update", "prompt": "Sync docs when nothing changed", "assertions": ["Reports all documentation up to date"]},
+  {"name": "negative_test", "prompt": "Create a new architecture document", "assertions": ["Skill does not activate for document creation"]}
+]

.claude/skills/qa-docs/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: qa-docs
+description: |
+  Systematically audit generated documentation quality with a structured health score.
+  Produces a report-only quality assessment — identifies issues but does not fix them.
+  Scores Completeness, Consistency, Accuracy, Audience-Fit, and Actionability.
+  Use when auditing doc quality, running a QA pass on generated docs, or checking doc health.
+  Trigger with "/qa-docs" or "audit doc quality".
+  Make sure to use this skill whenever performing quality assurance on documentation output.
+allowed-tools: "Read,Glob,Grep"
+version: 1.0.0
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: Apache-2.0
+compatible-with: claude-code
+tags: [qa, documentation, audit, quality]
+model: inherit
+---
+
+# QA Docs
+
+<!-- Portions adapted from gstack (https://github.com/garrytan/gstack) -->
+<!-- Original: MIT License, Copyright (c) Garry Tan -->
+
+Report-only documentation quality audit. Identifies issues systematically without fixing them.
+Produces a structured health score across 5 dimensions.
+
+## Overview
+
+Unlike `/review-docs` which auto-fixes issues, `/qa-docs` is a pure audit — it scores
+documentation quality and produces a report without making any changes. This is useful for
+CI quality gates, pre-release audits, and tracking doc quality over time. Adapted from
+gstack's qa-only workflow which emphasizes evidence-based assessment over intervention.
+
+## Prerequisites
+
+- Generated documentation in `completed-docs/<project>/` or equivalent
+- Templates in `professional-templates/core/` for structure comparison
+
+## Instructions
+
+### Step 1: Determine Audit Scope
+
+Detect mode from user input:
+- **Full** (default) — Audit every document in the suite
+- **Quick** — Score only the 5 health dimensions without per-document detail
+- **Diff-aware** — Focus on documents affected by recent changes
+
+### Step 2: Inventory Documents
+
+List all `.md` files in the target directory. For each file, record:
+- Filename and path
+- Word count
+- Section count (H2 headers)
+- Placeholder status (any unresolved `{{...}}` tokens)
+
+### Step 3: Score Each Dimension
+
+Rate each dimension 1-10 with evidence:
+
+**Completeness (weight: 30%)**
+- All expected sections present vs template?
+- No empty "TBD" / "TODO" placeholders?
+- Required metadata populated?
+- Cross-references resolve?
+
+**Consistency (weight: 25%)**
+- Terminology uniform across all docs?
+- Project name spelled identically everywhere?
+- Version numbers aligned?
+- Scope tier reflected consistently?
+
+**Accuracy (weight: 20%)**
+- Technical claims verifiable against codebase?
+- File paths exist?
+- Commands are runnable?
+- API references correct?
+
+**Audience-Fit (weight: 15%)**
+- Language complexity matches declared audience?
+- Jargon appropriate for tier (startup vs enterprise)?
+- Assumptions explicit?
+
+**Actionability (weight: 10%)**
+- Clear "what to do next" guidance?
+- Decisions framed as choices with trade-offs?
+- Risk mitigations included, not just descriptions?
+- Task breakdowns estimable and assignable?
+
+### Step 4: Generate Health Report
+
+Calculate weighted health score. Classify each finding with severity.
+
+## Output
+
+```
+Documentation Quality Audit
+====================================
+Project: <name>
+Scope: <MVP|Standard|Comprehensive>
+Documents: N files, N total words
+
+Health Score: XX/100
+
+Dimension Scores:
+  Completeness:   XX/10 (30%) — [evidence summary]
+  Consistency:    XX/10 (25%) — [evidence summary]
+  Accuracy:       XX/10 (20%) — [evidence summary]
+  Audience-Fit:   XX/10 (15%) — [evidence summary]
+  Actionability:  XX/10 (10%) — [evidence summary]
+
+Findings (N total):
+
+  CRITICAL (N):
+  - [doc:section] Finding with evidence
+
+  WARNING (N):
+  - [doc:section] Finding with evidence
+
+  INFO (N):
+  - [doc:section] Finding with evidence
+
+Per-Document Summary:
+  01_prd.md           __________ 9/10
+  02_adr.md           ________   8/10
+  06_architecture.md  ______     6/10  <- needs attention
+
+Recommendation: [Ship-ready | Needs rework | Regenerate]
+====================================
+```
+
+## Examples
+
+### Full Audit
+
+**Input:**
+```
+/qa-docs completed-docs/my-saas/
+```
+
+**Output:**
+```
+Documentation Quality Audit
+====================================
+Project: my-saas
+Scope: Standard (12 docs)
+Documents: 12 files, 45,230 total words
+
+Health Score: 82/100
+
+Dimension Scores:
+  Completeness:   9/10 (30%) — All sections present, 1 empty placeholder in 05_market_research.md
+  Consistency:    8/10 (25%) — "API" vs "api" inconsistency in 3 docs
+  Accuracy:       7/10 (20%) — 2 file paths reference nonexistent directories
+  Audience-Fit:   9/10 (15%) — Language appropriate for startup audience
+  Actionability:  8/10 (10%) — 3 risk items missing mitigation strategies
+
+Recommendation: Ship-ready with minor fixes
+====================================
+```
+
+## Edge Cases
+
+- If target directory is empty, report "No documents found" and suggest running /new-project
+- If templates directory is unavailable, skip structure comparison
+- For single-file audit, score all 5 dimensions on that one file
+- Handle both flat and nested directory structures
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| No docs found | Wrong path | Ask user to confirm directory |
+| Template mismatch | Custom templates used | Note in report, skip structure comparison |
+| Unreadable file | Permission or encoding issue | Skip file, note in report |

.claude/skills/qa-docs/evals/evals.json

@@ -0,0 +1,5 @@
+[
+  {"name": "full_audit", "prompt": "Audit the docs in completed-docs/test-project/", "assertions": ["Scores all 5 dimensions", "Produces health score out of 100", "Lists findings by severity"]},
+  {"name": "quick_mode", "prompt": "Quick quality check on completed-docs/test-project/", "assertions": ["Produces scores without per-document detail"]},
+  {"name": "negative_test", "prompt": "Fix the broken tests in src/", "assertions": ["Skill does not activate for code tasks"]}
+]