refactor: extract skills from commands across 8 plugins
Refactored commands to extract reusable skills following the Commands → Skills separation pattern. Each command is now <50 lines and references skill files for detailed knowledge. Plugins refactored: - claude-config-maintainer: 5 commands → 7 skills - code-sentinel: 3 commands → 2 skills - contract-validator: 5 commands → 6 skills - data-platform: 10 commands → 6 skills - doc-guardian: 5 commands → 6 skills (replaced nested dir) - git-flow: 8 commands → 7 skills Skills contain: workflows, validation rules, conventions, reference data, tool documentation Commands now contain: YAML frontmatter, agent assignment, skills list, brief workflow steps, parameters Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -6,116 +6,49 @@ description: Generate changelog from conventional commits in Keep-a-Changelog fo
|
||||
|
||||
Generate a changelog entry from conventional commits.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/changelog-format.md
|
||||
|
||||
## Visual Output
|
||||
|
||||
When executing this command, display the plugin header:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 📝 DOC-GUARDIAN · Changelog Generation │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
+------------------------------------------------------------------+
|
||||
| DOC-GUARDIAN - Changelog Generation |
|
||||
+------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Then proceed with the generation.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Identify Commit Range**
|
||||
- Default: commits since last tag
|
||||
- Optional: specify range (e.g., `v1.0.0..HEAD`)
|
||||
- Detect if this is first release (no previous tags)
|
||||
Execute `skills/changelog-format.md` - detect range from tags
|
||||
|
||||
2. **Parse Conventional Commits**
|
||||
Extract from commit messages following the pattern:
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
**Recognized Types:**
|
||||
| Type | Changelog Section |
|
||||
|------|------------------|
|
||||
| `feat` | Added |
|
||||
| `fix` | Fixed |
|
||||
| `docs` | Documentation |
|
||||
| `perf` | Performance |
|
||||
| `refactor` | Changed |
|
||||
| `style` | Changed |
|
||||
| `test` | Testing |
|
||||
| `build` | Build |
|
||||
| `ci` | CI/CD |
|
||||
| `chore` | Maintenance |
|
||||
| `BREAKING CHANGE` | Breaking Changes |
|
||||
Use pattern from skill: `<type>(<scope>): <description>`
|
||||
|
||||
3. **Group by Type**
|
||||
Organize commits into Keep-a-Changelog sections:
|
||||
- Breaking Changes (if any `!` suffix or `BREAKING CHANGE` footer)
|
||||
- Added (feat)
|
||||
- Changed (refactor, style, perf)
|
||||
- Deprecated
|
||||
- Removed
|
||||
- Fixed (fix)
|
||||
- Security
|
||||
Map to Keep-a-Changelog sections per skill
|
||||
|
||||
4. **Format Entries**
|
||||
For each commit:
|
||||
- Extract scope (if present) as prefix
|
||||
- Extract scope as bold prefix
|
||||
- Use description as entry text
|
||||
- Link to commit hash if repository URL available
|
||||
- Include PR/issue references from footer
|
||||
- Link commit hashes if repo URL available
|
||||
|
||||
5. **Output Format**
|
||||
```markdown
|
||||
## [Unreleased]
|
||||
|
||||
### Breaking Changes
|
||||
- **scope**: Description of breaking change
|
||||
|
||||
### Added
|
||||
- **scope**: New feature description
|
||||
- Another feature without scope
|
||||
|
||||
### Changed
|
||||
- **scope**: Refactoring description
|
||||
|
||||
### Fixed
|
||||
- **scope**: Bug fix description
|
||||
|
||||
### Documentation
|
||||
- Updated README with new examples
|
||||
```
|
||||
5. **Output**
|
||||
Use format from `skills/changelog-format.md`
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--from <tag>` | Start from specific tag | Latest tag |
|
||||
| `--to <ref>` | End at specific ref | HEAD |
|
||||
| `--version <ver>` | Set version header | [Unreleased] |
|
||||
| `--include-merge` | Include merge commits | false |
|
||||
| `--group-by-scope` | Group by scope within sections | false |
|
||||
| `--from <tag>` | Start from tag | Latest tag |
|
||||
| `--to <ref>` | End at ref | HEAD |
|
||||
| `--version <ver>` | Version header | [Unreleased] |
|
||||
| `--include-merge` | Include merges | false |
|
||||
| `--group-by-scope` | Group by scope | false |
|
||||
|
||||
## Integration
|
||||
|
||||
The generated output is designed to be copied directly into CHANGELOG.md:
|
||||
Output designed for direct copy to CHANGELOG.md:
|
||||
- Follows [Keep a Changelog](https://keepachangelog.com) format
|
||||
- Compatible with semantic versioning
|
||||
- Excludes non-user-facing commits (chore, ci, test by default)
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/changelog-gen
|
||||
/changelog-gen --from v1.0.0 --version 1.1.0
|
||||
/changelog-gen --include-merge --group-by-scope
|
||||
```
|
||||
|
||||
## Non-Conventional Commits
|
||||
|
||||
Commits not following conventional format are:
|
||||
- Listed under "Other" section
|
||||
- Flagged for manual categorization
|
||||
- Skipped if `--strict` flag is used
|
||||
|
||||
@@ -6,33 +6,26 @@ description: Full documentation audit - scans entire project for doc drift witho
|
||||
|
||||
Perform a comprehensive documentation drift analysis.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/drift-detection.md
|
||||
- skills/doc-patterns.md
|
||||
|
||||
## Visual Output
|
||||
|
||||
When executing this command, display the plugin header:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 📝 DOC-GUARDIAN · Documentation Audit │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
+------------------------------------------------------------------+
|
||||
| DOC-GUARDIAN - Documentation Audit |
|
||||
+------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Then proceed with the audit.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Inventory Documentation Files**
|
||||
- README.md (root and subdirectories)
|
||||
- CLAUDE.md
|
||||
- API documentation
|
||||
- Docstrings in code files
|
||||
- Configuration references
|
||||
Execute `skills/doc-patterns.md` - identify all doc files
|
||||
|
||||
2. **Cross-Reference Analysis**
|
||||
For each documentation file:
|
||||
- Extract referenced functions, classes, endpoints, configs
|
||||
- Verify each reference exists in codebase
|
||||
- Check signatures/types match documentation
|
||||
- Flag deprecated or renamed items still in docs
|
||||
Execute `skills/drift-detection.md` - verify all references
|
||||
|
||||
3. **Completeness Check**
|
||||
- Public functions without docstrings
|
||||
@@ -40,23 +33,7 @@ Then proceed with the audit.
|
||||
- Environment variables used but not documented
|
||||
- CLI commands not in help text
|
||||
|
||||
4. **Output Format**
|
||||
```
|
||||
## Documentation Drift Report
|
||||
|
||||
### Critical (Broken References)
|
||||
- [ ] README.md:45 references `calculate_total()` - function renamed to `compute_total()`
|
||||
|
||||
### Stale (Outdated Info)
|
||||
- [ ] CLAUDE.md:23 lists Python 3.9 - project uses 3.11
|
||||
|
||||
### Missing (Undocumented)
|
||||
- [ ] api/handlers.py:`create_order()` - no docstring
|
||||
|
||||
### Summary
|
||||
- Critical: X items
|
||||
- Stale: X items
|
||||
- Missing: X items
|
||||
```
|
||||
4. **Output**
|
||||
Use format from `skills/drift-detection.md`
|
||||
|
||||
5. **Do NOT make changes** - audit only, report findings
|
||||
|
||||
@@ -6,135 +6,43 @@ description: Calculate documentation coverage percentage for functions and class
|
||||
|
||||
Analyze codebase to calculate documentation coverage metrics.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/coverage-calculation.md
|
||||
- skills/doc-patterns.md
|
||||
|
||||
## Visual Output
|
||||
|
||||
When executing this command, display the plugin header:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 📝 DOC-GUARDIAN · Documentation Coverage │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
+------------------------------------------------------------------+
|
||||
| DOC-GUARDIAN - Documentation Coverage |
|
||||
+------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Then proceed with the analysis.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Scan Source Files**
|
||||
Identify all documentable items:
|
||||
|
||||
**Python:**
|
||||
- Functions (def)
|
||||
- Classes
|
||||
- Methods
|
||||
- Module-level docstrings
|
||||
|
||||
**JavaScript/TypeScript:**
|
||||
- Functions (function, arrow functions)
|
||||
- Classes
|
||||
- Methods
|
||||
- JSDoc comments
|
||||
|
||||
**Other Languages:**
|
||||
- Adapt patterns for Go, Rust, etc.
|
||||
Execute `skills/coverage-calculation.md` - identify documentable items
|
||||
|
||||
2. **Determine Documentation Status**
|
||||
For each item, check:
|
||||
- Has docstring/JSDoc comment
|
||||
- Docstring is non-empty and meaningful (not just `pass` or `TODO`)
|
||||
- Parameters are documented (for detailed mode)
|
||||
- Return type is documented (for detailed mode)
|
||||
Check each item has meaningful docstring/JSDoc
|
||||
|
||||
3. **Calculate Metrics**
|
||||
```
|
||||
Coverage = (Documented Items / Total Items) * 100
|
||||
```
|
||||
Use formula from skill: `Coverage = (Documented / Total) * 100`
|
||||
|
||||
**Levels:**
|
||||
- Basic: Item has any docstring
|
||||
- Standard: Docstring describes purpose
|
||||
- Complete: All parameters and return documented
|
||||
|
||||
4. **Output Format**
|
||||
```
|
||||
## Documentation Coverage Report
|
||||
|
||||
### Summary
|
||||
- Total documentable items: 156
|
||||
- Documented: 142
|
||||
- Coverage: 91.0%
|
||||
|
||||
### By Type
|
||||
| Type | Total | Documented | Coverage |
|
||||
|------|-------|------------|----------|
|
||||
| Functions | 89 | 85 | 95.5% |
|
||||
| Classes | 23 | 21 | 91.3% |
|
||||
| Methods | 44 | 36 | 81.8% |
|
||||
|
||||
### By Directory
|
||||
| Path | Total | Documented | Coverage |
|
||||
|------|-------|------------|----------|
|
||||
| src/api/ | 34 | 32 | 94.1% |
|
||||
| src/utils/ | 28 | 28 | 100.0% |
|
||||
| src/models/ | 45 | 38 | 84.4% |
|
||||
| tests/ | 49 | 44 | 89.8% |
|
||||
|
||||
### Undocumented Items
|
||||
- [ ] src/api/handlers.py:45 `create_order()`
|
||||
- [ ] src/api/handlers.py:78 `update_order()`
|
||||
- [ ] src/models/user.py:23 `UserModel.validate()`
|
||||
```
|
||||
4. **Output**
|
||||
Use format from `skills/coverage-calculation.md`
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--path <dir>` | Scan specific directory | Project root |
|
||||
| `--exclude <glob>` | Exclude files matching pattern | `**/test_*,**/*_test.*` |
|
||||
| `--include-private` | Include private members (_prefixed) | false |
|
||||
| `--include-tests` | Include test files | false |
|
||||
| `--min-coverage <pct>` | Fail if below threshold | none |
|
||||
| `--format <fmt>` | Output format (table, json, markdown) | table |
|
||||
| `--detailed` | Check parameter/return docs | false |
|
||||
| `--exclude <glob>` | Exclude pattern | `**/test_*` |
|
||||
| `--min-coverage <pct>` | Fail if below | none |
|
||||
| `--detailed` | Check params/returns | false |
|
||||
|
||||
## Thresholds
|
||||
## Exit Codes
|
||||
|
||||
Common coverage targets:
|
||||
| Level | Coverage | Description |
|
||||
|-------|----------|-------------|
|
||||
| Minimal | 60% | Basic documentation exists |
|
||||
| Good | 80% | Most public APIs documented |
|
||||
| Excellent | 95% | Comprehensive documentation |
|
||||
|
||||
## CI Integration
|
||||
|
||||
Use `--min-coverage` to enforce standards:
|
||||
```bash
|
||||
# Fail if coverage drops below 80%
|
||||
claude /doc-coverage --min-coverage 80
|
||||
```
|
||||
|
||||
Exit codes:
|
||||
- 0: Coverage meets threshold (or no threshold set)
|
||||
- 0: Coverage meets threshold
|
||||
- 1: Coverage below threshold
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/doc-coverage
|
||||
/doc-coverage --path src/
|
||||
/doc-coverage --min-coverage 85 --exclude "**/generated/**"
|
||||
/doc-coverage --detailed --include-private
|
||||
```
|
||||
|
||||
## Language Detection
|
||||
|
||||
File extensions mapped to documentation patterns:
|
||||
| Extension | Language | Doc Format |
|
||||
|-----------|----------|------------|
|
||||
| .py | Python | Docstrings (""") |
|
||||
| .js, .ts | JavaScript/TypeScript | JSDoc (/** */) |
|
||||
| .go | Go | // comments above |
|
||||
| .rs | Rust | /// doc comments |
|
||||
| .rb | Ruby | # comments, YARD |
|
||||
| .java | Java | Javadoc (/** */) |
|
||||
|
||||
@@ -6,22 +6,23 @@ description: Synchronize all pending documentation updates in a single commit
|
||||
|
||||
Apply all pending documentation updates detected by doc-guardian hooks.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/sync-workflow.md
|
||||
- skills/drift-detection.md
|
||||
|
||||
## Visual Output
|
||||
|
||||
When executing this command, display the plugin header:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 📝 DOC-GUARDIAN · Documentation Sync │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
+------------------------------------------------------------------+
|
||||
| DOC-GUARDIAN - Documentation Sync |
|
||||
+------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Then proceed with the sync.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Review Pending Queue**
|
||||
List all documentation drift detected during this session.
|
||||
Execute `skills/sync-workflow.md` - read `.doc-guardian-queue`
|
||||
|
||||
2. **Batch Updates**
|
||||
For each pending item:
|
||||
@@ -29,48 +30,13 @@ Then proceed with the sync.
|
||||
- Apply the update
|
||||
- Track in change list
|
||||
|
||||
3. **Update Types**
|
||||
|
||||
**Reference Fixes:**
|
||||
- Renamed function/class → update all doc references
|
||||
- Changed signature → update parameter documentation
|
||||
- Removed item → remove or mark deprecated in docs
|
||||
|
||||
**Content Sync:**
|
||||
- Version numbers (Python, Node, dependencies)
|
||||
- Configuration keys/values
|
||||
- File paths and directory structures
|
||||
- Command examples and outputs
|
||||
|
||||
**Structural:**
|
||||
- Add missing sections for new features
|
||||
- Remove sections for deleted features
|
||||
- Reorder to match current code organization
|
||||
|
||||
4. **Commit Strategy**
|
||||
3. **Commit Strategy**
|
||||
- Stage all doc changes together
|
||||
- Single commit: `docs: sync documentation with code changes`
|
||||
- Include summary of what was updated in commit body
|
||||
- Include summary in commit body
|
||||
|
||||
5. **Clear Queue**
|
||||
After successful sync, clear the queue file:
|
||||
```bash
|
||||
echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
|
||||
```
|
||||
4. **Clear Queue**
|
||||
After successful sync, clear the queue file
|
||||
|
||||
6. **Output**
|
||||
```
|
||||
## Documentation Sync Complete
|
||||
|
||||
### Files Updated
|
||||
- README.md (3 changes)
|
||||
- CLAUDE.md (1 change)
|
||||
- src/api/README.md (2 changes)
|
||||
|
||||
### Changes Applied
|
||||
- Updated function reference: calculate_total → compute_total
|
||||
- Updated Python version: 3.9 → 3.11
|
||||
- Added docstring to create_order()
|
||||
|
||||
Committed: abc123f
|
||||
```
|
||||
5. **Output**
|
||||
Use format from `skills/sync-workflow.md`
|
||||
|
||||
@@ -6,30 +6,23 @@ description: Detect documentation files that are stale relative to their associa
|
||||
|
||||
Identify documentation files that may be outdated based on commit history.
|
||||
|
||||
## Skills to Load
|
||||
|
||||
- skills/staleness-metrics.md
|
||||
- skills/drift-detection.md
|
||||
|
||||
## Visual Output
|
||||
|
||||
When executing this command, display the plugin header:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 📝 DOC-GUARDIAN · Stale Documentation Check │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
+------------------------------------------------------------------+
|
||||
| DOC-GUARDIAN - Stale Documentation Check |
|
||||
+------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
Then proceed with the check.
|
||||
|
||||
## Process
|
||||
|
||||
1. **Map Documentation to Code**
|
||||
Build relationships between docs and code:
|
||||
|
||||
| Doc File | Related Code |
|
||||
|----------|--------------|
|
||||
| README.md | All files in same directory |
|
||||
| API.md | src/api/**/* |
|
||||
| CLAUDE.md | Configuration files, scripts |
|
||||
| docs/module.md | src/module/**/* |
|
||||
| Component.md | Component.tsx, Component.css |
|
||||
Execute `skills/staleness-metrics.md` - build relationships
|
||||
|
||||
2. **Analyze Commit History**
|
||||
For each doc file:
|
||||
@@ -38,118 +31,22 @@ Then proceed with the check.
|
||||
- Count commits to code since doc was updated
|
||||
|
||||
3. **Calculate Staleness**
|
||||
```
|
||||
Commits Behind = Code Commits Since Doc Update
|
||||
Days Behind = Days Since Doc Update - Days Since Code Update
|
||||
```
|
||||
Use levels from skill (Fresh/Aging/Stale/Critical)
|
||||
|
||||
4. **Apply Threshold**
|
||||
Default: Flag if documentation is 10+ commits behind related code
|
||||
|
||||
**Staleness Levels:**
|
||||
| Commits Behind | Level | Action |
|
||||
|----------------|-------|--------|
|
||||
| 0-5 | Fresh | No action needed |
|
||||
| 6-10 | Aging | Review recommended |
|
||||
| 11-20 | Stale | Update needed |
|
||||
| 20+ | Critical | Immediate attention |
|
||||
|
||||
5. **Output Format**
|
||||
```
|
||||
## Stale Documentation Report
|
||||
|
||||
### Critical (20+ commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| docs/api.md | 2024-01-15 | 34 | src/api/**/* |
|
||||
|
||||
### Stale (11-20 commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| README.md | 2024-02-20 | 15 | package.json, src/index.ts |
|
||||
|
||||
### Aging (6-10 commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| CONTRIBUTING.md | 2024-03-01 | 8 | .github/*, scripts/* |
|
||||
|
||||
### Summary
|
||||
- Critical: 1 file
|
||||
- Stale: 1 file
|
||||
- Aging: 1 file
|
||||
- Fresh: 12 files
|
||||
- Total documentation files: 15
|
||||
```
|
||||
4. **Output**
|
||||
Use format from `skills/staleness-metrics.md`
|
||||
|
||||
## Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--threshold <n>` | Commits behind to flag as stale | 10 |
|
||||
| `--days` | Use days instead of commits | false |
|
||||
| `--path <dir>` | Scan specific directory | Project root |
|
||||
| `--doc-pattern <glob>` | Pattern for doc files | `**/*.md,**/README*` |
|
||||
| `--ignore <glob>` | Ignore specific docs | `CHANGELOG.md,LICENSE` |
|
||||
| `--show-fresh` | Include fresh docs in output | false |
|
||||
| `--format <fmt>` | Output format (table, json) | table |
|
||||
|
||||
## Relationship Detection
|
||||
|
||||
How docs are mapped to code:
|
||||
|
||||
1. **Same Directory**
|
||||
- `src/api/README.md` relates to `src/api/**/*`
|
||||
|
||||
2. **Name Matching**
|
||||
- `docs/auth.md` relates to `**/auth.*`, `**/auth/**`
|
||||
|
||||
3. **Explicit Links**
|
||||
- Parse `[link](path)` in docs to find related files
|
||||
|
||||
4. **Import Analysis**
|
||||
- Track which modules are referenced in code examples
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `.doc-guardian.yml` to customize mappings:
|
||||
```yaml
|
||||
stale-docs:
|
||||
threshold: 10
|
||||
mappings:
|
||||
- doc: docs/deployment.md
|
||||
code:
|
||||
- Dockerfile
|
||||
- docker-compose.yml
|
||||
- .github/workflows/deploy.yml
|
||||
- doc: ARCHITECTURE.md
|
||||
code:
|
||||
- src/**/*
|
||||
ignore:
|
||||
- CHANGELOG.md
|
||||
- LICENSE
|
||||
- vendor/**
|
||||
```
|
||||
|
||||
## Example Usage
|
||||
|
||||
```
|
||||
/stale-docs
|
||||
/stale-docs --threshold 5
|
||||
/stale-docs --days --threshold 30
|
||||
/stale-docs --path docs/ --show-fresh
|
||||
```
|
||||
|
||||
## Integration with doc-audit
|
||||
|
||||
`/stale-docs` focuses specifically on commit-based staleness, while `/doc-audit` checks content accuracy. Use both for comprehensive documentation health:
|
||||
|
||||
```
|
||||
/doc-audit # Check for broken references and content drift
|
||||
/stale-docs # Check for files that may need review
|
||||
```
|
||||
| `--threshold <n>` | Commits behind to flag | 10 |
|
||||
| `--days` | Use days instead | false |
|
||||
| `--path <dir>` | Scan directory | Project root |
|
||||
| `--show-fresh` | Include fresh docs | false |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- 0: No critical or stale documentation
|
||||
- 1: Stale documentation found (useful for CI)
|
||||
- 2: Critical documentation found
|
||||
- 0: No critical or stale docs
|
||||
- 1: Stale docs found
|
||||
- 2: Critical docs found
|
||||
|
||||
121
plugins/doc-guardian/skills/changelog-format.md
Normal file
121
plugins/doc-guardian/skills/changelog-format.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
name: changelog-format
|
||||
description: Keep a Changelog format and Conventional Commits parsing
|
||||
---
|
||||
|
||||
# Changelog Format
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines Keep a Changelog format and how to parse Conventional Commits.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **changelog-gen**: Generating changelog entries from commits
|
||||
- **git-flow integration**: Validating commit message format
|
||||
|
||||
---
|
||||
|
||||
## Conventional Commits Pattern
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Type to Section Mapping
|
||||
|
||||
| Commit Type | Changelog Section |
|
||||
|-------------|------------------|
|
||||
| `feat` | Added |
|
||||
| `fix` | Fixed |
|
||||
| `docs` | Documentation |
|
||||
| `perf` | Performance |
|
||||
| `refactor` | Changed |
|
||||
| `style` | Changed |
|
||||
| `test` | Testing |
|
||||
| `build` | Build |
|
||||
| `ci` | CI/CD |
|
||||
| `chore` | Maintenance |
|
||||
| `BREAKING CHANGE` | Breaking Changes |
|
||||
|
||||
---
|
||||
|
||||
## Keep a Changelog Sections
|
||||
|
||||
Standard order (only include non-empty):
|
||||
1. Breaking Changes
|
||||
2. Added
|
||||
3. Changed
|
||||
4. Deprecated
|
||||
5. Removed
|
||||
6. Fixed
|
||||
7. Security
|
||||
|
||||
---
|
||||
|
||||
## Breaking Changes Detection
|
||||
|
||||
Detected by:
|
||||
- `!` suffix on type: `feat!: new auth system`
|
||||
- `BREAKING CHANGE` in footer
|
||||
- `BREAKING-CHANGE` in footer
|
||||
|
||||
---
|
||||
|
||||
## Entry Formatting
|
||||
|
||||
For each commit:
|
||||
1. Extract scope (if present) as bold prefix: `**scope**: `
|
||||
2. Use description as entry text
|
||||
3. Link to commit hash if repository URL available
|
||||
4. Include PR/issue references from footer
|
||||
|
||||
### Example Output
|
||||
|
||||
```markdown
|
||||
## [Unreleased]
|
||||
|
||||
### Breaking Changes
|
||||
- **auth**: Remove deprecated OAuth1 support
|
||||
|
||||
### Added
|
||||
- **api**: New batch processing endpoint
|
||||
- User preference saving feature
|
||||
|
||||
### Changed
|
||||
- **core**: Improve error message clarity
|
||||
|
||||
### Fixed
|
||||
- **api**: Handle null values in response
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Non-Conventional Handling
|
||||
|
||||
Commits not following format:
|
||||
- List under "Other" section
|
||||
- Flag for manual categorization
|
||||
- Skip if `--strict` flag used
|
||||
|
||||
---
|
||||
|
||||
## Commit Range Detection
|
||||
|
||||
1. Default: commits since last tag
|
||||
2. First release: all commits from initial
|
||||
3. Explicit: `--from <tag> --to <ref>`
|
||||
|
||||
```bash
|
||||
# Find last tag
|
||||
git describe --tags --abbrev=0
|
||||
|
||||
# Commits since tag
|
||||
git log v1.0.0..HEAD --oneline
|
||||
```
|
||||
131
plugins/doc-guardian/skills/coverage-calculation.md
Normal file
131
plugins/doc-guardian/skills/coverage-calculation.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
name: coverage-calculation
|
||||
description: Documentation coverage metrics, language patterns, and thresholds
|
||||
---
|
||||
|
||||
# Coverage Calculation
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines how to calculate documentation coverage and thresholds.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **doc-coverage**: Full coverage analysis
|
||||
- **doc-audit**: Completeness checks
|
||||
|
||||
---
|
||||
|
||||
## Coverage Formula
|
||||
|
||||
```
|
||||
Coverage = (Documented Items / Total Items) * 100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Documentable Items by Language
|
||||
|
||||
### Python
|
||||
- Functions (`def`)
|
||||
- Classes
|
||||
- Methods
|
||||
- Module-level docstrings
|
||||
|
||||
### JavaScript/TypeScript
|
||||
- Functions (`function`, arrow functions)
|
||||
- Classes
|
||||
- Methods
|
||||
- JSDoc comments (`/** */`)
|
||||
|
||||
### Go
|
||||
- Functions
|
||||
- Types
|
||||
- Methods
|
||||
- Package comments (`//` above declaration)
|
||||
|
||||
### Rust
|
||||
- Functions
|
||||
- Structs/Enums
|
||||
- Impl blocks
|
||||
- Doc comments (`///`)
|
||||
|
||||
---
|
||||
|
||||
## Language Detection
|
||||
|
||||
| Extension | Language | Doc Format |
|
||||
|-----------|----------|------------|
|
||||
| .py | Python | Docstrings (`"""`) |
|
||||
| .js, .ts | JavaScript/TypeScript | JSDoc (`/** */`) |
|
||||
| .go | Go | `//` comments above |
|
||||
| .rs | Rust | `///` doc comments |
|
||||
| .rb | Ruby | `#` comments, YARD |
|
||||
| .java | Java | Javadoc (`/** */`) |
|
||||
|
||||
---
|
||||
|
||||
## Coverage Levels
|
||||
|
||||
### Basic
|
||||
- Item has any docstring/comment
|
||||
- Not empty or placeholder
|
||||
|
||||
### Standard
|
||||
- Docstring describes purpose
|
||||
- Non-trivial content (not just `pass` or `TODO`)
|
||||
|
||||
### Complete
|
||||
- All parameters documented
|
||||
- Return type documented
|
||||
- Raises/throws documented
|
||||
|
||||
---
|
||||
|
||||
## Coverage Thresholds
|
||||
|
||||
| Level | Coverage | Description |
|
||||
|-------|----------|-------------|
|
||||
| Minimal | 60% | Basic documentation exists |
|
||||
| Good | 80% | Most public APIs documented |
|
||||
| Excellent | 95% | Comprehensive documentation |
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Documentation Coverage Report
|
||||
|
||||
### Summary
|
||||
- Total documentable items: 156
|
||||
- Documented: 142
|
||||
- Coverage: 91.0%
|
||||
|
||||
### By Type
|
||||
| Type | Total | Documented | Coverage |
|
||||
|------|-------|------------|----------|
|
||||
| Functions | 89 | 85 | 95.5% |
|
||||
| Classes | 23 | 21 | 91.3% |
|
||||
| Methods | 44 | 36 | 81.8% |
|
||||
|
||||
### By Directory
|
||||
| Path | Total | Documented | Coverage |
|
||||
|------|-------|------------|----------|
|
||||
| src/api/ | 34 | 32 | 94.1% |
|
||||
| src/utils/ | 28 | 28 | 100.0% |
|
||||
|
||||
### Undocumented Items
|
||||
- [ ] src/api/handlers.py:45 `create_order()`
|
||||
- [ ] src/models/user.py:23 `UserModel.validate()`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exclusion Patterns
|
||||
|
||||
Default exclusions:
|
||||
- `**/test_*` - Test files
|
||||
- `**/*_test.*` - Test files
|
||||
- Private members (`_prefixed`) unless `--include-private`
|
||||
- Generated code (`**/generated/**`)
|
||||
67
plugins/doc-guardian/skills/doc-patterns.md
Normal file
67
plugins/doc-guardian/skills/doc-patterns.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: doc-patterns
|
||||
description: Common documentation structures and patterns
|
||||
---
|
||||
|
||||
# Documentation Patterns
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines common documentation file structures and their contents.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **doc-audit**: Understanding what to check in each doc type
|
||||
- **doc-coverage**: Identifying documentation locations
|
||||
|
||||
---
|
||||
|
||||
## README.md Patterns
|
||||
|
||||
Typical sections:
|
||||
- **Installation**: Version requirements, dependencies
|
||||
- **Usage**: Function calls, CLI commands
|
||||
- **Configuration**: Environment vars, config files
|
||||
- **API**: Endpoint references
|
||||
|
||||
---
|
||||
|
||||
## CLAUDE.md Patterns
|
||||
|
||||
Typical sections:
|
||||
- **Project Context**: Tech stack versions
|
||||
- **File Structure**: Directory layout
|
||||
- **Commands**: Available operations
|
||||
- **Workflows**: Process descriptions
|
||||
|
||||
---
|
||||
|
||||
## Code Documentation
|
||||
|
||||
### Docstrings
|
||||
- Function signatures
|
||||
- Parameters and types
|
||||
- Return values
|
||||
- Raised exceptions
|
||||
|
||||
### Type Hints
|
||||
- Should match docstring types
|
||||
- Verify consistency
|
||||
|
||||
### Inline Comments
|
||||
- References to other code
|
||||
- TODO markers
|
||||
- Warning notes
|
||||
|
||||
---
|
||||
|
||||
## File Inventory
|
||||
|
||||
Standard documentation files to check:
|
||||
- `README.md` (root and subdirectories)
|
||||
- `CLAUDE.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `CHANGELOG.md`
|
||||
- `docs/**/*.md`
|
||||
- API documentation
|
||||
- Configuration references
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
description: Knowledge of documentation patterns and structures for drift detection
|
||||
---
|
||||
|
||||
# Documentation Patterns Skill
|
||||
|
||||
## Common Documentation Structures
|
||||
|
||||
### README.md Patterns
|
||||
- Installation section: version requirements, dependencies
|
||||
- Usage section: function calls, CLI commands
|
||||
- Configuration section: env vars, config files
|
||||
- API section: endpoint references
|
||||
|
||||
### CLAUDE.md Patterns
|
||||
- Project context: tech stack versions
|
||||
- File structure: directory layout
|
||||
- Commands: available operations
|
||||
- Workflows: process descriptions
|
||||
|
||||
### Code Documentation
|
||||
- Docstrings: function signatures, parameters, returns
|
||||
- Type hints: should match docstring types
|
||||
- Comments: inline references to other code
|
||||
|
||||
## Drift Detection Rules
|
||||
|
||||
1. **Version Mismatch**: Any hardcoded version in docs must match package.json, pyproject.toml, requirements.txt
|
||||
2. **Function References**: Function names in docs must exist in codebase with matching signatures
|
||||
3. **Path References**: File paths in docs must exist in current directory structure
|
||||
4. **Config Keys**: Environment variables and config keys in docs must be used in code
|
||||
5. **Command Examples**: CLI examples in docs should be valid commands
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **P0 (Critical)**: Broken references that would cause user errors
|
||||
- **P1 (High)**: Outdated information that misleads users
|
||||
- **P2 (Medium)**: Missing documentation for public interfaces
|
||||
- **P3 (Low)**: Style inconsistencies, minor wording issues
|
||||
102
plugins/doc-guardian/skills/drift-detection.md
Normal file
102
plugins/doc-guardian/skills/drift-detection.md
Normal file
@@ -0,0 +1,102 @@
|
||||
---
|
||||
name: drift-detection
|
||||
description: Core drift detection rules, cross-reference analysis, and priority levels
|
||||
---
|
||||
|
||||
# Drift Detection
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines how to detect documentation drift through cross-reference analysis.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **doc-audit**: Full cross-reference analysis
|
||||
- **stale-docs**: Commit-based staleness detection
|
||||
- **SessionStart hook**: Real-time drift detection
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference Analysis
|
||||
|
||||
For each documentation file:
|
||||
1. Extract referenced functions, classes, endpoints, configs
|
||||
2. Verify each reference exists in codebase
|
||||
3. Check signatures/types match documentation
|
||||
4. Flag deprecated or renamed items still in docs
|
||||
|
||||
---
|
||||
|
||||
## Drift Detection Rules
|
||||
|
||||
| Rule | Check | Priority |
|
||||
|------|-------|----------|
|
||||
| Version Mismatch | Hardcoded versions must match package.json, pyproject.toml, requirements.txt | P0 |
|
||||
| Function References | Function names must exist with matching signatures | P0 |
|
||||
| Path References | File paths must exist in directory structure | P0 |
|
||||
| Config Keys | Env vars and config keys must be used in code | P1 |
|
||||
| Command Examples | CLI examples must be valid commands | P1 |
|
||||
|
||||
---
|
||||
|
||||
## Priority Levels
|
||||
|
||||
| Level | Description | Action |
|
||||
|-------|-------------|--------|
|
||||
| **P0 (Critical)** | Broken references causing user errors | Immediate fix |
|
||||
| **P1 (High)** | Outdated information misleading users | Fix in current session |
|
||||
| **P2 (Medium)** | Missing documentation for public interfaces | Add to backlog |
|
||||
| **P3 (Low)** | Style inconsistencies, minor wording | Optional |
|
||||
|
||||
---
|
||||
|
||||
## Drift Categories
|
||||
|
||||
### Critical (Broken References)
|
||||
- Function/class renamed but docs not updated
|
||||
- File moved/deleted but docs still reference old path
|
||||
- API endpoint changed but docs show old URL
|
||||
|
||||
### Stale (Outdated Info)
|
||||
- Version numbers not matching actual
|
||||
- Configuration examples using deprecated keys
|
||||
- Screenshots of old UI
|
||||
|
||||
### Missing (Undocumented)
|
||||
- Public functions without docstrings
|
||||
- New features not in README
|
||||
- Environment variables used but not documented
|
||||
|
||||
---
|
||||
|
||||
## Documentation File Mapping
|
||||
|
||||
| Doc File | Related Code |
|
||||
|----------|--------------|
|
||||
| README.md | All files in same directory |
|
||||
| API.md | src/api/**/* |
|
||||
| CLAUDE.md | Configuration files, scripts |
|
||||
| docs/module.md | src/module/**/* |
|
||||
| Component.md | Component.tsx, Component.css |
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Documentation Drift Report
|
||||
|
||||
### Critical (Broken References)
|
||||
- [ ] README.md:45 references `calculate_total()` - function renamed to `compute_total()`
|
||||
|
||||
### Stale (Outdated Info)
|
||||
- [ ] CLAUDE.md:23 lists Python 3.9 - project uses 3.11
|
||||
|
||||
### Missing (Undocumented)
|
||||
- [ ] api/handlers.py:`create_order()` - no docstring
|
||||
|
||||
### Summary
|
||||
- Critical: X items
|
||||
- Stale: X items
|
||||
- Missing: X items
|
||||
```
|
||||
127
plugins/doc-guardian/skills/staleness-metrics.md
Normal file
127
plugins/doc-guardian/skills/staleness-metrics.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: staleness-metrics
|
||||
description: Documentation staleness levels, thresholds, and relationship detection
|
||||
---
|
||||
|
||||
# Staleness Metrics
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines how to measure documentation staleness relative to code changes.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **stale-docs**: Commit-based staleness detection
|
||||
- **doc-audit**: Age-based analysis
|
||||
|
||||
---
|
||||
|
||||
## Staleness Calculation
|
||||
|
||||
```
|
||||
Commits Behind = Code Commits Since Doc Update
|
||||
Days Behind = Days Since Doc Update - Days Since Code Update
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Staleness Levels
|
||||
|
||||
| Commits Behind | Level | Action |
|
||||
|----------------|-------|--------|
|
||||
| 0-5 | Fresh | No action needed |
|
||||
| 6-10 | Aging | Review recommended |
|
||||
| 11-20 | Stale | Update needed |
|
||||
| 20+ | Critical | Immediate attention |
|
||||
|
||||
---
|
||||
|
||||
## Relationship Detection
|
||||
|
||||
### 1. Same Directory
|
||||
`src/api/README.md` relates to `src/api/**/*`
|
||||
|
||||
### 2. Name Matching
|
||||
`docs/auth.md` relates to `**/auth.*`, `**/auth/**`
|
||||
|
||||
### 3. Explicit Links
|
||||
Parse `[link](path)` in docs to find related files
|
||||
|
||||
### 4. Import Analysis
|
||||
Track which modules are referenced in code examples
|
||||
|
||||
---
|
||||
|
||||
## Git Commands
|
||||
|
||||
```bash
|
||||
# Last doc commit
|
||||
git log -1 --format="%H %ai" -- docs/api.md
|
||||
|
||||
# Last code commit for related files
|
||||
git log -1 --format="%H %ai" -- src/api/
|
||||
|
||||
# Commits to code since doc update
|
||||
git rev-list <doc-commit>..HEAD -- src/api/ | wc -l
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
`.doc-guardian.yml`:
|
||||
```yaml
|
||||
stale-docs:
|
||||
threshold: 10
|
||||
mappings:
|
||||
- doc: docs/deployment.md
|
||||
code:
|
||||
- Dockerfile
|
||||
- docker-compose.yml
|
||||
- .github/workflows/deploy.yml
|
||||
- doc: ARCHITECTURE.md
|
||||
code:
|
||||
- src/**/*
|
||||
ignore:
|
||||
- CHANGELOG.md
|
||||
- LICENSE
|
||||
- vendor/**
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Stale Documentation Report
|
||||
|
||||
### Critical (20+ commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| docs/api.md | 2024-01-15 | 34 | src/api/**/* |
|
||||
|
||||
### Stale (11-20 commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| README.md | 2024-02-20 | 15 | package.json, src/index.ts |
|
||||
|
||||
### Aging (6-10 commits behind)
|
||||
| File | Last Updated | Commits Behind | Related Code |
|
||||
|------|--------------|----------------|--------------|
|
||||
| CONTRIBUTING.md | 2024-03-01 | 8 | .github/*, scripts/* |
|
||||
|
||||
### Summary
|
||||
- Critical: 1 file
|
||||
- Stale: 1 file
|
||||
- Aging: 1 file
|
||||
- Fresh: 12 files
|
||||
- Total documentation files: 15
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- 0: No critical or stale documentation
|
||||
- 1: Stale documentation found (for CI)
|
||||
- 2: Critical documentation found
|
||||
109
plugins/doc-guardian/skills/sync-workflow.md
Normal file
109
plugins/doc-guardian/skills/sync-workflow.md
Normal file
@@ -0,0 +1,109 @@
|
||||
---
|
||||
name: sync-workflow
|
||||
description: Documentation synchronization process and queue management
|
||||
---
|
||||
|
||||
# Sync Workflow
|
||||
|
||||
## Purpose
|
||||
|
||||
Defines how to synchronize documentation with code changes.
|
||||
|
||||
## When to Use
|
||||
|
||||
- **doc-sync**: Apply pending documentation updates
|
||||
- **PostToolUse hook**: Queue drift for later sync
|
||||
|
||||
---
|
||||
|
||||
## Queue File
|
||||
|
||||
Location: `.doc-guardian-queue` in project root
|
||||
|
||||
Format:
|
||||
```
|
||||
# Doc Guardian Queue
|
||||
# Generated: YYYY-MM-DD HH:MM:SS
|
||||
|
||||
## Pending Updates
|
||||
- README.md:45 | reference | calculate_total -> compute_total
|
||||
- CLAUDE.md:23 | version | Python 3.9 -> 3.11
|
||||
- src/api/README.md:12 | path | old/path.py -> new/path.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Update Types
|
||||
|
||||
### Reference Fixes
|
||||
- Renamed function/class: update all doc references
|
||||
- Changed signature: update parameter documentation
|
||||
- Removed item: remove or mark deprecated in docs
|
||||
|
||||
### Content Sync
|
||||
- Version numbers (Python, Node, dependencies)
|
||||
- Configuration keys/values
|
||||
- File paths and directory structures
|
||||
- Command examples and outputs
|
||||
|
||||
### Structural
|
||||
- Add missing sections for new features
|
||||
- Remove sections for deleted features
|
||||
- Reorder to match current code organization
|
||||
|
||||
---
|
||||
|
||||
## Sync Process
|
||||
|
||||
1. **Review Queue**
|
||||
- Read `.doc-guardian-queue`
|
||||
- List all pending items
|
||||
|
||||
2. **Batch Updates**
|
||||
- Apply each update
|
||||
- Track in change list
|
||||
|
||||
3. **Commit Strategy**
|
||||
- Stage all doc changes together
|
||||
- Single commit: `docs: sync documentation with code changes`
|
||||
- Include summary in commit body
|
||||
|
||||
4. **Clear Queue**
|
||||
```bash
|
||||
echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
```
|
||||
## Documentation Sync Complete
|
||||
|
||||
### Files Updated
|
||||
- README.md (3 changes)
|
||||
- CLAUDE.md (1 change)
|
||||
- src/api/README.md (2 changes)
|
||||
|
||||
### Changes Applied
|
||||
- Updated function reference: calculate_total -> compute_total
|
||||
- Updated Python version: 3.9 -> 3.11
|
||||
- Added docstring to create_order()
|
||||
|
||||
Committed: abc123f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Queue Entry Format
|
||||
|
||||
```
|
||||
<file>:<line> | <type> | <old> -> <new>
|
||||
```
|
||||
|
||||
Types:
|
||||
- `reference` - Function/class name change
|
||||
- `version` - Version number update
|
||||
- `path` - File path change
|
||||
- `config` - Configuration key/value
|
||||
- `missing` - New documentation needed
|
||||
Reference in New Issue
Block a user