personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: extract skills from commands across 8 plugins

Browse Source 
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:
Leo Miranda
2026-01-30 17:32:24 -05:00
parent aad02ef2d9
commit 7c8a20c804
71 changed files with 3896 additions and 3690 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
plugins/doc-guardian/commands/changelog-gen.md
View File

@@ -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

47
plugins/doc-guardian/commands/doc-audit.md
View File

@@ -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

128
plugins/doc-guardian/commands/doc-coverage.md
View File

@@ -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 (/** */) |

64
plugins/doc-guardian/commands/doc-sync.md
View File

@@ -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`

141
plugins/doc-guardian/commands/stale-docs.md
View File

@@ -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