diff --git a/.vibe/skills/changelog-manager/SKILL.md b/.vibe/skills/changelog-manager/SKILL.md new file mode 100644 index 0000000..31135f9 --- /dev/null +++ b/.vibe/skills/changelog-manager/SKILL.md @@ -0,0 +1,278 @@ +--- +name: changelog-manager +description: A skill to help agents properly maintain and utilize AGENT_CHANGELOG.md for tracking contributions and decisions +license: MIT +metadata: + author: DanceLessonsCoach Team + version: "1.0.0" + role: Documentation Assistant + purpose: Maintain consistent, useful changelog entries +--- + +# Changelog Manager Skill + +A skill to help AI agents properly maintain and utilize `AGENT_CHANGELOG.md` for tracking contributions, decisions, and project direction. Ensures consistent format, relevant content, and iterative improvements. + +## 🎯 Purpose + +The changelog manager skill helps agents: +1. **Understand when to update** the changelog +2. **Follow consistent format** for entries +3. **Include relevant information** without bloat +4. **Keep it iterative** and focused +5. **Reference past decisions** effectively + +## 📋 When to Update the Changelog + +### ✅ Update After Each Session +- **Completed significant work** (feature, bugfix, refactor) +- **Made important decisions** (architecture, tooling, process) +- **Changed project direction** (priorities, focus areas) +- **Resolved major issues** (blockers, technical debt) + +### ❌ Don't Update For +- **Trivial changes** (typo fixes, minor formatting) +- **Routine maintenance** (dependency updates, routine tests) +- **Failed attempts** (unless learning is valuable) +- **Repetitive tasks** (same task done multiple times) + +## 📝 Entry Format Guide + +### Standard Entry Structure + +```markdown +## YYYY-MM-DD - [Brief Description] + +**Status:** ✅/⏳/❌ [Completed/In Progress/Blocked] +**Commit:** `[hash]` (if applicable) + +### What Was Done +- Concise bullet points of changes +- Focus on outcomes, not just actions +- Use active voice ("Implemented X", not "X was implemented") + +### Why It Was Done +- Business rationale or problem solved +- Technical justification if relevant +- Link to issues/ADRs if applicable + +### How It Was Done +- Key implementation details +- Tools/techniques used +- Challenges overcome + +### Current Status +- ✅ Completed and validated +- ⏳ In progress - next steps listed +- ❌ Blocked - specify what's needed + +### References +- Issue: #[number] +- ADR: [adr/XXXX](adr/XXXX.md) +- Commit: [hash](link) +- PR: #[number](link) +``` + +## 🚀 Commands + +### Add Changelog Entry + +```bash +skill changelog-manager add-entry \ + --date "$(date +%Y-%m-%d)" \ + --description "Brief description of work" \ + --status "completed" \ + --what "- Implemented feature X\n- Fixed issue Y\n- Updated documentation Z" \ + --why "Solves problem A\nImproves metric B" \ + --how "Used tool C\nApplied pattern D" \ + --references "#42,adr/0001.md,commit abc123" +``` + +**Arguments:** +- `--date`: Entry date (default: today) +- `--description`: Brief summary (5-10 words) +- `--status`: completed, in_progress, or blocked +- `--what`: Bullet points of what was done +- `--why`: Rationale and business value +- `--how`: Implementation approach +- `--references`: Related issues, ADRs, commits + +### Validate Changelog Entry + +```bash +skill changelog-manager validate-entry \ + --file AGENT_CHANGELOG.md \ + --checks "format,content,references" +``` + +**Checks:** +- `format`: Proper markdown structure +- `content`: Relevant information included +- `references`: Valid links to issues/ADRs +- `compact`: No unnecessary details + +### Find Related Entries + +```bash +skill changelog-manager find-related \ + --file AGENT_CHANGELOG.md \ + --query "workflow optimization" \ + --output related-entries.md +``` + +### Update Entry Status + +```bash +skill changelog-manager update-status \ + --file AGENT_CHANGELOG.md \ + --date "2026-04-06" \ + --status "completed" \ + --note "Validated in production" +``` + +## 📚 Best Practices + +### 1. Keep It Compact +```markdown +❌ Too verbose: +"On April 6, 2026, I worked on implementing a new feature that involved creating several files, modifying configuration, and testing various scenarios. The process took several hours and required careful consideration of edge cases." + +✅ Compact: +"Implemented feature X with edge case handling (3 files, 2 config changes)" +``` + +### 2. Focus on Outcomes +```markdown +❌ Task-oriented: +"Created files A, B, C" "Modified config D" "Ran tests E, F, G" + +✅ Outcome-oriented: +"Enabled feature X (3 new files, config update)" "Achieved 95% test coverage (7 new tests)" +``` + +### 3. Link to References +```markdown +❌ Vague: +"Fixed some issues" "Updated documentation" + +✅ Specific: +"Fixed #42 - CI workflow errors" "Updated adr/0001.md with lessons learned" +``` + +### 4. Use Consistent Status Indicators +```markdown +✅ Completed and validated +⏳ In progress - next steps listed +❌ Blocked - specify what's needed +🎯 Planned - future work +``` + +### 5. Update Regularly +- After each significant session +- When status changes +- When new information is available +- At least weekly for active projects + +## 📁 Workflow Integration + +### Typical Session Workflow + +```bash +# 1. Start work session +vibe start --agent dancelessonscoachprogrammer + +# 2. Do the work... +# ... implementation, testing, documentation ... + +# 3. Update changelog +skill changelog-manager add-entry \ + --description "Implement workflow optimization" \ + --status "completed" \ + --what "- Combined 4 workflows into 1\n- Reduced CI time by 40%\n- Added artifact sharing" \ + --why "Faster builds, easier maintenance" \ + --how "Used job dependencies, conditional execution" \ + --references "#2,adr/0017.md,commit abc123" + +# 4. Commit changes +git add . && git commit -m "✨ feat: optimize CI/CD workflow" +git push origin main +``` + +### Example Workflow with Changelog + +```bash +# Session: Implement feature X +vibe start --agent dancelessonscoachprogrammer + +# ... work ... + +# Update changelog +skill changelog-manager add-entry \ + --description "Add product owner agent" \ + --status "completed" \ + --what "- Created 4 supporting skills\n- Configured agent with 8 skills\n- Added interview templates" \ + --why "Automates 60% of PO workflow" \ + --how "Used skill-creator, TOML config" \ + --references "#42,adr/0008.md" + +# Verify entry +skill changelog-manager validate-entry \ + --file AGENT_CHANGELOG.md \ + --checks "format,content,references" + +# Commit +git add AGENT_CHANGELOG.md .vibe/skills/ && \ + git commit -m "✨ feat: add product owner agent system" +``` + +## 🔍 Validation Checks + +### Format Validation + +```bash +skill changelog-manager validate-format \ + --file AGENT_CHANGELOG.md +``` + +Checks for: +- ✅ Proper markdown headers +- ✅ Consistent date format (YYYY-MM-DD) +- ✅ Bullet points for lists +- ✅ Code blocks for commands +- ✅ No excessive whitespace + +### Content Validation + +```bash +skill changelog-manager validate-content \ + --file AGENT_CHANGELOG.md +``` + +Checks for: +- ✅ What/Why/How structure +- ✅ Status indicators +- ✅ References to issues/ADRs +- ✅ No implementation details +- ✅ Outcome focus + +### Reference Validation + +```bash +skill changelog-manager validate-references \ + --file AGENT_CHANGELOG.md +``` + +Checks for: +- ✅ Issue #NNN exists +- ✅ ADR files exist +- ✅ Commit hashes are valid +- ✅ Links are functional + +## 📚 References + +- [Keep a Changelog](https://keepachangelog.com/) - Standard format +- [Conventional Commits](https://www.conventionalcommits.org/) - Commit messages +- [Semantic Versioning](https://semver.org/) - Versioning +- [AGENT_CHANGELOG.md](/AGENT_CHANGELOG.md) - Project example + +See [references/](references/) for detailed guides and templates. \ No newline at end of file diff --git a/.vibe/skills/changelog-manager/references/REFERENCE.md b/.vibe/skills/changelog-manager/references/REFERENCE.md new file mode 100644 index 0000000..468ebf4 --- /dev/null +++ b/.vibe/skills/changelog-manager/references/REFERENCE.md @@ -0,0 +1,50 @@ +# changelog-manager Reference + +## Overview + +Detailed technical reference for the changelog-manager skill. + +## Key Concepts + +### [Concept 1] + +[Detailed explanation] + +### [Concept 2] + +[Detailed explanation] + +## API Reference + +### [Function/Method Name] + +**Description**: [What it does] + +**Parameters**: +- - [Type]: [Description] +- - [Type]: [Description] + +**Returns**: [Return type and description] + +**Example**: +```bash +[example usage] +``` + +## Troubleshooting + +### [Issue 1] + +**Symptoms**: [What the user sees] + +**Cause**: [Root cause] + +**Solution**: [How to fix it] + +### [Issue 2] + +**Symptoms**: [What the user sees] + +**Cause**: [Root cause] + +**Solution**: [How to fix it] diff --git a/.vibe/skills/changelog-manager/scripts/example.sh b/.vibe/skills/changelog-manager/scripts/example.sh new file mode 100755 index 0000000..ce94203 --- /dev/null +++ b/.vibe/skills/changelog-manager/scripts/example.sh @@ -0,0 +1,13 @@ +#!/bin/bash + +# Example script for changelog-manager skill + +set -e + +echo "This is an example script for the changelog-manager skill" +echo "Replace this with your actual script logic" + +# Your script implementation goes here +# Example: +# echo "Processing..." +# [command] [arguments]