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

feat: major improvements to projman plugin v1.0.0

Browse Source 
- Remove Wiki.js MCP server entirely
- Add wiki, milestone, and dependency tools to Gitea MCP server
- Add parallel execution support based on dependency graph
- Add mandatory pre-planning validations (org check, labels, docs/changes)
- Add CLI blocking rules to all agents (API-only)
- Add standardized task naming: [Sprint XX] <type>: <description>
- Add branch naming convention: feat/, fix/, debug/ prefixes
- Add MR body template without subtasks
- Add auto-close issues via commit keywords
- Create claude-config-maintainer plugin for CLAUDE.md optimization
- Update all sprint commands with new tools and workflows
- Update documentation to remove Wiki.js references

New MCP tools:
- Wiki: list_wiki_pages, get_wiki_page, create_wiki_page, create_lesson, search_lessons
- Milestones: list_milestones, get_milestone, create_milestone, update_milestone
- Dependencies: list_issue_dependencies, create_issue_dependency, get_execution_order
- Validation: validate_repo_org, get_branch_protection, create_label

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-19 17:10:22 -05:00
parent d84425cbb0
commit 74b28170fa
39 changed files with 3410 additions and 4023 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
plugins/projman/commands/initial-setup.md
View File

@@ -1,10 +1,10 @@
---
description: Run initial setup for support-claude-mktplace
description: Run initial setup for projman plugin
---
# Initial Setup
Run the installation script to set up the toolkit.
Run the installation script to set up the projman plugin.
## What This Does
@@ -12,7 +12,9 @@ Run the installation script to set up the toolkit.
2. Installs all dependencies
3. Creates configuration file templates
4. Validates existing configuration
5. Reports remaining manual steps
5. Validates repository organization
6. Syncs label taxonomy
7. Reports remaining manual steps
## Execution
@@ -21,13 +23,92 @@ cd ${PROJECT_ROOT}
./scripts/setup.sh
```
## Configuration Structure
The plugin uses a hybrid configuration approach:
**System-Level (credentials):**
```
~/.config/claude/gitea.env
```
Contains API credentials that work across all projects.
**Project-Level (repository/paths):**
```
project-root/.env
```
Contains project-specific settings like repository name.
## After Running
Review the output for any manual steps required:
- Configure API credentials in `~/.config/claude/`
- Run `/labels-sync` to sync Gitea labels
- Verify Wiki.js directory structure
1. **Configure API credentials** in `~/.config/claude/gitea.env`:
```
GITEA_URL=https://gitea.your-company.com
GITEA_TOKEN=your-api-token
GITEA_ORG=your-organization
```
2. **Configure project settings** in `.env`:
```
GITEA_REPO=your-repo-name
WIKIJS_PROJECT=your-project
```
3. **Run `/labels-sync`** to sync Gitea labels
4. **Verify Gitea Wiki** is accessible and has proper structure
## Pre-Flight Checks
The setup script validates:
- Repository belongs to an organization (required)
- Required label categories exist
- API credentials are valid
- Network connectivity to Gitea
## Re-Running
This command is safe to run multiple times. It will skip already-completed steps.
## MCP Server Structure
The plugin bundles these MCP servers:
```
plugins/projman/mcp-servers/
└── gitea/
├── .venv/
├── requirements.txt
└── mcp_server/
├── server.py
├── gitea_client.py
└── tools/
├── issues.py
├── labels.py
├── wiki.py
├── milestones.py
└── dependencies.py
```
## Troubleshooting
**Error: Repository not under organization**
- This plugin requires repositories to belong to a Gitea organization
- Transfer your repository to an organization or create one
**Error: Missing required labels**
- Run `/labels-sync` to create missing labels
- Or create them manually in Gitea
**Error: Cannot connect to Gitea**
- Verify `GITEA_URL` in `~/.config/claude/gitea.env`
- Check your API token has proper permissions
- Ensure network connectivity
**Error: Virtual environment creation failed**
- Ensure Python 3.8+ is installed
- Check disk space
- Try running `python -m venv .venv` manually in the MCP server directory

101
plugins/projman/commands/labels-sync.md
View File

@@ -16,19 +16,32 @@ The label taxonomy is **dynamic** - new labels may be added to Gitea over time:
## What This Command Does
1. **Fetch Current Labels** - Uses `get_labels` MCP tool to fetch all labels (org + repo)
2. **Compare with Local Reference** - Checks against `skills/label-taxonomy/labels-reference.md`
3. **Detect Changes** - Identifies new, removed, or modified labels
4. **Explain Changes** - Shows what changed and why it matters
5. **Update Reference** - Updates the local labels-reference.md file
6. **Confirm Update** - Asks for user confirmation before updating
1. **Validate Repository** - Verify repo belongs to an organization using `validate_repo_org`
2. **Fetch Current Labels** - Uses `get_labels` MCP tool to fetch all labels (org + repo)
3. **Compare with Local Reference** - Checks against `skills/label-taxonomy/labels-reference.md`
4. **Detect Changes** - Identifies new, removed, or modified labels
5. **Explain Changes** - Shows what changed and why it matters
6. **Create Missing Labels** - Uses `create_label` for required labels that don't exist
7. **Update Reference** - Updates the local labels-reference.md file
8. **Confirm Update** - Asks for user confirmation before updating
## MCP Tools Used
**Gitea Tools:**
- `get_labels` - Fetch all labels (organization + repository)
- `create_label` - Create missing required labels
- `validate_repo_org` - Verify repository belongs to organization
The command will parse the response and categorize labels by namespace and color.
## Required Label Categories
At minimum, these label categories must exist:
- **Type/***: Bug, Feature, Refactor, Documentation, Test, Chore
- **Priority/***: Low, Medium, High, Critical
- **Complexity/***: Simple, Medium, Complex
- **Efforts/***: XS, S, M, L, XL
If any required labels are missing, the command will offer to create them.
## Expected Output
@@ -36,6 +49,10 @@ The command will parse the response and categorize labels by namespace and color
Label Taxonomy Sync
===================
Validating repository organization...
Repository: bandit/your-repo-name
Organization: bandit
Fetching labels from Gitea...
Current Label Taxonomy:
@@ -46,34 +63,36 @@ Current Label Taxonomy:
Comparing with local reference...
Changes Detected:
✨ NEW: Type/Performance (org-level)
NEW: Type/Performance (org-level)
Description: Performance optimization tasks
Color: #FF6B6B
Suggestion: Add to suggestion logic for performance-related work
✨ NEW: Tech/Redis (repo-level)
NEW: Tech/Redis (repo-level)
Description: Redis-related technology
Color: #DC143C
Suggestion: Add to suggestion logic for caching and data store work
📝 MODIFIED: Priority/Critical
MODIFIED: Priority/Critical
Change: Color updated from #D73A4A to #FF0000
Impact: Visual only, no logic change needed
❌ REMOVED: Component/Legacy
REMOVED: Component/Legacy
Reason: Component deprecated and removed from codebase
Impact: Remove from suggestion logic
Required Labels Check:
Type/*: 6/6 present
Priority/*: 4/4 present
Complexity/*: 3/3 present
Efforts/*: 5/5 present
Summary:
- 2 new labels added
- 1 label modified (color only)
- 1 label removed
- Total labels: 44 → 45
Label Suggestion Logic Updates:
- Type/Performance: Suggest for keywords "optimize", "performance", "slow", "speed"
- Tech/Redis: Suggest for keywords "cache", "redis", "session", "pubsub"
- Component/Legacy: Remove from all suggestion contexts
- Total labels: 44 -> 45
- All required labels present
Update local reference file?
[Y/n]
@@ -135,9 +154,9 @@ Source: Gitea (bandit/your-repo-name)
When suggesting labels, consider:
**Type Detection:**
- Keywords "bug", "fix", "error" → Type/Bug
- Keywords "feature", "add", "implement" → Type/Feature
- Keywords "refactor", "extract", "restructure" → Type/Refactor
- Keywords "bug", "fix", "error" -> Type/Bug
- Keywords "feature", "add", "implement" -> Type/Feature
- Keywords "refactor", "extract", "restructure" -> Type/Refactor
...
```
@@ -161,6 +180,9 @@ The updated taxonomy is used by:
```
User: /labels-sync
Validating repository organization...
Repository: bandit/your-repo-name
Fetching labels from Gitea...
Current Label Taxonomy:
@@ -170,26 +192,43 @@ Current Label Taxonomy:
Comparing with local reference...
✅ No changes detected. Label taxonomy is up to date.
No changes detected. Label taxonomy is up to date.
Last synced: 2025-01-18 14:30 UTC
```
```
User: /labels-sync
Fetching labels from Gitea...
Changes Detected:
✨ NEW: Type/Performance
✨ NEW: Tech/Redis
NEW: Type/Performance
NEW: Tech/Redis
Required Labels Check:
MISSING: Complexity/Simple
MISSING: Complexity/Medium
MISSING: Complexity/Complex
Would you like me to create the missing required labels? [Y/n] y
Creating missing labels...
Created: Complexity/Simple
Created: Complexity/Medium
Created: Complexity/Complex
Update local reference file? [Y/n] y
✅ Label taxonomy updated successfully!
✅ Suggestion logic updated with new labels
Label taxonomy updated successfully!
Suggestion logic updated with new labels
New labels available for use:
- Type/Performance
- Tech/Redis
- Complexity/Simple
- Complexity/Medium
- Complexity/Complex
```
## Troubleshooting
@@ -199,6 +238,10 @@ New labels available for use:
- Verify your API token has `read:org` and `repo` permissions
- Ensure you're connected to the network
**Error: Repository is not under an organization**
- This plugin requires repositories to belong to an organization
- Transfer the repository to an organization or create one
**Error: Permission denied to update reference file**
- Check file permissions on `skills/label-taxonomy/labels-reference.md`
- Ensure you have write access to the plugin directory
@@ -210,8 +253,8 @@ New labels available for use:
## Best Practices
1. **Sync regularly** - Run monthly or when notified of label changes
1. **Sync at sprint start** - Ensure labels are current before planning
2. **Review changes** - Always review what changed before confirming
3. **Update planning** - After sync, consider if new labels affect current sprint
4. **Communicate changes** - Let team know when new labels are available
5. **Keep skill updated** - The label-taxonomy skill should match the reference file
3. **Create missing required labels** - Don't skip this step
4. **Update planning** - After sync, consider if new labels affect current sprint
5. **Communicate changes** - Let team know when new labels are available

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

@@ -1,10 +1,10 @@
---
description: Complete sprint and capture lessons learned to Wiki.js
description: Complete sprint and capture lessons learned to Gitea Wiki
---
# Close Sprint and Capture Lessons Learned
This command completes the sprint and captures lessons learned to Wiki.js. **This is critical** - after 15 sprints without lesson capture, repeated mistakes occurred (e.g., Claude Code infinite loops 2-3 times on similar issues).
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).
## Why Lessons Learned Matter
@@ -20,7 +20,8 @@ This command completes the sprint and captures lessons learned to Wiki.js. **Thi
The orchestrator agent will guide you through:
1. **Review Sprint Completion**
- Verify all issues are closed or moved to backlog
- 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
@@ -35,10 +36,9 @@ The orchestrator agent will guide you through:
- Ensure future sprints can find these lessons via search
- Use consistent tagging for patterns
4. **Update Wiki.js**
- Use `create_lesson` to save lessons to Wiki.js
- Create lessons in `/projects/{project}/lessons-learned/sprints/`
- Update INDEX.md automatically
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. **Git Operations**
@@ -47,6 +47,10 @@ The orchestrator agent will guide you through:
- Clean up merged branches
- Tag sprint completion
6. **Close Milestone**
- Use `update_milestone` to close the sprint milestone
- Document final completion status
## MCP Tools Available
**Gitea Tools:**
@@ -54,11 +58,15 @@ The orchestrator agent will guide you through:
- `get_issue` - Get detailed issue information for retrospective
- `update_issue` - Move incomplete issues to next sprint
**Wiki.js Tools:**
**Milestone Tools:**
- `get_milestone` - Get milestone status
- `update_milestone` - Close milestone
**Lessons Learned Tools (Gitea Wiki):**
- `create_lesson` - Create lessons learned entry
- `tag_lesson` - Add/update tags on lessons
- `list_pages` - Check existing lessons learned
- `update_page` - Update INDEX.md if needed
- `search_lessons` - Check for similar existing lessons
- `list_wiki_pages` - Check existing lessons learned
- `get_wiki_page` - Read existing lessons
## Lesson Structure
@@ -165,8 +173,9 @@ The orchestrator agent will:
2. Identify preventable mistakes vs. expected challenges
3. Structure lessons in the proper format
4. Suggest appropriate tags
5. Create lessons in Wiki.js using `create_lesson`
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
@@ -178,14 +187,14 @@ First, let me review the sprint completion...
[Uses list_issues to check sprint status]
Sprint 16 Summary:
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 went wrong or what challenges did you face this sprint?
What challenges did you face this sprint?
User: Claude Code got stuck in a loop when pytest validation tests failed
@@ -200,10 +209,10 @@ Let me ask some clarifying questions:
I'll create this lesson with tags: testing, claude-code, validation, python, pytest, debugging
[Uses create_lesson to save to Wiki.js]
[Uses create_lesson to save to Gitea Wiki]
Lesson created: "Sprint 16 - Claude Code Infinite Loop on Validation Errors"
Path: /projects/cuisineflow/lessons-learned/sprints/sprint-16-validation-loop.md
Lesson created: "Sprint 18 - Claude Code Infinite Loop on Validation Errors"
Saved to Gitea Wiki with appropriate tags.
Any other lessons from this sprint?
@@ -215,7 +224,14 @@ Orchestrator: Excellent - let's capture that too...
All lessons captured! They'll be searchable when planning future sprints.
Would you like me to handle git operations (merge branches, tag release)?
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]
```
## Getting Started
@@ -223,7 +239,8 @@ Would you like me to handle git operations (merge branches, tag release)?
Simply run `/sprint-close` when your sprint is complete. The orchestrator will guide you through:
1. Sprint review
2. Lessons learned capture
3. Wiki.js updates
3. Gitea Wiki updates
4. Git operations
5. Milestone closure
**Don't skip this step!** Future sprints will thank you for capturing these insights.

150
plugins/projman/commands/sprint-plan.md
View File

@@ -6,21 +6,57 @@ description: Start sprint planning with AI-guided architecture analysis and issu
You are initiating sprint planning. The planner agent will guide you through architecture analysis, ask clarifying questions, and help create well-structured Gitea issues with appropriate labels.
## Branch Detection
## CRITICAL: Pre-Planning Validations
**CRITICAL:** Before proceeding, check the current git branch:
**BEFORE PLANNING**, the planner agent performs mandatory checks:
### 1. Branch Detection
```bash
git branch --show-current
```
**Branch Requirements:**
- ✅ **Development branches** (`development`, `develop`, `feat/*`, `dev/*`): Full planning capabilities
- ⚠️ **Staging branches** (`staging`, `stage/*`): Can create issues to document needed changes, but cannot modify code
- ❌ **Production branches** (`main`, `master`, `prod/*`): READ-ONLY - no planning allowed
- **Development branches** (`development`, `develop`, `feat/*`, `dev/*`): Full planning capabilities
- **Staging branches** (`staging`, `stage/*`): Can create issues to document needed changes, but cannot modify code
- **Production branches** (`main`, `master`, `prod/*`): READ-ONLY - no planning allowed
If you are on a production or staging branch, you MUST stop and ask the user to switch to a development branch.
### 2. Repository Organization Check
Use `validate_repo_org` MCP tool to verify the repository belongs to an organization.
**If NOT an organization repository:**
```
REPOSITORY VALIDATION FAILED
This plugin requires the repository to belong to an organization, not a user.
Please transfer or create the repository under that organization.
```
### 3. Label Taxonomy Validation
Verify all required labels exist using `get_labels`:
**Required label categories:**
- Type/* (Bug, Feature, Refactor, Documentation, Test, Chore)
- Priority/* (Low, Medium, High, Critical)
- Complexity/* (Simple, Medium, Complex)
- Efforts/* (XS, S, M, L, XL)
**If labels are missing:** Use `create_label` to create them.
### 4. docs/changes/ Folder Check
Verify the project has a `docs/changes/` folder for sprint input files.
**If folder does NOT exist:** Prompt user to create it.
**If sprint starts with discussion but no input file:**
- Capture the discussion outputs
- Create a change file: `docs/changes/sprint-XX-description.md`
## Planning Workflow
The planner agent will:
@@ -44,27 +80,78 @@ The planner agent will:
4. **Create Gitea Issues**
- Use the `create_issue` MCP tool for each planned task
- Apply appropriate labels using `suggest_labels` tool
- Structure issues with clear titles and descriptions
- **Issue Title Format (MANDATORY):** `[Sprint XX] <type>: <description>`
- Include acceptance criteria and technical notes
5. **Generate Planning Document**
5. **Set Up Dependencies**
- Use `create_issue_dependency` to establish task dependencies
- This enables parallel execution planning
6. **Create or Select Milestone**
- Use `create_milestone` to group sprint issues
- Assign issues to the milestone
7. **Generate Planning Document**
- Summarize architectural decisions
- List created issues with labels
- Document assumptions and open questions
- Document dependency graph
- Provide sprint overview
## Issue Title Format (MANDATORY)
```
[Sprint XX] <type>: <description>
```
**Types:**
- `feat` - New feature
- `fix` - Bug fix
- `refactor` - Code refactoring
- `docs` - Documentation
- `test` - Test additions/changes
- `chore` - Maintenance tasks
**Examples:**
- `[Sprint 17] feat: Add user email validation`
- `[Sprint 17] fix: Resolve login timeout issue`
- `[Sprint 18] refactor: Extract authentication module`
## Task Granularity Guidelines
| Size | Scope | Example |
|------|-------|---------|
| **Small** | 1-2 hours, single file/component | Add validation to one field |
| **Medium** | Half day, multiple files, one feature | Implement new API endpoint |
| **Large** | Should be broken down | Full authentication system |
**If a task is too large, break it down into smaller tasks.**
## MCP Tools Available
**Gitea Tools:**
- `list_issues` - Review existing issues
- `get_issue` - Get detailed issue information
- `create_issue` - Create new issue with labels
- `update_issue` - Update issue
- `get_labels` - Fetch current label taxonomy
- `suggest_labels` - Get intelligent label suggestions based on context
- `create_issue` - Create new issue with labels
- `create_label` - Create missing labels
- `validate_repo_org` - Check if repo is under organization
**Wiki.js Tools:**
**Milestone Tools:**
- `list_milestones` - List milestones
- `create_milestone` - Create milestone
- `update_milestone` - Update milestone
**Dependency Tools:**
- `create_issue_dependency` - Create dependency between issues
- `list_issue_dependencies` - List dependencies for an issue
- `get_execution_order` - Get parallel execution batches
**Lessons Learned Tools (Gitea Wiki):**
- `search_lessons` - Search lessons learned from previous sprints
- `search_pages` - Search project documentation
- `get_page` - Fetch specific documentation page
- `list_wiki_pages` - List wiki pages
- `get_wiki_page` - Fetch specific documentation page
## Label Taxonomy
@@ -92,7 +179,11 @@ The planner agent is thoughtful and methodical:
```
User: I want to plan a sprint for user authentication
Planner: Great! Let me ask a few questions to understand the scope:
Planner: Great! Let me first run pre-planning validations...
[Checks branch, repo org, labels, docs/changes folder]
All validations passed. Now let me ask a few questions:
1. What authentication method are you planning? (JWT, OAuth, session-based?)
2. Are there any specific security requirements or compliance needs?
@@ -109,12 +200,28 @@ Based on previous experience, I found these relevant lessons:
Now, let me analyze the architecture...
[Creates issues with appropriate labels]
[Creates issues with appropriate labels and dependencies]
Created 5 issues for the authentication sprint:
- Issue #45: Implement JWT token generation [Type/Feature, Priority/High, Component/Auth, Tech/Python]
- Issue #46: Build user login endpoint [Type/Feature, Priority/High, Component/API, Tech/FastAPI]
...
- Issue #45: [Sprint 17] feat: Implement JWT token generation
Labels: Type/Feature, Priority/High, Component/Auth, Tech/Python
Dependencies: None
- Issue #46: [Sprint 17] feat: Build user login endpoint
Labels: Type/Feature, Priority/High, Component/API, Tech/FastAPI
Dependencies: #45
- Issue #47: [Sprint 17] feat: Create user registration form
Labels: Type/Feature, Priority/Medium, Component/Frontend, Tech/Vue
Dependencies: #46
Dependency Graph:
#45 -> #46 -> #47
|
v
#48
Milestone: Sprint 17 - User Authentication (Due: 2025-02-01)
```
## Getting Started
@@ -124,4 +231,11 @@ Invoke the planner agent by providing your sprint goals. The agent will guide yo
**Example:**
> "I want to plan a sprint for extracting the Intuit Engine service from the monolith"
The planner will then ask clarifying questions and guide you through the complete planning workflow.
The planner will then:
1. Run pre-planning validations
2. Ask clarifying questions
3. Search lessons learned
4. Create issues with proper naming and labels
5. Set up dependencies
6. Create milestone
7. Generate planning summary

201
plugins/projman/commands/sprint-start.md
View File

@@ -4,7 +4,7 @@ description: Begin sprint execution with relevant lessons learned from previous
# Start Sprint Execution
You are initiating sprint execution. The orchestrator agent will coordinate the work, search for relevant lessons learned, and guide you through the implementation process.
You are initiating sprint execution. The orchestrator agent will coordinate the work, analyze dependencies for parallel execution, search for relevant lessons learned, and guide you through the implementation process.
## Branch Detection
@@ -15,9 +15,9 @@ git branch --show-current
```
**Branch Requirements:**
- ✅ **Development branches** (`development`, `develop`, `feat/*`, `dev/*`): Full execution capabilities
- ⚠️ **Staging branches** (`staging`, `stage/*`): Can create issues to document bugs, but cannot modify code
- ❌ **Production branches** (`main`, `master`, `prod/*`): READ-ONLY - no execution allowed
- **Development branches** (`development`, `develop`, `feat/*`, `dev/*`): Full execution capabilities
- **Staging branches** (`staging`, `stage/*`): Can create issues to document bugs, but cannot modify code
- **Production branches** (`main`, `master`, `prod/*`): READ-ONLY - no execution allowed
If you are on a production or staging branch, you MUST stop and ask the user to switch to a development branch.
@@ -25,32 +25,72 @@ If you are on a production or staging branch, you MUST stop and ask the user to
The orchestrator agent will:
1. **Review Sprint Issues**
1. **Fetch Sprint Issues**
- Use `list_issues` to fetch open issues for the sprint
- Identify priorities based on labels (Priority/Critical, Priority/High, etc.)
- Understand dependencies between issues
2. **Search Relevant Lessons Learned**
2. **Analyze Dependencies and Plan Parallel Execution**
- Use `get_execution_order` to build dependency graph
- Identify batches that can be executed in parallel
- Present parallel execution plan
3. **Search Relevant Lessons Learned**
- Use `search_lessons` to find experiences from past sprints
- Search by tags matching the current sprint's technology and components
- Review patterns, gotchas, and preventable mistakes
- Present relevant lessons before starting work
3. **Identify Next Task**
- Select the highest priority task that's unblocked
- Review task details and acceptance criteria
- Check for dependencies
4. **Generate Lean Execution Prompt**
- Create concise implementation guidance (NOT full planning docs)
- Reference architectural decisions from planning phase
- Highlight relevant lessons learned
- Provide clear acceptance criteria
4. **Dispatch Tasks (Parallel When Possible)**
- For independent tasks (same batch), spawn multiple Executor agents in parallel
- For dependent tasks, execute sequentially
- Create proper branch for each task
5. **Track Progress**
- Update issue status as work progresses
- Use `add_comment` to document progress and blockers
- Identify when tasks are blocked and need attention
- Monitor when dependencies are satisfied and new tasks become unblocked
## Parallel Execution Model
The orchestrator analyzes dependencies and groups issues into parallelizable batches:
```
Parallel Execution Batches:
+---------------------------------------------------------------+
| Batch 1 (can start immediately): |
| #45 [Sprint 18] feat: Implement JWT service |
| #48 [Sprint 18] docs: Update API documentation |
+---------------------------------------------------------------+
| Batch 2 (after batch 1): |
| #46 [Sprint 18] feat: Build login endpoint (needs #45) |
| #49 [Sprint 18] test: Add auth tests (needs #45) |
+---------------------------------------------------------------+
| Batch 3 (after batch 2): |
| #47 [Sprint 18] feat: Create login form (needs #46) |
+---------------------------------------------------------------+
```
**Independent tasks in the same batch run in parallel.**
## Branch Naming Convention (MANDATORY)
When creating branches for tasks:
- Features: `feat/<issue-number>-<short-description>`
- Bug fixes: `fix/<issue-number>-<short-description>`
- Debugging: `debug/<issue-number>-<short-description>`
**Examples:**
```bash
git checkout -b feat/45-jwt-service
git checkout -b fix/46-login-timeout
git checkout -b debug/47-investigate-memory-leak
```
**Validation:**
- Issue number MUST be present
- Prefix MUST be `feat/`, `fix/`, or `debug/`
- Description should be kebab-case (lowercase, hyphens)
## MCP Tools Available
@@ -60,34 +100,54 @@ The orchestrator agent will:
- `update_issue` - Update issue status, assignee, labels
- `add_comment` - Add progress updates or blocker notes
**Wiki.js Tools:**
**Dependency Tools:**
- `list_issue_dependencies` - Get dependencies for an issue
- `get_execution_order` - Get parallel execution batches for sprint issues
**Milestone Tools:**
- `list_milestones` - List milestones
- `get_milestone` - Get milestone details
**Lessons Learned Tools (Gitea Wiki):**
- `search_lessons` - Find relevant lessons from past sprints
- `search_pages` - Search project documentation for references
- `get_page` - Fetch specific documentation (e.g., architecture decisions)
- `list_wiki_pages` - List project documentation
- `get_wiki_page` - Fetch specific documentation (e.g., architecture decisions)
## Orchestrator Personality
The orchestrator agent is concise and action-oriented:
- Generates lean execution prompts, not lengthy documents
- Tracks details meticulously (no task forgotten)
- Coordinates parallel execution based on dependencies
- Identifies blockers proactively
- Coordinates Git operations (commit, merge, cleanup)
- Manages task dependencies
- Updates documentation as work progresses
## Example Sprint Start Session
```
User: /sprint-start
Orchestrator: Starting sprint execution. Let me review open issues and relevant lessons...
Orchestrator: Starting sprint execution. Let me analyze the sprint...
[Uses list_issues to fetch sprint backlog]
Found 8 open issues for this sprint:
- Issue #45: Implement JWT token generation [Priority/High, Component/Auth]
- Issue #46: Build user login endpoint [Priority/High, Component/API]
- Issue #47: Create user registration form [Priority/Medium, Component/Frontend]
...
Found 5 open issues for this sprint.
[Uses get_execution_order to analyze dependencies]
Parallel Execution Batches:
+-----------------------------------------------+
| Batch 1 (can start immediately): |
| #45 - Implement JWT service |
| #48 - Update API documentation |
+-----------------------------------------------+
| Batch 2 (after batch 1): |
| #46 - Build login endpoint (needs #45) |
| #49 - Add auth tests (needs #45) |
+-----------------------------------------------+
| Batch 3 (after batch 2): |
| #47 - Create login form (needs #46) |
+-----------------------------------------------+
[Uses search_lessons to find relevant past experiences]
@@ -95,38 +155,53 @@ Relevant lessons learned:
- Sprint 12: "JWT Token Expiration Edge Cases" - Remember to handle token refresh
- Sprint 8: "OAuth Integration Pitfalls" - Test error handling for auth providers
[Identifies next task based on priority and dependencies]
Ready to start? I can dispatch multiple tasks in parallel.
Next task: Issue #45 - Implement JWT token generation
This is unblocked and high priority.
Dispatching Batch 1 (2 tasks in parallel):
Execution prompt:
- Create JWT token generation utility in backend/auth/jwt.py
- Use HS256 algorithm with secret from environment variable
- Include user_id, email, and expiration in payload
- Add token refresh logic (remember lesson from Sprint 12!)
- Write unit tests for token generation and validation
Task 1: #45 - Implement JWT service
Branch: feat/45-jwt-service
Executor: Starting...
Would you like me to invoke the executor agent for implementation guidance?
Task 2: #48 - Update API documentation
Branch: feat/48-api-docs
Executor: Starting...
Both tasks running in parallel. I'll monitor progress.
```
## Lessons Learned Integration
## Lean Execution Prompts
The orchestrator actively searches for and presents relevant lessons before starting work:
The orchestrator generates concise prompts (NOT verbose documents):
**Search by Technology:**
```
search_lessons(tags="python,fastapi,jwt")
```
Next Task: #45 - [Sprint 18] feat: Implement JWT token generation
**Search by Component:**
```
search_lessons(tags="authentication,api,backend")
```
Priority: High | Effort: M (1 day) | Unblocked
Branch: feat/45-jwt-service
**Search by Keywords:**
```
search_lessons(query="token expiration edge cases")
Quick Context:
- Create backend service for JWT tokens
- Use HS256 algorithm (decision from planning)
- Include user_id, email, expiration in payload
Key Actions:
1. Create auth/jwt_service.py
2. Implement generate_token(user_id, email)
3. Implement verify_token(token)
4. Add token refresh logic (Sprint 12 lesson!)
5. Write unit tests for generation/validation
Acceptance Criteria:
- Tokens generate successfully
- Token verification works
- Refresh prevents expiration issues
- Tests cover edge cases
Relevant Lessons:
Sprint 12: Handle token refresh explicitly to prevent mid-request expiration
Dependencies: None (can start immediately)
```
## Progress Tracking
@@ -145,16 +220,32 @@ update_issue(issue_number=45, state="closed")
**Document Blockers:**
```
add_comment(issue_number=46, body="Blocked: Waiting for auth database schema migration")
add_comment(issue_number=46, body="BLOCKED: Waiting for #45 to complete (dependency)")
```
**Track Parallel Execution:**
```
Parallel Execution Status:
Batch 1:
#45 - JWT service - COMPLETED (12:45)
#48 - API docs - IN PROGRESS (75%)
Batch 2 (now unblocked):
#46 - Login endpoint - READY TO START
#49 - Auth tests - READY TO START
#45 completed! #46 and #49 are now unblocked.
Starting #46 while #48 continues...
```
## Getting Started
Simply invoke `/sprint-start` and the orchestrator will:
1. Review your sprint backlog
2. Search for relevant lessons
3. Identify the next task to work on
4. Provide lean execution guidance
2. Analyze dependencies and plan parallel execution
3. Search for relevant lessons
4. Dispatch tasks (parallel when possible)
5. Track progress as you work
The orchestrator keeps you focused and ensures nothing is forgotten.
The orchestrator keeps you focused, maximizes parallelism, and ensures nothing is forgotten.

114
plugins/projman/commands/sprint-status.md
View File

@@ -4,15 +4,16 @@ description: Check current sprint progress and identify blockers
# Sprint Status Check
This command provides a quick overview of your current sprint progress, including open issues, completed work, and potential blockers.
This command provides a quick overview of your current sprint progress, including open issues, completed work, dependency status, and potential blockers.
## What This Command Does
1. **Fetch Sprint Issues** - Lists all issues with current sprint labels/milestone
2. **Categorize by Status** - Groups issues into: Open, In Progress, Blocked, Completed
3. **Identify Blockers** - Highlights issues with blocker comments or dependencies
4. **Show Progress Summary** - Provides completion percentage and velocity insights
5. **Highlight Priorities** - Shows critical and high-priority items needing attention
2. **Analyze Dependencies** - Shows dependency graph and blocked/unblocked tasks
3. **Categorize by Status** - Groups issues into: Open, In Progress, Blocked, Completed
4. **Identify Blockers** - Highlights issues with blocker comments or unmet dependencies
5. **Show Progress Summary** - Provides completion percentage and parallel execution status
6. **Highlight Priorities** - Shows critical and high-priority items needing attention
## Usage
@@ -22,53 +23,98 @@ Simply run `/sprint-status` to get a comprehensive sprint overview.
This command uses the following Gitea MCP tools:
**Issue Tools:**
- `list_issues(state="open")` - Fetch open issues
- `list_issues(state="closed")` - Fetch completed issues
- `get_issue(number)` - Get detailed issue information for blockers
**Dependency Tools:**
- `list_issue_dependencies(issue_number)` - Get dependencies for each issue
- `get_execution_order(issue_numbers)` - Get parallel execution batches
**Milestone Tools:**
- `get_milestone(milestone_id)` - Get milestone progress
## Expected Output
```
Sprint Status Report
====================
Sprint: Sprint 16 - Authentication System
Sprint: Sprint 18 - Authentication System
Milestone: Due 2025-02-01 (5 days remaining)
Date: 2025-01-18
Progress Summary:
- Total Issues: 8
- Completed: 3 (37.5%)
- In Progress: 2 (25%)
- Open: 2 (25%)
- Ready: 2 (25%)
- Blocked: 1 (12.5%)
Dependency Graph:
#45 -> #46 -> #47
|
v
#49 -> #50
Parallel Execution Status:
+-----------------------------------------------+
| Batch 1 (COMPLETED): |
| #45 - Implement JWT service |
| #48 - Update API documentation |
+-----------------------------------------------+
| Batch 2 (IN PROGRESS): |
| #46 - Build login endpoint (75%) |
| #49 - Add auth tests (50%) |
+-----------------------------------------------+
| Batch 3 (BLOCKED): |
| #47 - Create login form (waiting for #46) |
+-----------------------------------------------+
Completed Issues (3):
✅ #45: Implement JWT token generation [Type/Feature, Priority/High]
✅ #46: Build user login endpoint [Type/Feature, Priority/High]
✅ #48: Write authentication tests [Type/Test, Priority/Medium]
#45: [Sprint 18] feat: Implement JWT service [Type/Feature, Priority/High]
#48: [Sprint 18] docs: Update API documentation [Type/Docs, Priority/Medium]
#51: [Sprint 18] chore: Update dependencies [Type/Chore, Priority/Low]
In Progress (2):
🔄 #47: Create user registration form [Type/Feature, Priority/Medium]
🔄 #49: Add password reset flow [Type/Feature, Priority/Low]
#46: [Sprint 18] feat: Build login endpoint [Type/Feature, Priority/High]
#49: [Sprint 18] test: Add auth tests [Type/Test, Priority/Medium]
Open Issues (2):
📋 #50: Integrate OAuth providers [Type/Feature, Priority/Low]
📋 #51: Add email verification [Type/Feature, Priority/Medium]
Ready to Start (2):
#50: [Sprint 18] feat: Integrate OAuth providers [Type/Feature, Priority/Low]
#52: [Sprint 18] feat: Add email verification [Type/Feature, Priority/Medium]
Blocked Issues (1):
🚫 #52: Deploy auth service [Type/Deploy, Priority/High]
Blocker: Waiting for database migration approval
#47: [Sprint 18] feat: Create login form [Type/Feature, Priority/High]
Blocked by: #46 (in progress)
Priority Alerts:
⚠️ 1 high-priority item blocked: #52
✅ All critical items completed
1 high-priority item blocked: #47
All critical items completed
Recommendations:
1. Focus on unblocking #52 (Deploy auth service)
2. Continue work on #47 (User registration form)
3. Consider starting #51 (Email verification) next
1. Focus on completing #46 (Login endpoint) - unblocks #47
2. Continue parallel work on #49 (Auth tests)
3. #50 and #52 are ready - can start in parallel
```
## Dependency Analysis
The status check analyzes dependencies to show:
**Blocked Issues:**
- Issues waiting for other issues to complete
- Shows which issue is blocking and its current status
**Unblocked Issues:**
- Issues with no pending dependencies
- Ready to be picked up immediately
**Parallel Opportunities:**
- Multiple unblocked issues that can run simultaneously
- Maximizes sprint velocity
## Filtering Options
You can optionally filter the status check:
@@ -82,7 +128,7 @@ list_issues(labels=["Priority/High"])
**By Milestone:**
```
Show issues for specific sprint:
list_issues(milestone="Sprint 16")
list_issues(milestone="Sprint 18")
```
**By Component:**
@@ -94,9 +140,9 @@ list_issues(labels=["Component/Backend"])
## Blocker Detection
The command identifies blocked issues by:
1. Checking issue comments for keywords: "blocked", "blocker", "waiting for", "dependency"
2. Looking for issues with no recent activity (>7 days)
3. Identifying issues with unresolved dependencies
1. **Dependency Analysis** - Uses `list_issue_dependencies` to find unmet dependencies
2. **Comment Keywords** - Checks for "blocked", "blocker", "waiting for"
3. **Stale Issues** - Issues with no recent activity (>7 days)
## When to Use
@@ -106,6 +152,7 @@ Run `/sprint-status` when you want to:
- Check if the sprint is on track
- Identify bottlenecks or blockers
- Decide what to work on next
- See which tasks can run in parallel
## Integration with Other Commands
@@ -116,4 +163,17 @@ Run `/sprint-status` when you want to:
## Example Usage
```
User: /sprint-status
User: /sprint-status
Sprint Status Report
====================
Sprint: Sprint 18 - Authentication System
Progress: 3/8 (37.5%)
Next Actions:
1. Complete #46 - it's blocking #47
2. Start #50 or #52 - both are unblocked
Would you like me to generate execution prompts for the unblocked tasks?
```