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

refactor(projman): extract skills and consolidate commands

Browse Source 
Major refactoring of projman plugin architecture:

Skills Extraction (17 new files):
- Extracted reusable knowledge from commands and agents into skills/
- branch-security, dependency-management, git-workflow, input-detection
- issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow
- progress-tracking, repo-validation, review-checklist, runaway-detection
- setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions

Command Consolidation (17 → 12 commands):
- /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync)
- /debug: consolidates debug-report, debug-review (report/review modes)
- /test: consolidates test-check, test-gen (run/gen modes)
- /sprint-status: absorbs sprint-diagram via --diagram flag

Architecture Cleanup:
- Remove plugin-level mcp-servers/ symlinks (6 plugins)
- Remove plugin README.md files (12 files, ~2000 lines)
- Update all documentation to reflect new command structure
- Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md

Commands are now thin dispatchers (~20-50 lines) that reference skills.
Agents reference skills for domain knowledge instead of inline content.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-30 15:02:16 -05:00
parent 8fe685037e
commit 2e65b60725
70 changed files with 3450 additions and 8887 deletions
Download Patch File Download Diff File Expand all files Collapse all files

312
plugins/projman/commands/sprint-close.md
View File

@@ -1,293 +1,46 @@
---
description: Complete sprint and capture lessons learned to Gitea Wiki
agent: orchestrator
---
# Close Sprint and Capture Lessons Learned
This command completes the sprint and captures lessons learned to Gitea Wiki. **This is critical** - after 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops 2-3 times on similar issues).
## Skills Required
## Why Lessons Learned Matter
- skills/mcp-tools-reference.md
- skills/lessons-learned.md
- skills/wiki-conventions.md
- skills/progress-tracking.md
- skills/git-workflow.md
**Problem:** Without systematic lesson capture, teams repeat the same mistakes:
- Claude Code infinite loops on similar issues (happened 2-3 times)
- Same architectural mistakes (multiple occurrences)
- Forgotten optimizations (re-discovered each time)
## Purpose
**Solution:** Mandatory lessons learned capture at sprint close, searchable at sprint start.
Complete the sprint, capture lessons learned to Gitea Wiki, and update documentation. This is critical for preventing repeated mistakes across sprints.
## Sprint Close Workflow
## Invocation
The orchestrator agent will guide you through:
Run `/sprint-close` when sprint work is complete.
1. **Review Sprint Completion**
- Use `list_issues` to verify all issues are closed or moved to backlog
- Check milestone completion status
- Check for incomplete work needing carryover
- Review overall sprint goals vs. actual completion
## Workflow
2. **Capture Lessons Learned**
- What went wrong and why
- What went right and should be repeated
- Preventable repetitions to avoid in future sprints
- Technical insights and gotchas discovered
Execute the sprint close workflow:
3. **Tag for Discoverability**
- Apply relevant tags: technology, component, type of lesson
- Ensure future sprints can find these lessons via search
- Use consistent tagging for patterns
1. **Review Sprint Completion** - Verify issues closed or moved to backlog
2. **Capture Lessons Learned** - Interview user about challenges and insights
3. **Tag for Discoverability** - Apply technology, component, and pattern tags
4. **Save to Gitea Wiki** - Use `create_lesson` with metadata and implementation link
5. **Update Wiki Implementation Page** - Change status to Implemented/Partial/Failed
6. **Update Wiki Proposal Page** - Update overall status if all implementations complete
7. **New Command Verification** - Remind user new commands require session restart
8. **Update CHANGELOG** (MANDATORY) - Add changes to `[Unreleased]` section
9. **Version Check** - Run `/suggest-version` to recommend version bump
10. **Git Operations** - Commit, merge, tag, clean up branches
11. **Close Milestone** - Update milestone state to closed
4. **Save to Gitea Wiki**
- Use `create_lesson` to save lessons to Gitea Wiki
- Create lessons in project wiki under `lessons-learned/sprints/`
- Make lessons searchable for future sprints
5. **Update Wiki Implementation Page**
- Use `get_wiki_page` to fetch the current implementation page
- Update status from "In Progress" to "Implemented" (or "Partial"/"Failed")
- Add completion date
- Link to lessons learned created in step 4
- Use `update_wiki_page` to save changes
6. **Update Wiki Proposal Page**
- Check if all implementations for this proposal are complete
- If all complete: Update proposal status to "Implemented"
- If partial: Keep status as "In Progress", note completed implementations
- Add summary of what was accomplished
7. **New Command Verification** (if applicable)
- Check if this sprint added new commands or skills
- **IMPORTANT:** New commands are NOT discoverable until session restart
- If new commands were added:
- List them in sprint close notes
- Remind user: "New commands require session restart to test"
- Create verification task in next sprint or backlog
- **WHY:** Claude Code discovers skills at session start; commands added during a session won't work until restart
8. **Update CHANGELOG** (MANDATORY)
- Add all sprint changes to `[Unreleased]` section in CHANGELOG.md
- Categorize: Added, Changed, Fixed, Removed, Deprecated
- Include plugin prefix (e.g., `- **projman:** New feature`)
9. **Version Check**
- Run `/suggest-version` to analyze changes and recommend version bump
- If release warranted: run `./scripts/release.sh X.Y.Z`
- Ensures version numbers stay in sync across files
10. **Git Operations**
- Commit any remaining work (including CHANGELOG updates)
- Merge feature branches if needed
- Clean up merged branches
- Tag sprint completion (if release created)
11. **Close Milestone**
- Use `update_milestone` to close the sprint milestone
- Document final completion status
## MCP Tools Available
**Gitea Tools:**
- `list_issues` - Review sprint issues (completed and incomplete)
- `get_issue` - Get detailed issue information for retrospective
- `update_issue` - Move incomplete issues to next sprint
**Milestone Tools:**
- `get_milestone` - Get milestone status
- `update_milestone` - Close milestone
**Lessons Learned Tools (Gitea Wiki):**
- `create_lesson` - Create lessons learned entry
- `search_lessons` - Check for similar existing lessons
- `list_wiki_pages` - Check existing lessons learned
- `get_wiki_page` - Read existing lessons or implementation pages
- `update_wiki_page` - Update implementation/proposal status
## Lesson Structure
Lessons should follow this structure:
```markdown
# Sprint X - [Lesson Title]
## Metadata
- **Implementation:** [Change VXX.X.X (Impl N)](wiki-link)
- **Issues:** #45, #46, #47
- **Sprint:** Sprint X
## Context
[What were you trying to do? What was the sprint goal?]
## Problem
[What went wrong? What insight emerged? What challenge did you face?]
## Solution
[How did you solve it? What approach worked?]
## Prevention
[How can this be avoided or optimized in the future? What should future sprints know?]
## Tags
[Comma-separated tags for search: technology, component, type]
```
**IMPORTANT:** Always include the Implementation link in the Metadata section. This enables bidirectional traceability between lessons and the work that generated them.
## Example Lessons Learned
**Example 1: Technical Gotcha**
```markdown
# Sprint 16 - Claude Code Infinite Loop on Validation Errors
## Metadata
- **Implementation:** [Change V1.2.0 (Impl 1)](https://gitea.example.com/org/repo/wiki/Change-V1.2.0%3A-Proposal-(Implementation-1))
- **Issues:** #45, #46
- **Sprint:** Sprint 16
## Context
Implementing input validation for authentication API endpoints.
## Problem
Claude Code entered an infinite loop when pytest validation tests failed.
The loop occurred because the error message didn't change between attempts,
causing Claude to retry the same fix repeatedly.
## Solution
Added more descriptive error messages to validation tests that specify
exactly what value failed and why. This gave Claude clear feedback
to adjust the approach rather than retrying the same fix.
## Prevention
- Always write validation test errors with specific values and expectations
- If Claude loops, check if error messages provide unique information per failure
- Add a "loop detection" check in test output (fail after 3 identical errors)
## Tags
testing, claude-code, validation, python, pytest, debugging
```
**Example 2: Architectural Decision**
```markdown
# Sprint 14 - Extracting Services Too Early
## Metadata
- **Implementation:** [Change V2.0.0 (Impl 1)](https://gitea.example.com/org/repo/wiki/Change-V2.0.0%3A-Proposal-(Implementation-1))
- **Issues:** #32, #33, #34
- **Sprint:** Sprint 14
## Context
Planning to extract Intuit Engine service from monolith.
## Problem
Initial plan was to extract immediately without testing the API boundaries
first. This would have caused integration issues discovered late.
## Solution
Added a sprint phase to:
1. Define clear API contracts first
2. Add integration tests for the boundaries
3. THEN extract the service
Delayed extraction by one sprint but avoided major rework.
## Prevention
- Always define API contracts before service extraction
- Write integration tests FIRST, extraction SECOND
- Don't rush architectural changes - test boundaries first
## Tags
architecture, service-extraction, refactoring, api-design, planning
```
## Tagging Strategy
Use consistent tags for discoverability:
**By Technology:**
- `python`, `javascript`, `docker`, `postgresql`, `redis`, `vue`, `fastapi`
**By Component:**
- `backend`, `frontend`, `api`, `database`, `auth`, `deploy`, `testing`, `docs`
**By Type:**
- `bug`, `feature`, `refactor`, `architecture`, `performance`, `security`
**By Issue:**
- `claude-code`, `validation`, `testing`, `debugging`, `deployment`, `configuration`
**By Pattern:**
- `infinite-loop`, `edge-case`, `integration`, `boundaries`, `dependencies`
## Orchestrator's Role
The orchestrator agent will:
1. Ask probing questions about the sprint
2. Identify preventable mistakes vs. expected challenges
3. Structure lessons in the proper format
4. Suggest appropriate tags
5. Create lessons in Gitea Wiki using `create_lesson`
6. Ensure lessons are discoverable for future sprints
7. Handle git operations and milestone closure
## Example Sprint Close Session
```
User: /sprint-close
Orchestrator: Let's close the sprint and capture lessons learned.
First, let me review the sprint completion...
[Uses list_issues to check sprint status]
Sprint 18 Summary:
- 8 issues planned
- 7 completed (87.5%)
- 1 moved to backlog (#52: Deploy auth service - blocked by infra)
Great progress! Now, let's capture lessons learned.
What challenges did you face this sprint?
User: Claude Code got stuck in a loop when pytest validation tests failed
Orchestrator: That's a valuable lesson - this prevents future frustration.
Let me ask some clarifying questions:
1. What caused the loop? (Same error message repeated?)
2. How did you break out of it?
3. What would prevent this in future sprints?
[After gathering details]
I'll create this lesson with tags: testing, claude-code, validation, python, pytest, debugging
[Uses create_lesson to save to Gitea Wiki]
Lesson created: "Sprint 18 - Claude Code Infinite Loop on Validation Errors"
Saved to Gitea Wiki with appropriate tags.
Any other lessons from this sprint?
User: Yes, we discovered that JWT token refresh needs special handling
Orchestrator: Excellent - let's capture that too...
[Continues capturing lessons]
All lessons captured! They'll be searchable when planning future sprints.
Would you like me to handle git operations?
- Commit any remaining changes
- Merge feature branches to development
- Tag sprint completion (v0.18.0)
- Clean up merged branches
- Close milestone
[Y/n]
```
**Don't skip lessons learned!** Future sprints will benefit from captured insights.
## Visual Output
When executing this command, display the plugin header:
```
╔══════════════════════════════════════════════════════════════════╗
║ 📋 PROJMAN ║
@@ -295,18 +48,3 @@ When executing this command, display the plugin header:
║ [Sprint Name] ║
╚══════════════════════════════════════════════════════════════════╝
```
Replace `[Sprint Name]` with the actual sprint/milestone name.
Then proceed with the sprint close workflow.
## Getting Started
Simply run `/sprint-close` when your sprint is complete. The orchestrator will guide you through:
1. Sprint review
2. Lessons learned capture
3. Gitea Wiki updates
4. Git operations
5. Milestone closure
**Don't skip this step!** Future sprints will thank you for capturing these insights.