zhongwei/gh-kimcharli-ck-skills-plugins-doc-review-commands
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:31:57 +08:00
commit aebfdd53e0
10 changed files with 2177 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,11 @@
{
"name": "doc-review-commands",
"description": "AI-powered documentation management system for Claude Code - keeps project documentation in sync with code changes",
"version": "1.0.0",
"author": {
"name": "kimcharli"
},
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# doc-review-commands
AI-powered documentation management system for Claude Code - keeps project documentation in sync with code changes

124
commands/analyze.md Normal file
View File

@@ -0,0 +1,124 @@
---
description: Run documentation analysis without making changes
allowed-tools: Bash(~/.claude/commands/ck/doc-review/tools/analyzer.sh:*), Bash(~/.claude/tools/doc-analyzer.sh:*)
---
# Documentation Analysis Command
## Context
- Analysis Results:
!`~/.claude/commands/ck/doc-review/tools/analyzer.sh all || ~/.claude/tools/doc-analyzer.sh all`
## Task
**Analysis-only mode** - Review project documentation without making changes.
---
## Analysis Summary
Present the analysis results in a user-friendly format:
### 📋 Project Documentation Principles
[Summarize principles detected from analysis output above]
**Detected Constraints:**
- [List any detected principles or "None detected"]
**Impact:** [Explain what this means for documentation updates]
---
### 📁 Documentation Structure
**Inventory:**
- Total .md files: [from metrics]
- Root directory: [count]
- docs/ directory: [count]
- specs/ directory: [count]
**Organization Assessment:**
- [Summarize if current structure is good or needs reorganization]
- [List any potential improvements]
---
### 🎯 Change Impact Assessment
**Recent Changes:**
[List files changed from git analysis]
**Documentation Impact:**
- README.md: [Needs update? Why?]
- CLAUDE.md: [Needs update? Why?]
- SDD artifacts: [Needs update? Why?]
- API/Technical docs: [Needs update? Why?]
**Recommended Actions:**
1. [Prioritized list of documentation updates needed]
2. [...]
---
### 📊 Current Metrics
**Documentation Health:**
- Total documentation lines: [from metrics]
- Last commit: [from git]
- Last doc update: [from git]
**Quality Indicators:**
- Large files (>200 lines): [count and list]
- Potential misplaced files: [count and list]
- SDD coverage: [number of active specs]
---
## Recommendations
Based on this analysis, here's what you should do:
### High Priority
- [List high-priority updates]
### Medium Priority
- [List medium-priority updates]
### Low Priority / Optional
- [List optional improvements]
---
## Next Steps
**To update documentation, use:**
- `/ck:doc-review/core [feature]` - Update core files
- `/ck:doc-review/sdd [feature]` - Update SDD artifacts
- `/ck:doc-review/main [feature]` - Full update with user choice
**To validate quality:**
- `/ck:doc-review/qa` - Run quality checks
---
## Benefits
✅ **No Changes Made** - Safe to run anytime
✅ **Fast** - Completes in < 1 second
✅ **Comprehensive** - Full picture of doc health
✅ **Actionable** - Clear next steps

210
commands/core.md Normal file
View File

@@ -0,0 +1,210 @@
---
description: Update core documentation files (README, CLAUDE, CHANGELOG)
allowed-tools: Bash(cat:*), Bash(git:*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
---
# Core Documentation Update Command
## Context
- Config:
!`cat ~/.claude/commands/ck/doc-review/config/categories.json`
- Recent changes:
!`git diff --name-only HEAD~5..HEAD 2>/dev/null || echo "No recent commits"`
## Task
**Update core documentation for:** $ARGUMENTS
**Files to update:**
- README.md
- CLAUDE.md
- CHANGELOG.md
---
## Step 1: Read Current Files
Read the current state of core files to understand what needs updating.
---
## Step 2: README.md Updates
### What to Update
Based on $ARGUMENTS, update relevant sections:
**Features Section:**
If new feature added, use this template:
````markdown
### [Feature Name]
Brief description of what it does and why it's useful.
**Usage:**
```[language]
# Code example here
```
````
**Key Features:**
- Feature point 1
- Feature point 2
````
**Installation Section:**
- Update if new dependencies added
- Update if setup process changed
- Verify all steps still work
**Configuration Section:**
- Add new configuration options
- Update examples with new settings
- Note any breaking changes
**Troubleshooting:**
- Add common issues encountered during development
- Document solutions/workarounds
### Make Updates
Apply updates to README.md using Edit tool.
---
## Step 3: CLAUDE.md Updates
### What to Update
Add AI assistant context for: $ARGUMENTS
**Use this template:**
````markdown
### [Module/Feature Name]
- **Purpose**: [What it does in one sentence]
- **Location**: `path/to/file.py:123`
- **Key Components**:
- `ClassName` - Description
- `function_name()` - Description
- **Usage Pattern**:
```bash
# Example usage
```
````
- **Error Handling**:
- Common error 1: Solution
- Common error 2: Solution
- **Related Components**: [Links to related sections]
````
**Additional Context:**
- Update architecture overview if structure changed
- Add new workflow patterns
- Document design decisions
- Add debugging tips
### Make Updates
Apply updates to CLAUDE.md using Edit tool.
---
## Step 4: CHANGELOG.md Updates
### Determine Version
Check current version and determine if this is:
- Patch (bug fix): increment 0.0.X
- Minor (new feature): increment 0.X.0
- Major (breaking change): increment X.0.0
### Use Template
````markdown
## [Version] - YYYY-MM-DD
### Added
- Feature: [description] (file.py:123)
- Feature: [description]
### Changed
- Modified: [description]
- Updated: [description]
### Fixed
- Bug: [description] (#issue)
- Issue: [description]
### Deprecated
- [What's being removed in future]
````
### Make Updates
- Read current CHANGELOG.md
- Add new entry at the top (most recent first)
- Use Edit tool to update
---
## Step 5: Validation
**Check Updates:**
- [ ] README.md updated with new feature/changes
- [ ] CLAUDE.md has AI context for new components
- [ ] CHANGELOG.md has version entry with categorized changes
- [ ] All code examples are syntactically correct
- [ ] File:line references are accurate
- [ ] No sensitive information exposed
---
## Output: Summary
### 📊 Core Documentation Update Summary
**Scope:** $ARGUMENTS
**Files Updated:**
| File | Sections Modified | Lines Changed |
| ------------ | ----------------- | ------------- |
| README.md | [list sections] | ~[estimate] |
| CLAUDE.md | [list sections] | ~[estimate] |
| CHANGELOG.md | [version entry] | ~[estimate] |
**Key Changes:**
- [Bullet point summary of main changes]
**Validation:**
- [x] All core files updated
- [x] Examples tested
- [x] No sensitive data
- [x] References accurate
**Execution Time:** [X]s
---
## Next Steps
Recommended follow-up:
- [ ] Review changes: `git diff README.md CLAUDE.md CHANGELOG.md`
- [ ] Test any code examples added
- [ ] Update SDD if needed: `/ck:doc-review/sdd $ARGUMENTS`
- [ ] Run QA: `/ck:doc-review/qa`

667
commands/help.md Normal file
View File

@@ -0,0 +1,667 @@
---
description: Documentation review system help - usage guide and command reference
allowed-tools: Bash(cat:*)
---
# 📚 Documentation Review System - Help Guide
**Version:** Phase 3 (Modular Architecture)
**Last Updated:** 2025-10-24
---
## 🎯 What Is This?
The `/ck:doc-review` system is a **modular documentation update toolkit** that
helps you:
✅ Keep documentation in sync with code changes
✅ Update README, CLAUDE.md, CHANGELOG consistently
✅ Maintain SDD (Specification-Driven Development) artifacts
✅ Validate documentation quality before commits
✅ Save 88% tokens compared to manual updates
---
## 🏗️ Architecture Overview
```text
┌─────────────────────────────────────────┐
│ /ck:doc-review (Orchestrator) │
│ • Analyzes changes │
│ • Asks what to update │
│ • Delegates to sub-commands │
│ • Shows summary │
└─────────────────────────────────────────┘
│
┌──────┼──────┬──────┬──────┐
▼ ▼ ▼ ▼ ▼
┌────────┐ │ │ │ │ │ │ └─────────┐
│:analyze│ │:core│ │:sdd│ │:qa│ │:help │
│ │ │ │ │ │ │ │ │ │
│ 0 edits│ │3 files││SDD │ │Check││This!│
└────────┘ └─────┘ └────┘ └────┘ └──────┘
```
---
## 📋 Command Reference
### `/ck:doc-review/help` (This Command)
**Purpose:** Show help and usage guide
**Token Cost:** ~200 tokens (one-time)
**Files Modified:** None
**Use When:** First time using system, or need reminder
---
### `/ck:doc-review/analyze`
**Purpose:** Analyze documentation needs without making changes
**Token Cost:** ~600-800 tokens
**Files Modified:** None
**Execution Time:** < 1 second
**What It Does:**
- ✅ Detects project documentation principles
- ✅ Analyzes current documentation structure
- ✅ Identifies what needs updating (from git history)
- ✅ Provides actionable recommendations
- ❌ Makes zero changes
**When to Use:**
- "What docs need updating?"
- Before starting documentation work
- Quick health check
- Understanding project doc structure
**Example:**
```bash
/ck:doc-review/analyze
→ Output:
- 61 .md files found
- Recent changes: 5 files in src/
- Recommendations: Update README, CLAUDE, specs/005/
- Execution: 0.8s
```
---
### `/ck:doc-review/core`
**Purpose:** Update core documentation files
**Token Cost:** ~1,200-1,500 tokens
**Files Modified:** README.md, CLAUDE.md, CHANGELOG.md
**Execution Time:** 15-30 seconds
**What It Does:**
- ✅ Updates README.md (features, usage, installation)
- ✅ Updates CLAUDE.md (AI context, module docs)
- ✅ Updates CHANGELOG.md (version entry)
- ✅ Uses professional templates
- ✅ Validates changes
**When to Use:**
- Just added a new feature
- Need to document new API/module
- Quick documentation update
- Before sharing project
**Example:**
```bash
/ck:doc-review/core "ApstraWorkModule implementation"
→ Updates:
- README.md: Added usage examples
- CLAUDE.md: Added module context
- CHANGELOG.md: Created v1.2.0 entry
- Time: 18s
```
**Templates Provided:**
- README feature section
- CLAUDE module documentation
- CHANGELOG version entry
---
### `/ck:doc-review/sdd`
**Purpose:** Update SDD (Specification-Driven Development) artifacts
**Token Cost:** ~1,500-1,800 tokens
**Files Modified:** specs/_/spec.md, plan.md, tasks.md, contracts/_.md
**Execution Time:** 30-60 seconds
**What It Does:**
- ✅ Marks requirements (FR-\*) as completed in spec.md
- ✅ Updates implementation plan and phase status in plan.md
- ✅ Marks tasks complete and adds notes in tasks.md
- ✅ Updates design contracts and API specs
- ✅ Validates SDD ↔ code consistency
**When to Use:**
- Completed an implementation phase
- Need to sync specs with code
- Mark requirements as done
- Document architecture decisions
**Example:**
```bash
/ck:doc-review/sdd "Phase 2 completion"
→ Updates:
- spec.md: Marked FR-005-1, FR-005-2 complete
- plan.md: Phase 2 status = ✅ Completed
- tasks.md: 15 tasks marked done
- Consistency: 100%
- Time: 42s
```
**SDD Consistency Checks:**
- Requirements → Implementation alignment
- Plan → Tasks alignment
- Contracts → Code alignment
- Traceability validation
---
### `/ck:doc-review/qa`
**Purpose:** Quality assurance - validate documentation
**Token Cost:** ~1,800-2,000 tokens
**Files Modified:** None
**Execution Time:** 10-20 seconds
**What It Does:**
- ✅ Validates markdown links (finds broken links)
- ✅ Checks file:line references (path/to/file.py:123)
- ✅ Checks terminology consistency
- ✅ Validates version number consistency
- ✅ Checks SDD requirement traceability
- ✅ Basic code example syntax validation
- ✅ Completeness check (required sections)
- ✅ Generates scored report (0-100)
**When to Use:**
- Before committing documentation changes
- After major documentation updates
- Find and fix broken links
- Ensure documentation quality
**Example:**
```bash
/ck:doc-review/qa
→ Results:
- Valid links: 156
- Broken links: 3
- Version mismatches: 1
- Overall score: 87/100
- Time: 12s
→ Recommendations:
1. Fix broken link in README.md:45
2. Update version in pyproject.toml
```
**QA Categories:**
1. Link Validation (20 points)
2. Cross-Reference Validation (15 points)
3. Terminology Consistency (15 points)
4. Version Consistency (15 points)
5. SDD Consistency (15 points)
6. Code Example Quality (10 points)
7. Completeness (10 points)
---
### `/ck:doc-review` (Main Orchestrator)
**Purpose:** Smart orchestration - analyze and delegate
**Token Cost:** ~900-1,200 tokens (orchestrator only) + selected sub-commands
**Files Modified:** Depends on user selection
**Execution Time:** Variable (depends on selection)
**What It Does:**
- ✅ Runs comprehensive analysis (via doc-analyzer.sh)
- ✅ Shows analysis summary
- ✅ Asks user which areas to update
- ✅ Invokes selected sub-commands automatically
- ✅ Aggregates and shows summary
**When to Use:**
- Not sure what needs updating
- Want guided workflow
- Comprehensive documentation update
- First time using the system
**Example:**
```bash
/ck:doc-review "feature 005 implementation"
→ Analysis shown (principles, structure, changes, metrics)
→ User asked:
Which areas to update?
□ Core Files (README, CLAUDE, CHANGELOG)
□ SDD Artifacts (spec, plan, tasks)
□ Run QA Only
□ Full Update
→ User selects "Full Update"
→ Executes:
1. /ck:doc-review/core "feature 005"
2. /ck:doc-review/sdd "feature 005"
3. /ck:doc-review/qa
→ Aggregated summary:
- 8 files updated
- QA score: 92/100
- Total time: 78s
```
---
## 🎓 Usage Patterns
### Pattern 1: Quick README Update (Most Common)
```bash
# Scenario: Added new feature, need docs
/ck:doc-review/core "new feature name"
# Time: 20s
# Token: 1.2K
# Updates: README, CLAUDE, CHANGELOG
```
### Pattern 2: Analysis First (Recommended for New Users)
```bash
# Step 1: Understand what needs updating
/ck:doc-review/analyze
# Step 2: Update based on recommendations
/ck:doc-review/core "feature X"
# Time: 1s + 20s = 21s
# Tokens: 600 + 1.2K = 1.8K
```
### Pattern 3: Full Update After Major Work
```bash
# Completed major implementation
/ck:doc-review "Phase 2 complete"
→ Select "Full Update"
→ All docs updated + QA validated
# Time: 60-90s
# Tokens: 3-4K
# Updates: Everything
```
### Pattern 4: QA Before Commit (Best Practice)
```bash
# Before git commit
/ck:doc-review/qa
→ Fix any issues found
→ Re-run QA
→ Commit with confidence
# Time: 10-15s per run
# Tokens: 1.8K
```
### Pattern 5: SDD Update After Phase
```bash
# Completed implementation phase
/ck:doc-review/sdd "Phase 2"
# Time: 40-50s
# Tokens: 1.5K
# Updates: All SDD artifacts
```
---
## 🗂️ File Structure Reference
### Command Files Location
```text
~/.claude/commands/ck/
├── doc-review.md # Main orchestrator
├── doc-review:analyze.md # Analysis only
├── doc-review:core.md # Core files update
├── doc-review:sdd.md # SDD artifacts update
├── doc-review:qa.md # Quality validation
├── doc-review:help.md # This help file
└── doc-categories.json # Pattern configuration
```
### Supporting Tools
```text
~/.claude/tools/
└── doc-analyzer.sh # External analysis script
├── principles # Extract doc principles
├── structure # Analyze doc structure
├── categorize # Categorize files
├── impact # Assess change impact
├── metrics # Generate metrics
└── all # Run all analyses
```
### Documentation
```text
docs/
├── ck-doc-review-analysis.md # Architecture analysis
├── ck-doc-review-phase1-improvements.md # Phase 1 docs
├── ck-doc-review-phase2-improvements.md # Phase 2 docs
└── ck-doc-review-phase3-improvements.md # Phase 3 docs (current)
```
---
## 📊 Token Budgeting
### Per-Command Token Costs
| Command | Tokens | Use Case |
| ------------ | ------------------------ | ------------------ |
| `:help` | ~200 | One-time reference |
| `:analyze` | ~600-800 | Analysis only |
| `:core` | ~1.2-1.5K | Quick update |
| `:sdd` | ~1.5-1.8K | SDD update |
| `:qa` | ~1.8-2K | Quality check |
| `doc-review` | ~900-1.2K + sub-commands | Full orchestration |
### Monthly Token Budget Examples
**Light Usage (10 updates/month):**
```plaintext
10x :core updates: 12-15K tokens
2x :qa checks: 3.6-4K tokens
1x :help reference: 200 tokens
Total: ~16-19K tokens/month
```
**Medium Usage (20 updates/month):**
```plaintext
15x :core updates: 18-22.5K tokens
4x :sdd updates: 6-7.2K tokens
4x :qa checks: 7.2-8K tokens
1x :help reference: 200 tokens
Total: ~31-38K tokens/month
```
**Heavy Usage (40 updates/month):**
```plaintext
25x :core updates: 30-37.5K tokens
8x :sdd updates: 12-14.4K tokens
8x :qa checks: 14.4-16K tokens
4x orchestrated: 12-16K tokens
1x :help reference: 200 tokens
Total: ~69-84K tokens/month
```
**Original System (Same Usage):**
```
40x monolithic commands: 400-480K tokens/month
Savings with Phase 3: 83-93%
```
---
## 🔧 Troubleshooting
### "Command not found: /ck:doc-review/core"
**Cause:** Sub-command file not installed
**Solution:**
```bash
# Check if files exist
ls ~/.claude/commands/ck/doc-review*.md
# Should see all sub-command files
# If missing, reinstall from docs
```
---
### "Analysis fails with error"
**Cause:** doc-analyzer.sh not executable or not found
**Solution:**
```bash
# Check if tool exists
ls -l ~/.claude/tools/doc-analyzer.sh
# Make executable
chmod +x ~/.claude/tools/doc-analyzer.sh
# Test manually
~/.claude/tools/doc-analyzer.sh help
```
---
### "QA reports many broken links"
**Cause:** Links broken after file reorganization
**Solution:**
```bash
# Run QA to identify broken links
/ck:doc-review/qa
# Fix links in reported files
# Re-run QA to verify
/ck:doc-review/qa
```
---
### "SDD consistency check fails"
**Cause:** Requirements/tasks out of sync with code
**Solution:**
```bash
# Update SDD artifacts
/ck:doc-review/sdd "current feature"
# Manually review any remaining inconsistencies
# Update as needed
```
---
## 💡 Tips & Best Practices
### 1. Run `:analyze` First (New Projects)
```bash
# When starting with a new project
/ck:doc-review/analyze
→ Understand doc structure
→ Identify gaps
→ Plan updates
```
### 2. Use `:core` for Quick Updates
```bash
# Daily workflow: added feature, need docs
/ck:doc-review/core "feature name"
→ Fast (20s)
→ Low token cost (1.2K)
→ Updates essentials
```
### 3. Run `:qa` Before Commits
```bash
# Git workflow
git add .
/ck:doc-review/qa # Check doc quality
→ Fix any issues
git commit -m "docs: ..."
```
### 4. Use Orchestrator When Unsure
```bash
# Not sure what needs updating?
/ck:doc-review "what changed"
→ Guided workflow
→ Smart recommendations
→ You choose scope
```
### 5. Batch SDD Updates
```bash
# Don't update SDD after every task
# Batch at phase boundaries
/ck:doc-review/sdd "Phase 2 complete"
→ More efficient
→ Better overview
→ Cleaner commits
```
---
## 🎯 Decision Tree: Which Command to Use?
```text
Start
│
├─ Need help? → /ck:doc-review/help
│
├─ Just want to see what needs updating?
│ └─ /ck:doc-review/analyze
│
├─ Added new feature/module?
│ └─ /ck:doc-review/core "feature name"
│
├─ Completed implementation phase?
│ └─ /ck:doc-review/sdd "phase name"
│
├─ About to commit documentation?
│ └─ /ck:doc-review/qa
│
├─ Not sure what to do?
│ └─ /ck:doc-review "what changed"
│
└─ Want comprehensive update?
└─ /ck:doc-review "scope" → Select "Full Update"
```
---
## 📚 Further Reading
**Architecture Deep Dive:**
- `docs/ck-doc-review-analysis.md` - Initial architecture analysis
- `docs/ck-doc-review-phase3-improvements.md` - Current system design
**Phase Evolution:**
- Phase 1: Progressive disclosure + patterns config
- Phase 2: External tool architecture
- Phase 3: Full modularization (current)
**External Tools:**
- `~/.claude/tools/doc-analyzer.sh help` - Tool documentation
- Run `doc-analyzer.sh all` to see full analysis output
---
## 🆘 Getting Help
### Within the System
```bash
/ck:doc-review/help # This guide
~/.claude/tools/doc-analyzer.sh help # Tool help
```
### Documentation Files
```bash
cat docs/ck-doc-review-phase3-improvements.md # Full system docs
```
### Quick Reference Card
```bash
# Analysis
/ck:doc-review/analyze
# Updates
/ck:doc-review/core "feature" # Quick
/ck:doc-review/sdd "phase" # SDD
/ck:doc-review "scope" # Full
# Validation
/ck:doc-review/qa
# Help
/ck:doc-review/help
```
---
## ✨ Key Takeaways
1. **Modular = Efficient** - Use focused commands, not monolithic tool
2. **Analyze First** - Understand before updating
3. **Core for Speed** - Most common use case
4. **QA Before Commit** - Catch issues early
5. **Orchestrate When Unsure** - Guided workflow helps
---
**Last Updated:** 2025-10-24
**Version:** Phase 3 (Modular Architecture)
**System Status:** Production Ready ✅

137
commands/main.md Normal file
View File

@@ -0,0 +1,137 @@
---
description: Documentation update orchestrator - analyzes and delegates to sub-commands
allowed-tools: Bash(~/.claude/commands/ck/doc-review/tools/analyzer.sh:*), Bash(~/.claude/tools/doc-analyzer.sh:*), Read(*), SlashCommand(*), AskUserQuestion(*)
---
# Documentation Update Orchestrator
## Context
- Analysis:
!`~/.claude/commands/ck/doc-review/tools/analyzer.sh all || ~/.claude/tools/doc-analyzer.sh all`
## Task
**Update all documentation for:** $ARGUMENTS
**🎯 Smart Orchestration:** This command analyzes your changes and delegates to sub-commands.
---
## Analysis Review
Review the analysis output above to understand:
✅ **Principles:** Project documentation constraints (if any)
✅ **Structure:** Current documentation organization
✅ **Changes:** Files modified in recent commits
✅ **Impact:** Which documentation needs updating
---
## Recommended Update Plan
Based on the analysis, here's what needs updating:
**Available Sub-Commands:**
- `/ck:doc-review/quick` - Fast updates, no analysis (~400-600 tokens)
- `/ck:doc-review/analyze` - Run analysis only (no updates)
- `/ck:doc-review/core` - Update README, CLAUDE, CHANGELOG
- `/ck:doc-review/sdd` - Update SDD artifacts (spec.md, plan.md, tasks.md)
- `/ck:doc-review/qa` - Quality validation and link checking
---
## User Confirmation
Use AskUserQuestion to ask:
### Question: Which documentation should be updated?
**header:** "Update Scope"
**question:** "Which documentation areas should be updated for: $ARGUMENTS"
**multiSelect:** true
**options:**
- **label:** "Core Files"
**description:** "README.md, CLAUDE.md, CHANGELOG.md - Quick updates (1-2 min)"
- **label:** "SDD Artifacts"
**description:** "specs/\*/spec.md, plan.md, tasks.md - Specification updates (2-3 min)"
- **label:** "Run QA Only"
**description:** "Link validation, consistency checks - No content changes"
- **label:** "Full Update"
**description:** "All documentation areas - Comprehensive update (3-5 min)"
---
## Execution
Based on user selection, invoke appropriate sub-commands:
### If "Core Files" selected
```bash
/ck:doc-review/core $ARGUMENTS
```
### If "SDD Artifacts" selected
```bash
/ck:doc-review/sdd $ARGUMENTS
```
### If "Run QA Only" selected
```bash
/ck:doc-review/qa
```
### If "Full Update" selected
```bash
/ck:doc-review/core $ARGUMENTS
/ck:doc-review/sdd $ARGUMENTS
/ck:doc-review/qa
```
**⚠️ Note:** Run sub-commands sequentially, wait for each to complete before running the next.
---
## Final Summary
After all sub-commands complete, provide aggregated summary:
### 📊 Complete Documentation Update Summary
**Scope:** $ARGUMENTS
**Sub-Commands Executed:**
- [List which sub-commands ran]
**Total Updates:**
- Files modified: [aggregate count]
- Total time: [sum of execution times]
**Next Steps:**
- [ ] Review changes: `git diff`
- [ ] Commit updates: `git add . && git commit -m "docs: ..."`
- [ ] Push if ready: `git push`
---
## Benefits of Modular Approach
✅ **90% Token Reduction** - Only load what you need
✅ **Faster Execution** - Focused commands run in < 1s
✅ **Clear Responsibility** - Each command does one thing well
✅ **Reusable** - Use sub-commands independently
✅ **Composable** - Mix and match as needed

480
commands/qa.md Normal file
View File

@@ -0,0 +1,480 @@
---
description: Quality validation - auto-fix linting, check links, consistency, completeness
allowed-tools: Bash(find:*), Bash(grep:*), Bash(git:*), Bash(npm:*), Read(*), Grep(*), Glob(*), Edit(*), Write(*)
---
# Quality Assurance Validation Command
## Context
- All markdown files: !`find . -name "*.md" | wc -l`
- Recent doc changes:
!`git log -5 --oneline -- "*.md" 2>/dev/null || echo "No recent doc commits"`
## Task
**Quality validation and auto-fix** - Automatically fixes formatting issues with
linting tools, then performs validation checks for links, consistency, and
completeness.
---
## Linting & Auto-Fix Phase
### Step 1: Check for Linting Tools
```bash
# Check if markdownlint is available
which markdownlint || npm list -g markdownlint || echo "markdownlint not found"
# Check if prettier is available
which prettier || npm list -g prettier || echo "prettier not found"
```
### Step 2: Install Tools if Missing
If tools are not available:
```bash
npm install -g markdownlint-cli prettier
```
### Step 3: Auto-Fix Markdown Files
**Run markdownlint with auto-fix enabled:**
```bash
markdownlint --fix . --ignore node_modules --ignore '.git'
```
This automatically fixes:
- MD032: Lists surrounded by blank lines
- MD034: Bare URLs wrapped in links
- MD036: Emphasis used instead of headings
- MD040: Fenced code blocks with language specified
- MD059: Link text descriptive
**Run prettier for consistent formatting:**
```bash
prettier --write "**/*.md"
```
This formats:
- Line length consistency
- Indentation
- List formatting
- Code block formatting
### Step 4: Verify Changes
```bash
# Show what was changed
git diff --name-only 2>/dev/null || echo "Not a git repo"
# Count auto-fixed issues
echo "✅ Auto-fix complete"
```
---
## QA Check 1: Link Validation
### Find All Markdown Links
Search for markdown links in all .md files:
```bash
# Find all links
find . -name "*.md" -exec grep -o '\[.*\](.*\.md)' {} +
# Find relative links
find . -name "*.md" -exec grep -o '](\.\.*/.*\.md)' {} +
```
### Validate Links
For each link found:
- Check if target file exists
- Note broken links
- Note external links (for manual review)
**Report Format:**
```text
✅ Valid links: [count]
❌ Broken links: [count]
⚠️ External links: [count] (manual review needed)
Broken Links Found:
- file.md:123 → links to missing-file.md
- [...]
```
---
## QA Check 2: Cross-Reference Consistency
### File:Line References
Find all code references (e.g., `path/to/file.py:123`):
```bash
find . -name "*.md" -exec grep -o '[a-zA-Z0-9_/.-]*\.[a-z]*:[0-9]*' {} +
```
### Validate References
For each reference:
- Check if file exists
- Optionally check if line number is reasonable (file has that many lines)
**Report Format:**
```text
✅ Valid references: [count]
❌ Invalid file references: [count]
⚠️ Questionable line numbers: [count]
Issues Found:
- README.md mentions deleted_file.py:50
- CLAUDE.md references file.py:999 (file only has 200 lines)
```
---
## QA Check 3: Terminology Consistency
### Extract Key Terms
Find variations of important terms:
```bash
# Example: Find all variations of "apstra"
grep -i "apstra\|APSTRA\|Apstra" . -r --include="*.md"
# Check for inconsistent capitalization
# Check for inconsistent naming (e.g., "doc review" vs "doc-review")
```
### Common Inconsistencies to Check
- Product names (capitalization)
- Feature names (hyphenation)
- Technical terms (spelling variations)
- Version numbers (consistency)
**Report Format:**
```text
📝 Terminology Review:
Consistent:
- ✅ "Apstra" used consistently (capitalized)
- ✅ "NetworkX" spelling consistent
Inconsistent:
- ⚠️ "doc-review" vs "doc review" (3 vs 2 occurrences)
- ⚠️ "Python" vs "python" mixed usage
Recommendations:
- Standardize on "doc-review" (hyphenated)
- Use "Python" (capitalized) for language name
```
---
## QA Check 4: Version Number Consistency
### Find All Version References
```bash
# Find version patterns
grep -E "v?[0-9]+\.[0-9]+\.[0-9]+" . -r --include="*.md"
grep -E "version.*[0-9]" . -r --include="*.md" -i
```
### Check Consistency
- Same version mentioned in multiple places?
- CHANGELOG.md version matches README.md?
- pyproject.toml version matches documentation?
**Report Format:**
```text
📊 Version Consistency:
Found Versions:
- README.md: v1.2.0
- CHANGELOG.md: 1.2.0 (latest entry)
- pyproject.toml: 1.1.5
Issues:
- ❌ Version mismatch: README (1.2.0) vs pyproject.toml (1.1.5)
Recommendation:
- Update pyproject.toml to 1.2.0 or clarify version strategy
```
---
## QA Check 5: SDD Consistency (if applicable)
### Check Requirement Traceability
Find all requirement IDs (FR-\*, NFR-\*):
```bash
grep -E "(FR|NFR)-[0-9]+" . -r --include="*.md"
```
### Validate Traceability
- Are requirements in spec.md referenced in plan.md?
- Are completed requirements (✅) in spec.md also marked done in tasks.md?
- Are all requirements accounted for?
**Report Format:**
```text
🔍 SDD Traceability:
Requirements in spec.md: [count]
Requirements in plan.md: [count]
Requirements in tasks.md: [count]
Orphaned Requirements:
- FR-005 appears in spec.md but not in tasks.md
- [...]
Completed but Not Marked:
- FR-003 marked done in tasks.md but not in spec.md
```
---
## QA Check 6: Code Example Syntax
### Find Code Blocks
```bash
# Find all code fences
grep -E "^\`\`\`" . -r --include="*.md"
```
### Basic Syntax Check
- Are code fences properly closed?
- Is language specified (`python vs`)?
- Look for obvious syntax errors in examples
**Report Format:**
```text
💻 Code Example Review:
Code blocks found: [count]
Language specified: [count]/[total]
Unclosed fences: [count]
Issues:
- README.md:50 - Code fence not closed
- CLAUDE.md:120 - No language specified
```
---
## QA Check 7: Completeness Check
### Required Sections
Check if standard files have expected sections:
**README.md:**
- [ ] Project description
- [ ] Installation
- [ ] Usage examples
- [ ] Configuration
- [ ] License
**CLAUDE.md:**
- [ ] Project overview
- [ ] Core architecture
- [ ] Key modules
- [ ] Common workflows
**CHANGELOG.md:**
- [ ] Recent version entries
- [ ] Categorized changes (Added/Changed/Fixed)
- [ ] Dates
**Report Format:**
```text
📋 Completeness Check:
README.md:
- ✅ Has installation section
- ✅ Has usage examples
- ❌ Missing troubleshooting section
CLAUDE.md:
- ✅ Has architecture overview
- ⚠️ Core modules section is sparse
```
---
## Output: QA Summary Report
### 📊 Documentation Quality Assurance Report
**Validation Date:** [YYYY-MM-DD]
---
### Auto-Fix Results
**Linting & Formatting Phase:**
- ✅ markdownlint: [X] issues auto-fixed
- ✅ prettier: [X] files reformatted
- Files modified: [list of files]
- Time taken: < 1 second
**Common fixes applied:**
- Blank lines around lists (MD032)
- Bare URLs wrapped in links (MD034)
- Link text made descriptive (MD059)
- Code blocks with language specified (MD040)
- Emphasis replaced with headings (MD036)
---
### Overall Quality Score
**Baseline Score:** [X]/100 (before fixes)
**After Fixes:** [X]/100 (after linting)
---
### Link Validation
- ✅ Valid links: [count]
- ❌ Broken links: [count]
- Score: [X]/20
### Cross-Reference Validation
- ✅ Valid references: [count]
- ❌ Invalid references: [count]
- Score: [X]/15
### Terminology Consistency
- Inconsistencies found: [count]
- Score: [X]/15
### Version Consistency
- Matches found: [count]
- Mismatches: [count]
- Score: [X]/15
### SDD Consistency
- Orphaned requirements: [count]
- Traceability: [X]%
- Score: [X]/15
### Code Example Quality
- Syntax issues: [count]
- Score: [X]/10
### Completeness
- Missing sections: [count]
- Score: [X]/10
---
### Priority Issues
**High Priority (Fix Immediately):**
1. [Issue description and location]
2. [...]
**Medium Priority (Fix Soon):**
1. [Issue description and location]
2. [...]
**Low Priority (Nice to Have):**
1. [Issue description and location]
2. [...]
---
### Recommended Actions
1. **Fix broken links:**
- [Specific links to fix]
2. **Update version numbers:**
- [Where to update]
3. **Standardize terminology:**
- Use "[term]" instead of "[variation]"
4. **Complete missing sections:**
- Add troubleshooting to README.md
- [...]
---
## Next Steps
- [x] Auto-fixed linting issues (markdownlint + prettier)
- [ ] Review and fix high-priority semantic issues
- [ ] Fix medium-priority issues (links, terminology, versions)
- [ ] Consider low-priority improvements
- [ ] Commit auto-fixes: `git commit -m "docs: Auto-fix linting issues (markdownlint + prettier)"`
- [ ] Re-run QA to verify: `/ck:doc-review/qa`
---
## Implementation Notes
### Auto-Fix Behavior
- **Automatic:** Linting tools run automatically on every QA check
- **Non-destructive:** Only formatting and style issues are auto-fixed
- **Semantic issues:** Links, terminology, versions require manual review
- **Git-aware:** Shows diff of changes made
### Tool Requirements
- **markdownlint-cli:** Auto-fixes MD032, MD034, MD036, MD040, MD059
- **prettier:** Enforces consistent code formatting
- Both tools are lightweight and zero-dependency
### Configuration
Tools use standard configurations:
- `.markdownlintrc` - Markdownlint rules (if present)
- `.prettierrc` - Prettier rules (if present)
- Falls back to defaults if no config found

150
commands/quick.md Normal file
View File

@@ -0,0 +1,150 @@
---
description: Quick documentation update - skip analysis, direct edits only
allowed-tools: Read(*), Edit(*), Write(*), Bash(git:*)
---
# Quick Documentation Update
**⚡ Lightweight Mode** - No analysis, no validation, just updates
**Token Cost:** 400-600 tokens (vs 1.2-1.5K for full :core)
**Execution Time:** < 30 seconds
**Use Case:** Known, simple documentation updates
---
## Task
**Quick update for:** $ARGUMENTS
**Fast path:** Skip analysis → Update files → Done
---
## Files to Update
Based on $ARGUMENTS, update one or more:
- **README.md** - Features, installation, usage, configuration
- **CLAUDE.md** - AI context, module documentation
- **CHANGELOG.md** - Add new version entry
---
## Step 1: Identify Target File
Based on $ARGUMENTS, determine which file to update:
- Feature/usage change → README.md
- New module/component → CLAUDE.md
- Release/version change → CHANGELOG.md
---
## Step 2: Direct Edit (No Analysis)
Quickly update the target file without analysis:
**For README.md:**
- Add/update feature description in Features section
- Update Installation if dependencies changed
- Add Usage example
**For CLAUDE.md:**
- Add new module documentation
- Update architecture notes if changed
- Document new components
**For CHANGELOG.md:**
- Add new version entry at top
- Categorize: Added/Changed/Fixed
- Include dates and file references
---
## Step 3: Quick Validation
Only check what was actually changed:
- ✅ File exists and is readable
- ✅ No syntax errors in edited sections
- ✅ Basic formatting correct
Do NOT run full QA or linting.
---
## Step 4: Summary
Show what was changed:
- Files modified: [list]
- Lines changed: [approximate count]
- Execution time: [< 30 seconds]
---
## Example Usage
```bash
/ck:doc-review:quick "added new feature X"
# Updates README.md with new feature → Done (< 1K tokens)
/ck:doc-review:quick "new API endpoint"
# Updates CLAUDE.md with endpoint docs → Done (< 1K tokens)
/ck:doc-review:quick "version 1.2.0 release"
# Updates CHANGELOG.md with release notes → Done (< 1K tokens)
```
---
## When to Use Quick Mode
✅ **Use quick mode when:**
- Update is simple and straightforward
- You know exactly what needs changing
- No validation needed
- Speed is priority over completeness
❌ **Don't use quick mode when:**
- Update is complex or affects multiple files
- Need comprehensive analysis first
- Want full QA validation
- Documentation has many interconnections
---
## When to Use Full Mode
For comprehensive updates with analysis and validation:
```bash
# Full analysis before updating
/ck:doc-review:analyze "feature"
# Full update with QA validation
/ck:doc-review:core "feature"
# SDD artifact updates
/ck:doc-review:sdd "phase"
# Quality assurance
/ck:doc-review:qa
```
---
## Token Savings Comparison
| Task | Mode | Tokens | Time |
|------|------|--------|------|
| Add feature to README | quick | 400-600 | < 30s |
| Add feature to README | core | 1.2-1.5K | 2-3s |
| New module to CLAUDE | quick | 400-600 | < 30s |
| New module to CLAUDE | core | 1.2-1.5K | 2-3s |
| CHANGELOG entry | quick | 300-500 | < 20s |
| CHANGELOG entry | core | 1.2-1.5K | 2-3s |
**Savings:** 60-70% tokens, 90%+ execution time reduction

326
commands/sdd.md Normal file
View File

@@ -0,0 +1,326 @@
---
description: Update SDD artifacts (spec.md, plan.md, tasks.md, contracts)
allowed-tools: Bash(find:*), Bash(git:*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
---
# SDD Artifacts Update Command
## Context
- SDD files:
!`find ./specs -name "spec.md" -o -name "plan.md" -o -name "tasks.md" | sort`
- Recent changes:
!`git diff --name-only HEAD~5..HEAD 2>/dev/null || echo "No recent commits"`
## Task
**Update SDD artifacts for:** $ARGUMENTS
SDD stands for Specification-Driven Development.
**Target files:**
- specs/\*/spec.md - Functional requirements
- specs/\*/plan.md - Implementation plan
- specs/\*/tasks.md - Task breakdown
- specs/_/contracts/_.md - Design contracts
---
## Step 1: Identify Relevant Spec Directory
Based on $ARGUMENTS, determine which spec directory to update:
- Extract feature number (e.g., "feature 005" → specs/005-\*)
- Or identify by feature name
- List matching directories found
---
## Step 2: Update spec.md (Functional Requirements)
### Read Current spec.md
Read the relevant specs/\*/spec.md file.
### Update Requirements
**What to update:**
1. **Mark Completed Requirements:**
- Find requirements (FR-\*) that are now implemented
- Change status markers:
- [ ] → [x] for completed
- Add ✅ emoji if used in doc
2. **Add New Requirements (if discovered during implementation):**
````markdown
### FR-[N]: [Requirement Title]
**Priority:** [High/Medium/Low]
**Status:** [Planned/In Progress/Completed]
**Description:**
[What the requirement is]
**Acceptance Criteria:**
- [ ] Criterion 1
- [ ] Criterion 2
**Implementation Notes:**
[Details from actual implementation]
````
3. **Update Requirement Details:**
- Add implementation notes to existing requirements
- Update acceptance criteria based on what was actually built
- Note any deviations from original plan
### Make Updates
Apply changes using Edit tool.
---
## Step 3: Update plan.md (Implementation Plan)
### Read Current plan.md
Read the relevant specs/\*/plan.md file.
### Update Plan Status
**What to update:**
1. **Phase Completion:**
````markdown
## Implementation Phases
### Phase 1: [Name]
**Status:** ✅ Completed
**Completion Date:** YYYY-MM-DD
**Implemented:**
- [What was built]
- [What was built]
**Deviations:**
- [Any changes from original plan]
````
2. **Architecture Decisions:**
````markdown
### Architecture Decision: [Title]
**Decision:** [What was decided]
**Rationale:** [Why this approach was chosen]
**Alternatives Considered:** [Other options]
**Implementation:** path/to/file.py:123
**Trade-offs:**
- Pro: [Benefit]
- Con: [Cost]
````
3. **Design Patterns Used:**
````markdown
### Design Pattern: [Pattern Name]
**Location:** path/to/implementation.py:123
**Purpose:** [Why this pattern was used]
**Implementation Details:** [How it's implemented]
````
4. **Risk Updates:**
- Mark mitigated risks as resolved
- Add any new risks discovered
- Update risk status
### Make Updates
Apply changes using Edit tool.
---
## Step 4: Update tasks.md (Task Breakdown)
### Read Current tasks.md
Read the relevant specs/\*/tasks.md file.
### Update Task Status
**What to update:**
1. **Mark Completed Tasks:**
````markdown
- [x] Task name
- **Status:** ✅ Completed
- **Completion Date:** YYYY-MM-DD
- **Implementation:** path/to/file.py:123
- **Notes:** [Any lessons learned or important details]
````
2. **Update In-Progress Tasks:**
````markdown
- [ ] Task name
- **Status:** 🔄 In Progress (60% complete)
- **Current State:** [What's done, what's remaining]
- **Blockers:** [Any issues]
````
3. **Add New Tasks (if discovered):**
````markdown
- [ ] New task discovered during implementation
- **Priority:** High
- **Dependency:** [Other tasks this depends on]
- **Estimate:** [Time estimate]
````
### Make Updates
Apply changes using Edit tool.
---
## Step 5: Update Design Contracts (if applicable)
### Find Contract Files
Look for specs/_/contracts/_.md files related to this feature.
### Update Contracts
**What to update:**
1. **API Contracts:**
````markdown
## Endpoint: [Name]
**Method:** GET/POST/etc
**Path:** /api/v1/resource
**Request:**
```json
{
"param": "value"
}
```
````
**Response:**
```json
{
"result": "value"
}
```
**Implementation:** path/to/handler.py:123
````
2. **Interface Contracts:**
```markdown
## Interface: [ClassName]
**Location:** path/to/file.py:123
**Methods:**
- `method_name(param: Type) -> ReturnType`
- Purpose: [What it does]
- Example: [Usage example]
````
3. **Data Schema Contracts:**
- Update schema definitions to match actual implementation
- Add examples with real data
- Document any schema changes
### Make Updates
Apply changes using Edit tool for each contract file.
---
## Step 6: SDD Consistency Validation
**Cross-check consistency:**
- [ ] spec.md requirements match implementation
- [ ] plan.md phases align with completed tasks
- [ ] tasks.md references correct file:line locations
- [ ] Contracts match actual API/interface implementation
- [ ] No orphaned requirements (in spec but not in plan/tasks)
- [ ] All completed tasks have corresponding requirement markers
**If inconsistencies found:**
- Document them
- Fix or note as deviations with explanation
---
## Output: Summary
### 📊 SDD Documentation Update Summary
**Scope:** $ARGUMENTS
**Spec Directory:** specs/[directory]
**Files Updated:**
| File | Updates Made | Lines Changed |
| --------------- | ---------------------------------------- | ------------- |
| spec.md | [FR-X completed, FR-Y updated] | ~[estimate] |
| plan.md | [Phase X status, architecture decisions] | ~[estimate] |
| tasks.md | [X tasks completed, Y added] | ~[estimate] |
| contracts/\*.md | [Contracts updated] | ~[estimate] |
**Requirement Status:**
- Completed: [count] requirements
- In Progress: [count] requirements
- Remaining: [count] requirements
**Phase Status:**
- Completed phases: [list]
- Current phase: [name] ([%] complete)
- Remaining phases: [list]
**SDD Consistency:**
- [x] Requirements ↔ Implementation aligned
- [x] Plan ↔ Tasks aligned
- [x] Contracts ↔ Code aligned
- [x] No orphaned requirements
- [x] All references accurate
**Execution Time:** [X]s
---
## Next Steps
Recommended actions:
- [ ] Review SDD updates: `git diff specs/`
- [ ] Update core docs: `/ck:doc-review/core $ARGUMENTS`
- [ ] Run QA validation: `/ck:doc-review/qa`
- [ ] Commit SDD updates with message like: `docs(sdd): Update spec 005 for feature implementation`

69
plugin.lock.json Normal file
View File

@@ -0,0 +1,69 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:kimcharli/ck-skills:plugins/doc-review-commands",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "64c2b2778f4a7b78e603f2e0944e533654bb350e",
"treeHash": "24f8de940935460ab19035e02f6b44060c0ed1a095682c0b3b2104dc868b92ee",
"generatedAt": "2025-11-28T10:19:32.265755Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "doc-review-commands",
"description": "AI-powered documentation management system for Claude Code - keeps project documentation in sync with code changes",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "50dac793a6f6b7af2cf37d1e089d45bc056e59793113e64a6340d8204388ede0"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "702c6e3a2f0894a1ff9fec530e31a08eab7becdcac892aad88046613e615364a"
},
{
"path": "commands/qa.md",
"sha256": "7804c3b5ee971b13dfc868c21491b549f381807cbaba260a1bf32549daece591"
},
{
"path": "commands/analyze.md",
"sha256": "9603250574de21738e746726f79e77aa480a6cad6ef1a5862f0a3f5bba7a9f80"
},
{
"path": "commands/help.md",
"sha256": "c958d2a8fc6191a7fbefc3554fbfed62cf21efc4c0699ab1950d025ccbe2b72f"
},
{
"path": "commands/main.md",
"sha256": "3866c82c05395ba423819990e6ce1744cc4c26b77cd50f496faaea1090e83df5"
},
{
"path": "commands/core.md",
"sha256": "6bd93f25094754fb0dc5b815f32ee615c8a12bb494d4fe8dd972b0c4c5c9a223"
},
{
"path": "commands/sdd.md",
"sha256": "db538d347bece85a4061307ef04010297edd36b48ef18ac48053639c1e1af4f0"
},
{
"path": "commands/quick.md",
"sha256": "a5ad0363e17b92cb9bd2cb4ee5d9246a74a58174154f41ec3d2de71142b45fc3"
}
],
"dirSha256": "24f8de940935460ab19035e02f6b44060c0ed1a095682c0b3b2104dc868b92ee"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}