zhongwei/gh-bradleyboehmke-brads-marketplace-document-generator
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-29 18:01:55 +08:00
commit 60782a2f51
22 changed files with 5228 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
commands/generate-adr.md Normal file
View File

@@ -0,0 +1,186 @@
---
description: Create an Architecture Decision Record (ADR) following MADR format
---
# Generate ADR
## Activated Agent
**Activate**: `adr-author` agent
The agent will help create a structured ADR document.
## Objective
Create an Architecture Decision Record (ADR) that documents an architectural decision with context, alternatives, and consequences following the MADR (Markdown Any Decision Record) format.
## Prerequisites
This command requires the **repo-investigator** plugin to be installed for codebase analysis capabilities.
If you haven't installed it yet:
```bash
claude plugin install repo-investigator@brads-marketplace
```
## Activated Skills
The agent will activate these skills:
1. **`adr-authoring`** (document-generator) - MADR template and ADR best practices
2. **`repository-analysis-methods`** (repo-investigator) - Understanding project architecture for context
## Process
**Before starting**, verify the repo-investigator plugin is available:
1. Check if `repo-investigator` skills are accessible
2. If `repository-analysis-methods` skill is not available:
- Display a clear message to the user:
```
⚠️ Missing Dependency: repo-investigator plugin
The generate-adr command requires the repo-investigator plugin for codebase analysis.
Please install it:
claude plugin install repo-investigator@brads-marketplace
Then re-run this command.
```
- Stop execution and wait for user to install the plugin
The agent will:
1. **Choose Workflow** - Ask user to select their preferred approach:
- **Guided Interview**: Step-by-step questions with interactive clarification
- **Comprehensive Input**: Provide all information at once
### Guided Interview Workflow
If user selects guided interview, ask questions one at a time or in small groups:
1. What architectural decision needs to be documented?
2. When was this decision made?
3. What problem does it solve?
4. What alternatives were considered?
5. What is the current status?
6. What are the consequences (positive and negative)?
### Comprehensive Input Workflow
If user selects comprehensive input, present this summary of required information:
```
Please provide the following information about your architectural decision:
**Required:**
- Decision title and brief description
- Problem/context that prompted this decision
- Chosen solution/approach
**Recommended:**
- Date of decision (defaults to today if not provided)
- Alternatives that were considered and why they were rejected
- Positive consequences/benefits
- Negative consequences/trade-offs
- Decision drivers (key factors influencing the choice)
- Current status (Proposed/Accepted/Deprecated/Superseded)
You can provide this in any format - bullet points, paragraphs, or structured sections.
```
Then extract information from the user's response and ask targeted follow-up questions only for critical missing pieces.
### Common Steps (Both Workflows)
2. **Analyze** - Examine the codebase to understand:
- Current architecture and components
- Affected files and modules
- Existing ADRs (for numbering)
3. **Generate** - Create ADR document with:
- Sequential ADR number
- MADR-compliant structure
- Evidence-based context
- Clear decision statement
- Documented alternatives
- Positive and negative consequences
4. **Provide guidance** - Suggest:
- Filename: `adr/ADR-XXX-title-in-kebab-case.md`
- Where to store the file
- How to update status over time
## Output Format
Generate an ADR following this MADR template:
```markdown
# ADR-XXX: [Decision Title]
Date: YYYY-MM-DD
## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-YYY]
## Context
[Problem description, requirements, constraints]
## Decision Drivers
* [Factor 1]
* [Factor 2]
* [Factor 3]
## Considered Options
* [Option 1 - chosen]
* [Option 2]
* [Option 3]
## Decision Outcome
Chosen option: "[Option 1]", because [justification].
### Positive Consequences
* [Benefit 1]
* [Benefit 2]
### Negative Consequences
* [Challenge 1]
* [Challenge 2]
## Pros and Cons of the Options
### [Option 1]
* Good, because [argument a]
* Bad, because [argument b]
### [Option 2]
* Good, because [argument a]
* Bad, because [argument b]
## Links
* [Related ADR or documentation]
```
## Constraints
- **Evidence-based**: Reference actual code and file paths
- **Balanced**: Present alternatives fairly
- **Focused**: One decision per ADR
- **No speculation**: Ask for missing information
- **Sequential numbering**: Check existing ADRs to determine next number
## Storage Location
Default location: `adr/ADR-XXX-title-in-kebab-case.md`
If `adr/` doesn't exist, create it.

132
commands/generate-architecture-diagram.md Normal file
View File

@@ -0,0 +1,132 @@
---
description: Create Mermaid architecture diagrams for visualizing system structure and data flow
---
# Generate Architecture Diagram
## Activated Agent
**Activate**: `mermaid-expert` agent
The agent will create appropriate Mermaid diagrams based on what needs visualization.
## Objective
Create clear, accurate Mermaid diagrams to visualize software architecture, data flow, system interactions, or other technical concepts.
## Activated Skills
The agent will activate these skills:
1. **`mermaid-diagramming`** - Mermaid syntax and diagram types
2. **`diagram-analysis`** - Understanding what to visualize and choosing diagram type
## Process
The agent will:
1. **Understand the need** - Ask:
- What do you want to visualize?
- Who is the audience?
- What level of detail?
- Any preferred diagram type?
- **Output destination**: Insert into existing file or create standalone?
2. **Analyze the system** - Examine:
- Project structure and architecture
- Components and services
- Data flow and interactions
- Technologies in use
3. **Choose diagram type** - Select from:
- C4 Context (system in environment)
- C4 Container (services and tech)
- Flowchart (processes, algorithms)
- Sequence (interactions over time)
- ER Diagram (data models)
- Class (OOP structure)
- State (entity lifecycles)
4. **Generate diagram** - Create:
- Valid Mermaid syntax (basic and styled versions)
- Clear labels and relationships
- Appropriate level of detail
- Focused scope
5. **Output diagram**:
- **If standalone**: Create new .md file at specified location
- **If insertion**: Read target file, insert diagram at specified location (line number or after section heading)
6. **Provide usage** - Explain:
- How to embed in other documents
- How to render/preview (GitHub, VS Code, mkdocs)
- Suggested customizations
## Diagram Type Selection
| Type | Use For | Example |
|------|---------|---------|
| **C4 Context** | System overview | "How does our platform fit in the ecosystem?" |
| **C4 Container** | Service architecture | "What are our main services?" |
| **Flowchart** | Processes | "How does training work?" |
| **Sequence** | API interactions | "What happens during request?" |
| **ER Diagram** | Data models | "Database schema?" |
| **Class** | OOP design | "Class hierarchy?" |
| **State** | Lifecycles | "Deployment states?" |
## Output Format
Provide:
1. **Diagram code** - Complete Mermaid syntax
2. **Explanation** - What the diagram shows
3. **Usage instructions** - How to use/render it
4. **Storage suggestion** - Where to save
Example output:
````markdown
Here's a C4 Container diagram showing your ML platform architecture:
```mermaid
C4Container
title ML Platform Architecture
Person(ds, "Data Scientist", "Trains models")
Container(api, "API Service", "FastAPI", "Model serving")
Container(training, "Training Service", "Python", "Model training")
ContainerDb(db, "Model Registry", "PostgreSQL", "Model metadata")
Rel(ds, training, "Submits jobs", "CLI")
Rel(training, db, "Stores models")
Rel(api, db, "Loads models")
```
**To use this diagram:**
- Embed in Markdown files (GitHub will render it)
- Preview in VS Code with Mermaid extension
- Save to `docs/architecture/platform-overview.md`
````
## Constraints
- **Valid syntax**: Ensure Mermaid renders correctly
- **Evidence-based**: Reflect actual architecture
- **Focused scope**: One concern per diagram
- **No sensitive data**: Exclude credentials, IPs
- **Clear labels**: Use descriptive names
## Output Options
**Standalone file**:
- Create new .md file with diagram
- Default location: `docs/architecture/[diagram-name].md`
- File renders in GitHub automatically
**Insert into existing file**:
- Ask for file path to insert into
- Ask for insertion point (line number or section heading like "## Architecture")
- Read file first to understand context
- Insert diagram at specified location
- Preserve existing content

200
commands/generate-changelog.md Normal file
View File

@@ -0,0 +1,200 @@
---
description: Create a new CHANGELOG.md file from scratch for a project
---
# Generate Changelog
## Objective
Create a new CHANGELOG.md file following standards (Keep a Changelog format) with entries inferred from git history, supporting both semantic and calendar versioning.
## Activated Skills
1. **`changelog-standards`** (document-generator) - changelog format and structure
2. **`version-validation`** (document-generator) - Versioning rules and validation
3. **`git-history-analysis`** (document-generator) - Git commit parsing patterns
## Parameters
- `--version-type` (optional): `semantic` (default) or `calendar`
- `--format` (optional): `single-file` (default, CHANGELOG.md) or `yearly` (docs/changelog/YYYY.md)
- `--style` (optional): `standard` (default, Keep a Changelog) or `detailed` (Highlights + Technical Details)
- `--path` (optional): Custom changelog location (e.g., `docs/CHANGELOG.md`, `CHANGELOG.md`)
- `--initial-version` (optional): Starting version (default: 0.1.0 for semantic, YYYY.1 for calendar)
- `--tier` (optional): Prototype, MVP, Production
## Process
### 1. Pre-flight Checks
Determine changelog location:
- If `--path` specified: Use that location
- If `--format=yearly`: Use `docs/changelog/YYYY.md`
- Otherwise: Use `CHANGELOG.md` (default)
Check if changelog already exists at target location.
If exists:
```
⚠️ CHANGELOG.md already exists
What would you like to do?
1. Skip - keep existing changelog
2. Backup and regenerate
3. Use /document-generator:update-changelog instead
```
### 2. Detect Version Type
Auto-detect from git tags, `pyproject.toml`, or `package.json`:
- Versions matching `YYYY.N` pattern → CalVer
- Versions matching `X.Y.Z` pattern → SemVer
- `--version-type` parameter → Override
- Default → SemVer
### 3. Analyze Git History
Retrieve all commits from initial commit to HEAD:
```bash
git log --no-merges --pretty=format:"%h|%s|%ad" --date=short
```
Parse commit messages (conventional commits or keyword-based), filter noise, categorize into sections, group related commits, and rephrase in user-facing language.
**Extract PR/issue numbers**: Look for `(#123)`, `#123`, or PR references in commit messages to link entries to GitHub.
### 4. Determine Initial Version
**If `--initial-version` specified**: Use that
**Otherwise**:
- SemVer: Start with `0.1.0` (pre-release) or `1.0.0` (if mature)
- CalVer: Use current year and `.1` (e.g., `2025.1`)
**Ask user if unclear**:
```
What initial version should I use?
1. 0.1.0 (pre-release/prototype)
2. 1.0.0 (stable first release)
3. Custom version
```
### 5. Generate CHANGELOG.md
Choose format based on `--style` parameter:
**Standard style** (default):
```markdown
## [VERSION] - YYYY-MM-DD [TIER]
### Added
- Feature description (#PR)
### Changed
- Change description (#PR)
### Fixed
- Bug fix (#PR)
```
**Detailed style**:
```markdown
## [VERSION] - YYYY-MM-DD [TIER]
### Highlights
- Major feature or improvement (executive summary)
- Critical fix or update
### Detailed Notes
#### Added
- Feature description with technical context (#PR)
- Sub-detail 1
- Sub-detail 2
#### Changed
- Change description with rationale (#PR)
#### Fixed
- Bug fix with context (#PR)
```
Include PR/issue links where available from commit messages.
### 6. Write File
Write to determined location:
- `--path` specified: Write to custom path
- `--format=yearly`: Create `docs/changelog/` if needed, write to `docs/changelog/YYYY.md`
- Default: Write to `CHANGELOG.md` in project root
Create parent directories if they don't exist.
### 7. Provide Guidance
```
✓ Created CHANGELOG.md with initial version VERSION
File location: [path]
Version type: [SemVer/CalVer]
Tier: [tier if specified]
Next steps:
1. Review generated entries for accuracy
2. Add any missing user-facing changes
3. Commit the changelog: git add CHANGELOG.md
4. Tag the release: git tag vVERSION
5. Use /document-generator:update-changelog for future updates
```
## Output Format
**Console** (default): Display summary and next steps
**Markdown** (if `--output` specified): Save changelog as markdown file
## Constraints
- Token budget: Keep command concise, delegate to skills
- One changelog per project (single source of truth)
- Focus on user-facing changes only
- No speculation - use actual git history
- Validate version format using `version-validation` skill
## Examples
**Basic usage**:
```bash
/document-generator:generate-changelog
→ Creates CHANGELOG.md with SemVer, starting at 0.1.0
```
**Calendar versioning**:
```bash
/document-generator:generate-changelog --version-type=calendar
→ Creates CHANGELOG.md with CalVer (2025.1)
```
**With tier annotation**:
```bash
/document-generator:generate-changelog --initial-version=1.0.0 --tier=MVP
→ Creates CHANGELOG.md starting at [1.0.0] [MVP]
```
**Yearly format**:
```bash
/document-generator:generate-changelog --format=yearly
→ Creates docs/changelog/2025.md
```
**Custom location**:
```bash
/document-generator:generate-changelog --path=docs/CHANGELOG.md
→ Creates docs/CHANGELOG.md
```
**Detailed style with highlights**:
```bash
/document-generator:generate-changelog --style=detailed
→ Creates CHANGELOG.md with Highlights + Detailed Notes sections
```

236
commands/generate-readme.md Normal file
View File

@@ -0,0 +1,236 @@
---
description: Create a new README.md from scratch for projects without one
---
# Generate README
## Activated Agent
**Activate**: `readme-author` agent
The agent will help create a minimal, standards-compliant README for your project.
## Objective
Create a new README.md following the Personal minimal 8-section structure with business context integration and link-first approach.
## Command Parameters
| Parameter | Options | Default | Description |
|-----------|---------|---------|-------------|
| `--tier` | `prototype`, `mvp`, `production` | Auto-detect | Project maturity tier |
| `--format` | `console`, `markdown` | `console` | Output format (console display vs. file) |
| `--output` | `<path>` | `./README.md` | Custom output path (requires `--format=markdown`) |
| `--interactive` | `true`, `false` | `true` | Prompt for approval before writing |
**Examples:**
```bash
/document-generator:generate-readme # Interactive, auto-detect tier, console display
/document-generator:generate-readme --tier=mvp --format=markdown
/document-generator:generate-readme --output=./docs/README.md --format=markdown --interactive=false
```
## Activated Skills
The agent will activate these skills:
1. **`readme-authoring`** - 8-section templates and generation patterns
2. **`readme-standards`** - minimal README validation criteria
## Process
The agent will follow this workflow:
### 1. Pre-flight Checks
**Check if README.md already exists**:
- If `README.md` exists in current directory:
```
⚠️ README.md already exists in this directory.
Use `/document-generator:update-readme` to refactor an existing README.
Do you want to:
1. Overwrite the existing README (⚠️ this will replace current content)
2. Cancel and use update-readme instead
3. Generate to a different path
Enter choice (1-3):
```
- If user chooses overwrite: Proceed with generation
- If user chooses cancel: Stop execution, suggest `/document-generator:update-readme`
- If user chooses different path: Prompt for new output path
### 2. Detect Project Tier
Agent will detect project tier (Prototype/MVP/Production) from codebase signals (if not specified via `--tier`). Display detected tier and allow user override if needed.
### 3. Extract Project Metadata
Agent will extract project name, version, and description from language-specific project files. If extraction fails, prompt user for required information.
### 4. Extract Business Context
Agent searches for business problem/solution in existing docs, module docstrings, and code comments. If not found, prompts user for business context (problem + solution). See `readme-authoring` skill "Context Extraction Patterns" for details.
### 5. Discover Existing Documentation
Agent scans for documentation to link (architecture, ADRs, setup guides, CONTRIBUTING.md). See `readme-authoring` skill "Documentation discovery" section for paths.
### 6. Generate 8-Section README
Generate content for all 8 sections using `readme-authoring` skill "Section Generation Reference" table:
- Title & One-Liner, Badges (tier-based), Description (with business context)
- Installation (simple command + setup link), Documentation (discovered links only)
- Supporting Components (optional), Contributing, Bugs & Enhancements
See `readme-authoring` skill for detailed generation patterns per section.
### 7. Present Draft (Interactive Mode)
If `--interactive=true` (default), show generated README to user:
```
📄 Generated README.md:
==================================================
# {Project Name}
{Generated content...}
==================================================
Sections included:
✓ Title & One-Liner
✓ Badges (MVP tier)
✓ Short Description (with business context)
✓ Installation
✓ Documentation (3 links)
✓ Contributing
✓ Bugs & Enhancements
Does this look good? (y/n/edit):
- y: Write to file
- n: Cancel generation
- edit: Modify specific sections
```
**If user chooses "edit"**:
```
Which section would you like to modify?
1. Title & One-Liner
2. Badges
3. Short Description
4. Installation
5. Documentation
6. Contributing
7. Bugs & Enhancements
Enter number (or 'done' to finish):
```
Allow user to provide replacement content for selected sections, then re-present draft.
### 8. Write README File
**Write to output path** (default: `./README.md`):
```bash
# Create README.md
cat > ./README.md <<'EOF'
{generated content}
EOF
```
**Confirm success**:
```
✓ README.md created successfully at ./README.md
Next steps:
- Review the README and adjust as needed
- Run `/document-generator:validate-readme` to check compliance
- Consider creating missing documentation linked in the README:
- docs/architecture.md
- docs/quickstart.md
```
**If `--format=console`** (display only):
- Show generated README in console
- Don't write file
- Provide copy-paste-ready output
## Output Format
Generate README following the 8-section minimal structure defined in `readme-authoring` skill.
**Example output** (Prototype tier):
```markdown
# Customer Churn Predictor
Early-stage prototype for predicting customer churn using transaction history.
## Description
The marketing team needs to identify customers at risk of churning to target retention campaigns effectively. This prototype implements a gradient boosting classifier trained on transaction and engagement data to predict churn probability. The model achieves 78% accuracy on historical data and provides interpretable feature importance for business teams.
## Installation
\`\`\`bash
pip install -e .
\`\`\`
## Documentation
- See notebooks in `notebooks/` for exploratory analysis and model training
- Model card available in `docs/model-card.md`
## Contributing
This is an experimental prototype. For questions or suggestions, contact the data science team.
## Bugs & Enhancements
Report issues via [GitHub Issues](https://github.com/USERNAME/churn-predictor/issues).
```
## Constraints
- **Don't overwrite existing README** without explicit user confirmation
- **Only link to docs that exist** - verify files before adding links
- **Integrate business context** - don't create separate Business Problem/Solution sections
- **Keep it minimal** - 8 sections only, no extras
- **Respect tier** - Prototype gets minimal structure, Production gets comprehensive
- **No placeholder links** - if docs don't exist, note this instead of linking to empty files
## Error Handling
**No project metadata found**:
- Prompt user for project name and description
- Continue with manual input
**No business context found**:
- Prompt user for business problem/solution
- Don't skip this - it's required for Short Description
**No issue tracker detected**:
- Prompt user for issue tracker URL
- Provide example format
**Write permission denied**:
- Display error message
- Suggest alternative output path or check permissions
## Success Criteria
Generated README should:
- ✅ Follow 8-section minimal structure
- ✅ Include business problem/solution in Short Description
- ✅ Have actionable installation command
- ✅ Link to existing documentation (no placeholders)
- ✅ Be tier-appropriate (badges, documentation depth)
- ✅ Pass validation via `/document-generator:validate-readme`
## Related Commands
- **`/document-generator:validate-readme`** - Check README compliance
- **`/document-generator:update-readme`** - Refactor existing README

292
commands/update-changelog.md Normal file
View File

@@ -0,0 +1,292 @@
---
description: Update existing CHANGELOG.md with new entries from recent commits
---
# Update Changelog
## Objective
Update existing CHANGELOG.md with new version entries based on recent git commits, maintaining standards and proper version sequencing.
## Activated Skills
1. **`changelog-standards`** (document-generator) - changelog format and structure
2. **`version-validation`** (document-generator) - Versioning rules and validation
3. **`git-history-analysis`** (document-generator) - Git commit parsing patterns
## Parameters
- `--path` (optional): Changelog location (auto-detects if not specified)
- `--style` (optional): Inherit from existing changelog or specify `standard`/`detailed`
- `--since` (optional): Git ref to start from (default: last version tag or last changelog entry)
- `--new-version` (optional): Version for new release (auto-increment if not provided)
- `--tier` (optional): Update tier annotation (Prototype, MVP, Production)
- `--draft` (optional): Add to [Unreleased] section instead of creating versioned release
## Process
### 1. Locate and Read Changelog
Locate changelog file:
- If `--path` specified: Use that location
- Otherwise auto-detect from standard locations:
- `CHANGELOG.md` (root)
- `docs/CHANGELOG.md`
- `docs/changelog/YYYY.md` (current year)
- Search for `**/CHANGELOG.md` or `**/changelog/*.md`
If not found:
```
❌ No CHANGELOG.md found
Run /document-generator:generate-changelog to create one first.
```
Read and parse existing changelog:
- Extract current version
- Detect version type (SemVer vs CalVer)
- Identify format (single-file vs yearly)
- Detect style (standard vs detailed) from existing structure
### 2. Determine Commit Range
**Find last version**:
```bash
# From changelog
grep -E "^## \[" CHANGELOG.md | head -n 2 | tail -n 1
# From git tags
git describe --tags --abbrev=0 2>/dev/null
```
**Get commits since last version**:
```bash
# If last tag exists
git log LAST_TAG..HEAD --no-merges --pretty=format:"%h|%s|%ad" --date=short
# If no tags (first release since changelog creation)
git log --since="$(git log -1 --format=%ai CHANGELOG.md)" --no-merges --pretty=format:"%h|%s|%ad" --date=short
```
If no new commits:
```
ℹ️ No new commits since last version
Changelog is up-to-date.
```
### 3. Analyze New Commits
Parse commit messages, categorize into sections, filter noise, group related changes, and transform to user-facing language.
**Extract PR/issue numbers** from commit messages to include as links.
### 4. Determine New Version
**If `--new-version` specified**: Use that (validate with `version-validation` skill)
**If `--draft` flag**: Add to [Unreleased] section
**Otherwise, auto-increment**:
**For SemVer**:
- If "feat" or "Added" entries → Increment MINOR (2.1.0 → 2.2.0)
- If only "fix" or "Fixed" entries → Increment PATCH (2.1.0 → 2.1.1)
- If breaking changes detected → Suggest MAJOR (2.1.0 → 3.0.0)
**For CalVer (Year.Minor)**:
- Same year → Increment MINOR (2025.1 → 2025.2)
- New year → Reset to YEAR.1 (2024.5 → 2025.1)
**Ask user for confirmation**:
```
Based on commits, I suggest version: [suggested-version]
Changes detected:
- X new features (Added)
- Y bug fixes (Fixed)
- Z improvements (Changed)
What version should I use?
1. [suggested-version] (recommended)
2. Specify custom version
3. Add to [Unreleased] instead
```
### 5. Insert New Version Section
Format new entry based on detected or specified style:
**Standard style**:
```markdown
## [NEW_VERSION] - YYYY-MM-DD [TIER]
### Added
- Feature description (#PR)
### Changed
- Improvement description (#PR)
### Fixed
- Bug fix (#PR)
```
**Detailed style**:
```markdown
## [NEW_VERSION] - YYYY-MM-DD [TIER]
### Highlights
- Major capability added
- Significant improvement made
### Detailed Notes
#### Added
- Feature with technical context (#PR)
#### Changed
- Change with rationale (#PR)
#### Fixed
- Fix with context (#PR)
```
**Insert location**:
- After "## [Unreleased]" section
- Before previous version entries
- Maintain reverse chronological order
**Update [Unreleased] section**:
- Remove entries that moved to new version
- Keep any remaining draft entries
### 6. Update Version Comparison Links
At bottom of changelog, add/update links:
```markdown
[NEW_VERSION]: https://github.com/ORG/REPO/compare/vOLD_VERSION...vNEW_VERSION
[OLD_VERSION]: https://github.com/ORG/REPO/compare/vPREV_VERSION...vOLD_VERSION
```
Extract repo URL from:
```bash
git config --get remote.origin.url
```
### 7. Write Updated Changelog
Validate with `version-validation` skill:
- Version format correct
- Chronological ordering maintained
- No version skips
- Dates are valid
Write updated file back to original location.
### 8. Provide Guidance
```
✓ Updated CHANGELOG.md with version NEW_VERSION
Changes:
- Added: X entries
- Changed: Y entries
- Fixed: Z entries
Next steps:
1. Review the new changelog entries
2. Commit changes: git add CHANGELOG.md
3. Tag release: git tag vNEW_VERSION
4. Push with tags: git push --tags
```
## Output Format
**Console** (default): Display summary and next steps
**Markdown** (if `--output` specified): Save updated changelog
## Special Cases
### Draft Mode (--draft)
Add to [Unreleased] instead of creating versioned release:
```markdown
## [Unreleased]
### Added
- New feature in development
### Fixed
- Bug fix awaiting release
```
Use this when:
- Changes not ready for release
- Accumulating changes before version bump
- Working in feature branch
### Empty Unreleased Section
If [Unreleased] section exists but is empty, preserve it:
```markdown
## [Unreleased]
## [1.2.0] - 2025-11-11
```
### Multiple Version Formats
If changelog contains both CalVer and SemVer (migration scenario):
- Detect most recent format
- Warn user about mixed formats
- Suggest standardizing
## Examples
**Basic usage**:
```bash
/document-generator:update-changelog
→ Auto-detects last version, suggests next version, updates changelog
```
**With specific version**:
```bash
/document-generator:update-changelog --new-version=2.1.0
→ Creates version 2.1.0 entry with recent commits
```
**Draft mode**:
```bash
/document-generator:update-changelog --draft
→ Adds commits to [Unreleased] section
```
**With tier annotation**:
```bash
/document-generator:update-changelog --new-version=1.0.0 --tier=MVP
→ Creates [1.0.0] [MVP] entry
```
**Since specific ref**:
```bash
/document-generator:update-changelog --since=v1.5.0
→ Includes all commits since v1.5.0 tag
```
**Custom location**:
```bash
/document-generator:update-changelog --path=docs/CHANGELOG.md
→ Updates changelog at docs/CHANGELOG.md
```
## Constraints
- Token budget: Keep concise, delegate to skills
- Preserve existing changelog structure
- Maintain chronological order
- Validate all version increments
- No data loss - backup approach recommended

514
commands/update-readme.md Normal file
View File

@@ -0,0 +1,514 @@
---
description: Refactor existing README.md to conform to standards
---
# Update README
## Activated Agent
**Activate**: `readme-author` agent
The agent will refactor your existing README.md to meet Personal minimal standards.
## Objective
Update existing README.md to conform to 8-section minimal structure, preserving compliant content while adding missing sections and integrating business context.
## Command Parameters
| Parameter | Options | Default | Description |
|-----------|---------|---------|-------------|
| `--sections` | Comma-separated: `title`, `badges`, `description`, `installation`, `documentation`, `components`, `contributing`, `bugs` | All missing/incomplete | Specific sections to update |
| `--tier` | `prototype`, `mvp`, `production` | Auto-detect | Target project tier |
| `--format` | `console`, `markdown` | `console` | Output format (console display vs. write file) |
| `--output` | `<path>` | `./README.md` | Output path (use different path to preserve original) |
| `--interactive` | `true`, `false` | `true` | Show diffs and prompt for approval |
**Examples:**
```bash
/document-generator:update-readme # Interactive, all sections
/document-generator:update-readme --sections=description,documentation
/document-generator:update-readme --tier=mvp --format=markdown --interactive=false
/document-generator:update-readme --output=./README-new.md --format=markdown
```
## Activated Skills
The agent will activate these skills:
1. **`readme-authoring`** - Templates for missing sections
2. **`readme-standards`** - Validation criteria and compliance checking
## Process
The agent will follow this workflow:
### 1. Pre-flight Checks
**Check if README.md exists**:
- If `README.md` not found:
```
❌ No README.md found in current directory.
Use `/document-generator:generate-readme` to create one.
Aborting update.
```
- Stop execution
**Create backup** (before making changes):
```bash
cp README.md README.md.backup
```
Notify user:
```
📁 Backup created: README.md.backup
```
### 2. Validate Current README
**Run validation first** (same logic as `validate-readme`):
- Parse structure
- Identify missing/incomplete sections
- Check content quality
- Validate links
**Display current state**:
```
📊 Current README Status
Tier: MVP (detected)
Compliance: ✅ Minimal
Issues found:
⚠️ 1. Short Description - Missing business problem context
⚠️ 2. Documentation - ADRs not linked (adr/ exists)
❌ 3. Contributing - Section missing
ℹ️ 4. Badges - Not present (recommended for MVP tier)
Ready to fix these issues.
```
### 3. Determine Sections to Update
**If `--sections` parameter provided**:
- Only update specified sections
- Skip sections not in the list
**If no `--sections` parameter**:
- Update all missing sections (❌)
- Update all incomplete sections (⚠️)
- Note optional sections (ℹ️) but don't auto-add unless requested
**Priority order**:
1. Missing required sections (Contributing, Installation, etc.)
2. Incomplete sections (missing business context, broken links)
3. Optional enhancements (Badges, Supporting Components)
### 4. Extract Context for Updates
Same extraction logic as `generate-readme`:
**For missing/incomplete sections, gather**:
- Project metadata (from pyproject.toml, package.json, etc.)
- Business context (from docs, code, or user input)
- Existing documentation to link
- Issue tracker URL
- CONTRIBUTING.md location
**Preserve existing content**:
- Don't regenerate compliant sections
- Extract and reuse content from non-compliant sections
- Maintain user's formatting choices where possible
### 5. Generate Section Updates
For each section needing update:
**Title & One-Liner**:
- Preserve existing title if present
- Add one-liner if missing
- Improve vague descriptions
**Badges** (if missing and tier >= MVP):
- Generate minimal badge set
- Insert after title, before description
**Short Description**:
- **If "## Overview" exists instead of "## Description"**:
- Keep as "## Overview" (both acceptable per standards)
- Only update if content lacks business context
- **If separate "Business Problem" and "Solution" sections exist**:
- Note: This is acceptable per flexible standards
- Offer to merge into single `## Description` or `## Overview` paragraph for conciseness (optional)
- If user prefers merged format: Extract, merge, show diff
- If user prefers separate: Keep as-is if content is brief and focused
- **If description/overview lacks business context**:
- Prompt user for business problem/solution
- Integrate into existing description or overview
- Preserve technical details
**Installation**:
- If missing: Generate from project type
- If incomplete: Add link to setup guide if exists
- If overly detailed: Suggest moving to docs/setup.md
**Documentation**:
- Check if docs are in dedicated `## Documentation` section OR within `## Guides` or similar
- Add links to discovered docs not currently linked (anywhere in README)
- If docs scattered across multiple sections, offer to consolidate (optional)
- Verify all existing links still valid
- Organize in logical order (Quickstart, API, Architecture, ADRs)
**Supporting Components**:
- Only add if dependencies detected
- Skip if standalone project
**Contributing**:
- Check if contributing link exists in dedicated `## Contributing` section OR within `## Documentation`/`## Guides`
- If CONTRIBUTING.md exists but not linked anywhere: Add link (in existing docs section or create new Contributing section)
- If no CONTRIBUTING.md: Offer to create basic Contributing section with inline guidance
- Add test command if detectable
**Issue Reporting**:
- Check if issue reporting exists in dedicated `## Bugs` section OR within `## Contributing`/`## Documentation`
- If missing anywhere: Add link (in existing section or create new Bugs section)
- GitHub Issues link if GitHub repo detected
- Prompt user for issue tracker if not detectable
### 6. Present Diffs (Interactive Mode)
For each section being updated, show before/after diff:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UPDATE: Short Description
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BEFORE:
────────────────────────────────────────────────
## Business Problem
Marketing teams struggle with customer segmentation.
## Solution
This tool provides automated clustering.
## Description
The Customer Segmentation Engine uses ML to group customers.
────────────────────────────────────────────────
AFTER:
────────────────────────────────────────────────
## Description
Marketing teams struggle with customer segmentation, leading to ineffective campaign targeting and low conversion rates. This tool provides automated clustering capabilities using machine learning to group customers by purchasing behavior. The Customer Segmentation Engine processes transaction history and demographic data to generate actionable segments for targeted marketing campaigns.
────────────────────────────────────────────────
Changes:
- Merged Business Problem and Solution sections into Description
- Integrated business context into cohesive paragraph
- Preserved technical details from original Description
Apply this update? (y/n/edit):
```
**User options**:
- `y`: Apply this update
- `n`: Skip this update
- `edit`: Modify the generated content before applying
- `all`: Apply all remaining updates without prompting
**If user chooses "edit"**:
```
Enter updated content for Short Description:
(Paste content, then press Ctrl+D or type 'done' on new line)
> ___
```
Accept user's edited content and continue.
### 7. Apply Updates
**Build updated README**:
1. Start with existing README content
2. For each section to update:
- If section exists: Replace content
- If section missing: Insert in correct position (maintain 8-section order)
- If section needs removal (e.g., separate Business Problem): Remove it
3. Maintain proper structure:
- Title first (`#`)
- Badges after title (if present)
- Sections in order (`##`)
- Preserve custom sections not in standard 8 (at end)
**Example transformation**:
**Before (non-compliant)**:
```markdown
# My Project
## Business Problem
Teams have issues.
## Solution
This fixes it.
## Setup
Install stuff.
```
**After (compliant)**:
```markdown
# My Project
Brief description of what this does and why.
## Description
Teams struggle with X problem, leading to Y consequence. This project provides Z solution by implementing W approach. The system handles A, B, and C use cases.
## Installation
\`\`\`bash
pip install my-project
\`\`\`
## Documentation
- [Architecture](docs/architecture.md) - System design
- [ADRs](adr/) - Key decisions
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## Bugs & Enhancements
Report issues via [GitHub Issues](https://github.com/org/my-project/issues).
```
### 8. Write Updated README
**If `--format=markdown`** (write file):
```bash
# Write updated README
cat > ./README.md <<'EOF'
{updated content}
EOF
```
**Confirm success**:
```
✓ README.md updated successfully
Sections updated:
1. Short Description - Merged Business Problem/Solution, added context
2. Documentation - Added links to ADRs and architecture docs
3. Contributing - Added link to CONTRIBUTING.md
Backup saved to: README.md.backup
Next steps:
- Review the updated README
- Run `/document-generator:validate-readme` to verify compliance
- Consider creating suggested documentation:
- docs/quickstart.md
```
**If `--format=console`** (display only):
- Show full updated README
- Don't write file
- Note that backup was NOT created (no changes made)
### 9. Cleanup
**If changes were successfully applied**:
- Keep backup file (README.md.backup)
- User can delete backup later
**If user cancelled**:
- Remove backup file
- Leave original README unchanged
## Interactive Patterns
### Prompt for Business Context
If description lacks business problem/solution:
```
The Short Description section is missing business context.
To update it, I need to know:
1. What business problem does this project solve?
(1-2 sentences describing the problem and its impact)
> ___
2. What solution does this project provide?
(1-2 sentences describing how it addresses the problem)
> ___
```
### Confirm Major Changes
For significant restructuring (merging sections, removing content):
```
⚠️ Major Restructure Detected
This update will:
- Merge "Business Problem" and "Solution" sections into "Description"
- Remove separate sections (content will be preserved)
- Add 2 new sections (Contributing, Bugs & Enhancements)
This is a significant change. Continue? (y/n):
```
### Handle Custom Sections
If README has custom sections beyond the standard 8:
```
ℹ️ Custom Sections Detected
Your README contains custom sections:
- ## FAQ
- ## Troubleshooting
- ## Changelog
These will be preserved at the end of the README.
Continue? (y/n):
```
## Constraints
- **Preserve compliant content** - Don't regenerate sections that meet standards
- **Maintain user intent** - Keep custom sections, preserve formatting preferences
- **Show diffs for transparency** - User should see all changes before applying
- **Create backups** - Always backup before modifying
- **Link validation** - Only add links to docs that actually exist
- **Respect tier** - Apply tier-appropriate standards
## Error Handling
**README.md not found**:
- Suggest using `generate-readme`
- Stop execution
**README.md not writable**:
- Check file permissions
- Suggest alternative output path
**Backup creation fails**:
- Warn user
- Prompt to continue without backup or cancel
**User cancels mid-update**:
- Restore from backup
- Clean up partial changes
## Success Criteria
Updated README should:
- ✅ Preserve all compliant existing content
- ✅ Fix identified compliance issues
- ✅ Integrate business context into Description
- ✅ Link to all discovered documentation
- ✅ Follow 8-section minimal structure
- ✅ Pass validation via `/document-generator:validate-readme`
## Special Cases
### Optional: Merging Business Problem/Solution Sections
**Note**: Per updated standards, separate Business Problem/Solution sections are acceptable if brief and focused.
**If README has** separate sections and user prefers merged format:
```markdown
## Business Problem
{problem text}
## Solution
{solution text}
## Description
{technical details}
```
**Offer to transform to** (optional):
```markdown
## Description
{problem text}. {solution text}. {technical details}.
```
**Or keep as-is** if user prefers separate sections (compliant per flexible standards)
### Handling Overly Detailed Installation
**If Installation section has**:
```markdown
## Installation
1. Install Python 3.9+
2. Create virtual environment
3. Install dependencies: pip install -r requirements.txt
4. Set up database: ...
5. Run migrations: ...
6. Configure environment: ...
```
**Suggest**:
```
⚠️ Installation section is overly detailed.
Recommendation: Move detailed setup to docs/setup.md
Updated Installation section:
───────────────────────────────────────
## Installation
\`\`\`bash
pip install my-project
\`\`\`
For detailed setup and configuration, see [Setup Guide](docs/setup.md).
───────────────────────────────────────
Apply this simplification? (y/n):
```
### Preserving Custom Content
If README has unique sections (FAQ, Roadmap, Changelog):
- Keep them at the end of README
- Maintain their order
- Don't flag as non-compliant
- Note in update summary
## Related Commands
- **`/document-generator:validate-readme`** - Check README before/after update
- **`/document-generator:generate-readme`** - Create new README instead
## Batch Update Mode
**For non-interactive batch updates** (`--interactive=false`):
- Apply all fixes automatically
- No user prompts
- Create detailed update log
- Save to `./reports/readme-update-log.md`
**Use with caution** - Review changes carefully after batch update.

280
commands/validate-changelog.md Normal file
View File

@@ -0,0 +1,280 @@
---
description: Validate existing CHANGELOG.md against standards
---
# Validate Changelog
## Objective
Validate existing CHANGELOG.md against standards (Keep a Changelog format) and report compliance issues with severity levels.
## Activated Skills
1. **`changelog-standards`** (document-generator) - changelog format and structure
2. **`version-validation`** (document-generator) - Versioning rules and validation
## Parameters
- `--path` (optional): Changelog location (auto-detects if not specified)
- `--fix` (optional): Automatically fix common formatting issues
- `--output` (optional): `console` (default) or `markdown` (generate validation report)
## Process
### 1. Locate Changelog
Locate changelog file:
- If `--path` specified: Use that location
- Otherwise auto-detect from standard locations:
- `CHANGELOG.md` (root)
- `docs/CHANGELOG.md`
- `docs/changelog/*.md` (yearly format)
- Search for `**/CHANGELOG.md` or `**/changelog/*.md`
If not found:
```
❌ CHANGELOG.md not found
No changelog file detected in standard locations.
Run /document-generator:generate-changelog to create one.
```
### 2. Parse Changelog Structure
Read and extract:
- File header (title, preamble)
- [Unreleased] section
- Version entries with dates and tiers
- Changelog sections (Added, Changed, Fixed, etc.)
- Version comparison links
### 3. Validate Format
**Apply `changelog-standards` skill** to check:
#### Header Validation
- ✓ Has "# Changelog" or "# Change Log" title
- ✓ References Keep a Changelog format
- ⚠️ Missing header is a warning (not error)
#### Version Heading Validation
- ✓ Format: `## [VERSION] - YYYY-MM-DD` or `## [VERSION] - YYYY-MM-DD [TIER]`
- ❌ Missing brackets around version
- ❌ Incorrect date format (not YYYY-MM-DD)
- ⚠️ Invalid tier annotation
**Examples**:
```markdown
## [2.1.0] - 2025-11-01 [MVP] ✓ Valid
## [2025.1] - 2025-01-15 ✓ Valid
## v2.1.0 - 2025-11-01 ❌ No brackets
## [2.1.0] - 11/01/2025 ❌ Wrong date format
## [2.1.0] - 2025-11-01 [Alpha] ⚠️ Invalid tier (use Prototype)
```
#### Section Validation
- ✓ Uses standard sections (Added, Changed, Deprecated, Removed, Fixed, Security)
- ⚠️ Non-standard sections (Features, Bugs, etc.)
- ✓ Sections in correct order
- ⚠️ Empty sections (should remove or populate)
#### Link Validation
- ✓ Version comparison links at bottom
- ✓ Links follow format: `[VERSION]: URL`
- ⚠️ Missing links for versions
- ❌ Broken link format
### 4. Validate Versions
**Apply `version-validation` skill** to check:
#### Version Format
- ✓ Matches SemVer pattern (`X.Y.Z`)
- ✓ Matches CalVer pattern (`YYYY.N` or `YYYY.MM.N`)
- ❌ Invalid version format
- ⚠️ Mixed version types (both SemVer and CalVer)
#### Version Ordering
- ✓ Versions in reverse chronological order (newest first)
- ❌ Out-of-order versions
- ⚠️ Skipped versions (1.0.0 → 1.2.0, missing 1.1.0)
#### Version Increments
- ✓ Proper SemVer increments
- ✓ Proper CalVer increments
- ❌ Invalid increment (e.g., 2.1.5 → 2.3.0, skipped 2.2.x)
#### Date Validation
- ✓ Valid ISO dates (YYYY-MM-DD)
- ❌ Invalid date format
- ❌ Invalid date (e.g., Feb 30)
- ⚠️ Dates not in chronological order
- ⚠️ Future dates (minor warning)
### 5. Generate Validation Report
**Categorize issues** by severity:
**Errors** (❌) - Must fix:
- Invalid version format
- Invalid date format
- Out-of-order versions
- Broken heading structure
**Warnings** (⚠️) - Should fix:
- Missing tier annotations
- Skipped versions
- Non-standard sections
- Missing version links
- Empty sections
**Info** (ℹ️) - Nice to have:
- Missing header preamble
- Future dates
- Inconsistent formatting
**Output format** (console):
```
Validating CHANGELOG.md...
❌ Errors (3)
Line 15: Invalid version format "v2.1.0" (should be "[2.1.0]")
Line 23: Invalid date format "11/01/2025" (should be "YYYY-MM-DD")
Line 30: Versions out of order ([1.5.0] before [2.0.0])
⚠️ Warnings (2)
Line 42: Skipped version 1.1.0 (jumped from 1.0.0 to 1.2.0)
Line 67: Non-standard section "Bugs" (use "Fixed")
ℹ️ Info (1)
Missing version comparison links at bottom of file
Overall: Failed (3 errors, 2 warnings)
```
### 6. Auto-fix (if --fix enabled)
Automatically correct common issues:
**Fixable issues**:
- Add brackets around versions: `v2.1.0` → `[2.1.0]`
- Standardize date format: `11/01/2025` → `2025-11-01`
- Rename sections: `Bugs` → `Fixed`, `Features` → `Added`
- Add missing header preamble
- Generate version comparison links
**Not auto-fixable** (manual intervention required):
- Out-of-order versions (need reordering)
- Invalid dates (need manual correction)
- Skipped versions (intentional or error?)
**If --fix enabled**:
```
Fixing common issues...
✓ Fixed 5 issues automatically
- Standardized 2 version formats
- Corrected 2 date formats
- Renamed 1 section
⚠️ 2 issues require manual fix
- Line 30: Reorder versions manually
- Line 42: Confirm if version 1.1.0 was intentionally skipped
Updated CHANGELOG.md saved.
```
### 7. Output Results
**Console output** (default):
- Display validation summary
- List all errors and warnings with line numbers
- Provide fix suggestions
- Show overall pass/fail status
**Markdown report** (if `--output=markdown`):
- Save to `./reports/changelog-validation-report.md`
- Include all issues with context
- Link to changelog file
- Provide remediation steps
## Output Format
### Console (Default)
```
Validating CHANGELOG.md...
✓ Header present
✓ Keep a Changelog format referenced
✓ [Unreleased] section present
✓ 5 versions found
Checking versions...
[2.1.0] ✓
[2.0.0] ✓
[1.5.0] ⚠️ Missing tier annotation
[1.0.0] ✓
Checking format...
✓ All sections use standard names
✓ Versions in correct order
⚠️ 2 versions missing comparison links
Summary:
- Errors: 0
- Warnings: 3
- Overall: Pass with warnings
Next steps:
1. Add tier annotations to versions
2. Generate comparison links at bottom
```
### Markdown Report (--output=markdown)
Same structure as console output above, saved to `./reports/changelog-validation-report.md` with:
- Full issue details with line numbers and context
- Fix recommendations for each issue
- Links to changelog file
- Remediation steps by priority
## Examples
**Basic validation**:
```bash
/document-generator:validate-changelog
→ Validates CHANGELOG.md and displays results in console
```
**Auto-fix issues**:
```bash
/document-generator:validate-changelog --fix
→ Validates and automatically fixes common formatting issues
```
**Generate report**:
```bash
/document-generator:validate-changelog --output=markdown
→ Saves validation report to ./reports/changelog-validation-report.md
```
**Combined**:
```bash
/document-generator:validate-changelog --fix --output=markdown
→ Fixes issues and generates report
```
**Custom location**:
```bash
/document-generator:validate-changelog --path=docs/CHANGELOG.md
→ Validates changelog at docs/CHANGELOG.md
```
## Constraints
- Token budget: Keep concise, delegate validation logic to skills
- Non-destructive by default (use --fix to modify)
- Preserve user content, only fix format
- Clear severity distinctions (error vs warning vs info)

386
commands/validate-readme.md Normal file
View File

@@ -0,0 +1,386 @@
---
description: Audit existing README.md compliance with standards without making changes
---
# Validate README
## Activated Agent
**Activate**: `readme-author` agent
The agent will audit your README.md against Personal minimal standards.
## Objective
Validate existing README.md structure and content against 8-section minimal requirements, identify missing or incomplete sections, and provide actionable recommendations for improvement.
## Command Parameters
| Parameter | Options | Default | Description |
|-----------|---------|---------|-------------|
| `--tier` | `prototype`, `mvp`, `production` | Auto-detect | Project tier to validate against |
| `--format` | `console`, `markdown` | `console` | Output format (console display vs. report file) |
| `--output` | `<path>` | `./reports/readme-validation-report.md` | Custom report path (requires `--format=markdown`) |
**Examples:**
```bash
/document-generator:validate-readme # Console output, auto-detect tier
/document-generator:validate-readme --tier=mvp --format=markdown
/document-generator:validate-readme --format=markdown --output=./docs/readme-validation.md
```
## Activated Skills
The agent will activate these skills:
1. **`readme-standards`** - minimal README validation criteria
2. **`readme-authoring`** - Reference templates for comparison
## Process
The agent will follow this workflow:
### 1. Pre-flight Checks
**Check if README.md exists**:
- If `README.md` not found in current directory:
```
❌ No README.md found in current directory.
Use `/document-generator:generate-readme` to create one.
Aborting validation.
```
- Stop execution
- If `README.md` exists: Proceed with validation
### 2. Detect Project Tier
Agent will detect project tier (if not specified via `--tier`) and display for user. Validation will use tier-appropriate standards from `readme-standards` skill.
### 3. Parse README Structure
**Read and analyze README.md**:
1. **Extract sections** - Identify which of the 8 sections are present (with flexible section names):
- Title & One-Liner (check for `# {Title}` and description)
- Badges Block (check for shield.io badges or similar)
- Short Description (`## Description` or `## Overview` acceptable)
- Installation (`## Installation` or `## Quick Start`)
- Documentation (dedicated `## Documentation` section OR links within `## Guides`/other sections)
- Supporting Components (`## Supporting Components`)
- Contributing (dedicated `## Contributing` section OR link within `## Documentation`/`## Guides`)
- Issue Reporting (dedicated `## Bugs` section OR link within `## Contributing`/`## Documentation`)
2. **Check heading hierarchy**:
- Title uses `#`
- Sections use `##`
- No `###` headings (keep it minimal)
3. **Count sections** - Track which required vs. optional sections are present
### 4. Validate Content Quality
For each section, validate content:
**Title & One-Liner** (REQUIRED):
- ✅ Level 1 heading present
- ✅ One-liner present (1-2 sentences)
- ✅ Description is specific, not vague
- ⚠️ If missing or vague: Flag as incomplete
**Badges** (OPTIONAL, tier-dependent):
- ℹ️ Note if missing for MVP/Production projects
- ✅ If present, check format (shields.io or similar)
- ⚠️ If placeholder badges: Flag as incomplete
**Short Description** (REQUIRED):
- ✅ `## Description` or `## Overview` heading present
- ✅ Paragraph length appropriate (3-5 sentences)
- ✅ **Business problem context** included
- ✅ **Solution context** included
- ℹ️ Separate `## Business Problem` or `## Solution` sections acceptable if brief and focused
- ✅ Preferred approach: Integrate business/solution context into single Description/Overview paragraph
- ⚠️ If business context missing: Flag as incomplete
**Installation** (REQUIRED):
- ✅ `## Installation` heading present
- ✅ Installation command in code block
- ✅ Command is actionable (not "install this project")
- ✅ Link to setup guide if `docs/setup.md` exists
- ⚠️ If missing link to existing setup guide: Flag as incomplete
**Documentation** (REQUIRED):
- ✅ Documentation links present (can be in dedicated `## Documentation` section OR within `## Guides` or similar section)
- ✅ At least one documentation link provided
- ✅ Links point to existing files (validate)
- ⚠️ If ADRs exist in `adr/` but not linked anywhere: Recommend linking
- ⚠️ If architecture docs exist but not linked anywhere: Recommend linking
- ⚠️ If minimal documentation: Suggest additions
**Supporting Components** (OPTIONAL):
- ℹ️ Note if missing (not an error)
- ✅ If present, lists actual dependencies with links
**Contributing Link** (REQUIRED):
- ✅ Contributing guidance or link present (can be dedicated `## Contributing` section OR link within `## Documentation`/`## Guides`)
- ✅ Link to `CONTRIBUTING.md` if file exists (can be in any section)
- ✅ If no `CONTRIBUTING.md`, basic guidance provided somewhere in README
- ⚠️ If `CONTRIBUTING.md` exists but not linked anywhere: Recommend linking
- ⚠️ If MVP/Production without `CONTRIBUTING.md`: Suggest creating one
**Issue Reporting** (REQUIRED):
- ✅ Issue reporting link or guidance present (can be dedicated `## Bugs` section OR link within `## Contributing`/`## Documentation`)
- ✅ Issue tracker link provided somewhere in README
- ⚠️ If no clear path to report issues: Flag as missing
### 5. Validate Links
**Check documentation links** referenced in README:
1. **Relative links** - Verify files exist:
- `docs/setup.md`
- `docs/architecture.md`
- `adr/`
- `CONTRIBUTING.md`
2. **External links** - Note but don't verify (assume valid):
- GitHub Issues URLs
- API documentation URLs
- Confluence links
3. **Flag broken links**:
```
❌ Broken link: docs/quickstart.md (file not found)
```
### 6. Check for Undiscovered Documentation
**Scan for documentation not linked in README**:
```bash
# Check for common doc files
test -f docs/architecture.md && echo "Architecture doc exists"
test -d adr && echo "ADRs exist"
test -f CONTRIBUTING.md && echo "Contributing guide exists"
```
**If documentation exists but not linked**:
```
⚠️ Found documentation not linked in README:
- docs/architecture.md exists but not linked in Documentation section
- adr/ exists (3 ADRs) but not linked
```
### 7. Generate Compliance Report
**Tier-appropriate validation** using `readme-standards` skill criteria.
**Calculate compliance score**:
- Count required content present (out of 6 core requirements: Title, Description/Overview, Installation, Documentation links, Contributing link, Issue reporting)
- Note: Section names can vary - focus on whether essential content/links exist somewhere in README
- Count optional sections present (out of 2: Badges, Supporting Components)
- Count content quality issues (missing business context, broken links, etc.)
**Assign compliance level**:
- ✅✅✅ **Excellent** - All required content present, business context clear, comprehensive links, tier-appropriate
- ✅✅ **Standard** - All required content present, minor content gaps
- ✅ **Minimal** - Required content mostly present, some significant gaps (missing contributing link or issue reporting)
- ❌ **Non-compliant** - Missing multiple core requirements
### 8. Present Results
**Console format** (`--format=console`, default):
```
📋 README Validation Report
Project: {Project Name}
Tier: {Detected Tier}
Compliance Level: ✅✅ Standard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ COMPLIANT SECTIONS (5/6 required, 1/2 optional)
1. Title & One-Liner - Clear and descriptive
2. Short Description - Business context included
3. Installation - Simple command with setup link
4. Documentation - 3 resources linked
5. Bugs & Enhancements - Issue tracker linked
ℹ️ OPTIONAL SECTIONS
6. Badges - Not present (MVP tier - recommended)
7. Supporting Components - Not applicable
⚠️ INCOMPLETE SECTIONS (1)
8. Contributing - Section present but CONTRIBUTING.md not linked
→ CONTRIBUTING.md exists at ./CONTRIBUTING.md
→ Add link in Contributing section
❌ MISSING SECTIONS (1)
9. (None)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌 RECOMMENDATIONS
Priority 1 (Required):
- Link to CONTRIBUTING.md in Contributing section
Priority 2 (Suggested):
- Add badges (project is MVP tier - version, lifecycle, docs, code style)
- Link to ADRs in Documentation section (3 ADRs found in adr/)
Priority 3 (Optional):
- Create quickstart guide (docs/quickstart.md)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✨ NEXT STEPS
Run `/document-generator:update-readme` to automatically fix issues.
```
**Markdown format** (`--format=markdown`):
Generate detailed report using structure from `readme-standards` skill Resources section.
Write to output path (default: `./reports/readme-validation-report.md`):
```markdown
# README Validation Report
**Project**: {Project Name}
**Date**: {Date}
**Tier**: {Detected Tier}
**Compliance Level**: ✅✅ Standard
## Summary
- ✅ 5 of 6 required sections compliant
- ⚠️ 1 section incomplete
- ❌ 0 sections missing
- ℹ️ 1 of 2 optional sections present
## Detailed Assessment
### ✅ Compliant Sections
1. **Title & One-Liner** - Clear and descriptive
- Title: "Customer Segmentation Engine"
- One-liner present and specific
2. **Short Description** - Business context included
- Business problem: Marketing teams need customer segmentation
- Solution: Clustering service for targeted campaigns
- Core functionality described
...
### ⚠️ Incomplete Sections
8. **Contributing** - Section present but incomplete
- Section exists with basic guidance
- CONTRIBUTING.md exists at `./CONTRIBUTING.md` but not linked
- **Recommendation**: Add link to CONTRIBUTING.md
### ❌ Missing Sections
(None)
## Recommendations
### Priority 1 (Required)
- Link to CONTRIBUTING.md in Contributing section
### Priority 2 (Suggested)
- Add badges (MVP tier: version, lifecycle, docs, code style)
- Link to ADRs in Documentation section
### Priority 3 (Optional)
- Create quickstart guide
## Next Steps
Run `/document-generator:update-readme` to automatically fix issues.
```
**Create reports directory if needed**:
```bash
mkdir -p reports
```
**Confirm report creation**:
```
✓ Validation report saved to ./reports/readme-validation-report.md
```
## Output Format
**Console output** - Structured, scannable report with emojis for visual clarity
**Markdown report** - Detailed, archivable document following structure from `readme-standards` skill
## Validation Levels
Using progressive validation from `readme-standards` skill:
**Level 1: Structure** (must pass for minimal compliance):
- All 6 required pieces of content present (title, description/overview, installation, docs links, contributing link, issue reporting)
- Section names can vary - essential content matters more than exact section structure
- Proper heading hierarchy
**Level 2: Content** (standard compliance):
- Business problem/solution context included (in Description, Overview, or separate sections)
- Actionable installation command
- Valid documentation links
- Contributing guidance accessible (dedicated section or link within docs/guides)
- Issue reporting path clear (dedicated section or link within contributing/docs)
**Level 3: Quality** (excellent compliance):
- Tier-appropriate badges
- Comprehensive documentation links (architecture, ADRs, guides)
- CONTRIBUTING.md exists and linked for mature projects
- All available documentation linked appropriately
## Constraints
- **Read-only** - This command does not modify README.md
- **Link validation** - Only check relative links, not external URLs
- **Tier-appropriate** - Validation criteria adjust based on project tier
- **No speculation** - Only flag issues based on actual file checks
- **Actionable recommendations** - Every issue should have clear fix
## Error Handling
**README.md not found**:
- Display clear error message
- Suggest using `/document-generator:generate-readme`
- Stop execution
**Cannot create reports directory**:
- Display error with permission issue
- Suggest alternative output path
**README.md unreadable**:
- Display error (encoding issue, permissions)
- Suggest checking file permissions
## Success Criteria
Validation report should:
- ✅ Accurately identify missing/incomplete sections
- ✅ Provide tier-appropriate recommendations
- ✅ Flag broken links and missing doc references
- ✅ Give clear, actionable next steps
- ✅ Assign appropriate compliance level
## Related Commands
- **`/document-generator:generate-readme`** - Create new README
- **`/document-generator:update-readme`** - Fix identified issues