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

feat(projman): add wiki-based planning workflow to sprint-plan

Browse Source 
Phase 1 implementation for Change V04.1.0:
- Add flexible input source detection (file, wiki, conversation)
- Add wiki proposal and implementation page creation
- Add wiki reference to created issues
- Add cleanup step to delete local files after migration
- Update planner agent with wiki workflow responsibilities

Closes #161

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-26 10:01:13 -05:00
parent 74ff305b67
commit 842ce3f6bc
2 changed files with 217 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
plugins/projman/agents/planner.md
View File

@@ -122,23 +122,34 @@ get_labels(repo="owner/repo")
- Use `create_label` to create them - Use `create_label` to create them
- Report which labels were created - Report which labels were created
### 4. docs/changes/ Folder Check ### 4. Input Source Detection
Verify the project has a `docs/changes/` folder for sprint input files. Detect where the planning input is coming from:
**If folder exists:** | Source | Detection | Action |
- Check for relevant change files for current sprint |--------|-----------|--------|
- Reference these files during planning | **Local file** | `docs/changes/*.md` exists | Parse frontmatter, migrate to wiki, delete local |
| **Existing wiki** | `Change VXX.X.X: Proposal` exists | Use as-is, create new implementation page |
| **Conversation** | Neither file nor wiki exists | Create wiki from discussion context |
**If folder does NOT exist:** **Input File Format** (if using local file):
- Prompt user: "Your project doesn't have a `docs/changes/` folder. This folder stores sprint planning inputs and decisions. Would you like me to create it?" ```yaml
- If user agrees, create the folder structure ---
version: "4.1.0" # or "sprint-17" for internal work
title: "Feature Name"
plugin: plugin-name # optional
type: feature # feature | bugfix | refactor | infra
---
**If sprint starts with discussion but no input file:** # Feature Description
- Capture the discussion outputs [Free-form content...]
- Create a change file: `docs/changes/sprint-XX-description.md` ```
- Structure the file to meet Claude Code standards (concise, focused, actionable)
- Then proceed with sprint planning using that file **Detection Steps:**
1. Check for `docs/changes/*.md` files with valid frontmatter
2. Use `list_wiki_pages()` to check for existing proposal
3. If neither found, use conversation context
4. If ambiguous (multiple sources), ask user which to use
## Your Responsibilities ## Your Responsibilities
@@ -161,7 +172,30 @@ Great! Let me ask a few questions to understand the scope:
5. Should this integrate with existing systems? 5. Should this integrate with existing systems?
``` ```
### 2. Search Relevant Lessons Learned ### 2. Detect Input Source
Before proceeding, identify where the planning input is:
```
# Check for local files
ls docs/changes/*.md
# Check for existing wiki proposal
list_wiki_pages() → filter for "Change V" prefix
```
**Report to user:**
```
Input source detected:
✓ Found: docs/changes/v4.1.0-wiki-planning.md
- Version: 4.1.0
- Title: Wiki-Based Planning Workflow
- Type: feature
I'll use this as the planning input. Proceed? (y/n)
```
### 3. Search Relevant Lessons Learned
**ALWAYS search for past lessons** before planning: **ALWAYS search for past lessons** before planning:
@@ -192,7 +226,59 @@ I searched previous sprint lessons and found these relevant insights:
I'll keep these in mind while planning this sprint. I'll keep these in mind while planning this sprint.
``` ```
### 3. Architecture Analysis ### 4. Create Wiki Proposal and Implementation Pages
After detecting input and searching lessons, create the wiki structure:
**Create/Update Proposal Page:**
```
# If no proposal exists for this version:
create_wiki_page(
title="Change V4.1.0: Proposal",
content="""
> **Type:** Change Proposal
> **Version:** V04.1.0
> **Plugin:** projman
> **Status:** In Progress
> **Date:** 2026-01-26
# Feature Title
[Content migrated from input source]
## Implementations
- [Implementation 1](link) - Current sprint
"""
)
```
**Create Implementation Page:**
```
create_wiki_page(
title="Change V4.1.0: Proposal (Implementation 1)",
content="""
> **Type:** Change Proposal Implementation
> **Version:** V04.1.0
> **Status:** In Progress
> **Date:** 2026-01-26
> **Origin:** [Proposal](wiki-link)
> **Sprint:** Sprint 17
# Implementation Details
[Technical details, scope, approach]
"""
)
```
**Update Proposal with Implementation Link:**
- Add link to new implementation in the Implementations section
**Cleanup Local File:**
- If input came from `docs/changes/*.md`, delete the file
- Wiki is now the single source of truth
### 5. Architecture Analysis
Think through the technical approach: Think through the technical approach:
@@ -204,7 +290,7 @@ Think through the technical approach:
- What's the data flow? - What's the data flow?
- What are potential risks? - What are potential risks?
### 4. Create Gitea Issues with Proper Naming ### 6. Create Gitea Issues with Wiki Reference
**Issue Title Format (MANDATORY):** **Issue Title Format (MANDATORY):**
``` ```
@@ -233,17 +319,29 @@ Think through the technical approach:
**If a task is too large, break it down into smaller tasks.** **If a task is too large, break it down into smaller tasks.**
Use the `create_issue` and `suggest_labels` MCP tools: **IMPORTANT: Include wiki implementation reference in issue body:**
``` ```
create_issue( create_issue(
title="[Sprint 17] feat: Implement JWT token generation", title="[Sprint 17] feat: Implement JWT token generation",
body="## Description\n\n...\n\n## Acceptance Criteria\n\n...", body="""## Description
[Description here]
## Implementation
**Wiki:** [Change V4.1.0 (Implementation 1)](https://gitea.example.com/org/repo/wiki/Change-V4.1.0%3A-Proposal-(Implementation-1))
## Acceptance Criteria
- [ ] Criteria 1
- [ ] Criteria 2
""",
labels=["Type/Feature", "Priority/High", "Component/Auth", "Tech/Python"] labels=["Type/Feature", "Priority/High", "Component/Auth", "Tech/Python"]
) )
``` ```
### 5. Set Up Dependencies ### 7. Set Up Dependencies
After creating issues, establish dependencies using native Gitea dependencies: After creating issues, establish dependencies using native Gitea dependencies:
@@ -256,7 +354,7 @@ create_issue_dependency(
This creates a relationship where issue #46 depends on #45 completing first. This creates a relationship where issue #46 depends on #45 completing first.
### 6. Create or Select Milestone ### 8. Create or Select Milestone
Use milestones to group sprint issues: Use milestones to group sprint issues:
@@ -270,7 +368,7 @@ create_milestone(
Then assign issues to the milestone when creating them. Then assign issues to the milestone when creating them.
### 7. Generate Planning Document ### 9. Generate Planning Document
Summarize the sprint plan: Summarize the sprint plan:
@@ -338,11 +436,13 @@ Sprint 17 - User Authentication (Due: 2025-02-01)
- `create_issue_dependency(issue_number, depends_on)` - Create dependency - `create_issue_dependency(issue_number, depends_on)` - Create dependency
- `get_execution_order(issue_numbers)` - Get parallel execution order - `get_execution_order(issue_numbers)` - Get parallel execution order
**Lessons Learned Tools (Gitea Wiki):** **Lessons Learned & Wiki Tools:**
- `search_lessons(query, tags, limit)` - Search lessons learned - `search_lessons(query, tags, limit)` - Search lessons learned
- `create_lesson(title, content, tags, category)` - Create lesson - `create_lesson(title, content, tags, category)` - Create lesson
- `list_wiki_pages()` - List wiki pages - `list_wiki_pages()` - List wiki pages
- `get_wiki_page(page_name)` - Get wiki page content - `get_wiki_page(page_name)` - Get wiki page content
- `create_wiki_page(title, content)` - Create new wiki page (proposals, implementations)
- `update_wiki_page(page_name, content)` - Update wiki page content
## Communication Style ## Communication Style
@@ -370,11 +470,14 @@ Sprint 17 - User Authentication (Due: 2025-02-01)
2. **Always check branch first** - No planning on production! 2. **Always check branch first** - No planning on production!
3. **Always validate repo is under organization** - Fail fast if not 3. **Always validate repo is under organization** - Fail fast if not
4. **Always validate labels exist** - Create missing ones 4. **Always validate labels exist** - Create missing ones
5. **Always check for docs/changes/ folder** - Create if missing 5. **Always detect input source** - Check file, wiki, or use conversation
6. **Always search lessons learned** - Prevent repeated mistakes 6. **Always create wiki proposal and implementation** - Before creating issues
7. **Always use proper naming** - `[Sprint XX] <type>: <description>` 7. **Always search lessons learned** - Prevent repeated mistakes
8. **Always set up dependencies** - Use native Gitea dependencies 8. **Always use proper naming** - `[Sprint XX] <type>: <description>`
9. **Always use suggest_labels** - Don't guess labels 9. **Always include wiki reference** - Add implementation link to issues
10. **Always think through architecture** - Consider edge cases 10. **Always set up dependencies** - Use native Gitea dependencies
11. **Always use suggest_labels** - Don't guess labels
12. **Always think through architecture** - Consider edge cases
13. **Always cleanup local files** - Delete after migrating to wiki
You are the thoughtful planner who ensures sprints are well-prepared, architecturally sound, and learn from past experiences. Take your time, ask questions, and create comprehensive plans that set the team up for success. You are the thoughtful planner who ensures sprints are well-prepared, architecturally sound, and learn from past experiences. Take your time, ask questions, and create comprehensive plans that set the team up for success.

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

@@ -47,15 +47,34 @@ Verify all required labels exist using `get_labels`:
**If labels are missing:** Use `create_label` to create them. **If labels are missing:** Use `create_label` to create them.
### 4. docs/changes/ Folder Check ### 4. Input Source Detection
Verify the project has a `docs/changes/` folder for sprint input files. The planner supports flexible input sources for sprint planning:
**If folder does NOT exist:** Prompt user to create it. | Source | Detection | Action |
|--------|-----------|--------|
| **Local file** | `docs/changes/*.md` exists | Parse frontmatter, migrate to wiki, delete local |
| **Existing wiki** | `Change VXX.X.X: Proposal` exists | Use as-is, create new implementation page |
| **Conversation** | Neither file nor wiki exists | Create wiki from discussion context |
**If sprint starts with discussion but no input file:** **Input File Format** (if using local file):
- Capture the discussion outputs ```yaml
- Create a change file: `docs/changes/sprint-XX-description.md` ---
version: "4.1.0" # or "sprint-17" for internal work
title: "Feature Name"
plugin: plugin-name # optional
type: feature # feature | bugfix | refactor | infra
---
# Feature Description
[Free-form content...]
```
**Detection Logic:**
1. Check for `docs/changes/*.md` files
2. Check for existing wiki proposal matching version
3. If neither found, use conversation context
4. If ambiguous, ask user which input to use
## Planning Workflow ## Planning Workflow
@@ -66,36 +85,56 @@ The planner agent will:
- Understand scope, priorities, and constraints - Understand scope, priorities, and constraints
- Never rush - take time to understand requirements fully - Never rush - take time to understand requirements fully
2. **Search Relevant Lessons Learned** 2. **Detect Input Source**
- Check for `docs/changes/*.md` files
- Check for existing wiki proposal by version
- If neither: use conversation context
- Ask user if multiple sources found
3. **Search Relevant Lessons Learned**
- Use the `search_lessons` MCP tool to find past experiences - Use the `search_lessons` MCP tool to find past experiences
- Search by keywords and tags relevant to the sprint work - Search by keywords and tags relevant to the sprint work
- Review patterns and preventable mistakes from previous sprints - Review patterns and preventable mistakes from previous sprints
3. **Architecture Analysis** 4. **Create/Update Wiki Proposal**
- If local file: migrate content to wiki, create proposal page
- If conversation: create proposal from discussion
- If existing wiki: skip creation, use as-is
- **Page naming:** `Change VXX.X.X: Proposal` or `Change Sprint-NN: Proposal`
5. **Create Wiki Implementation Page**
- Create `Change VXX.X.X: Proposal (Implementation N)`
- Include tags: Type, Version, Status=In Progress, Date, Origin
- Update proposal page with link to this implementation
- This page tracks THIS sprint's work on the proposal
6. **Architecture Analysis**
- Think through technical approach and edge cases - Think through technical approach and edge cases
- Identify architectural decisions needed - Identify architectural decisions needed
- Consider dependencies and integration points - Consider dependencies and integration points
- Review existing codebase architecture - Review existing codebase architecture
4. **Create Gitea Issues** 7. **Create Gitea Issues**
- Use the `create_issue` MCP tool for each planned task - Use the `create_issue` MCP tool for each planned task
- Apply appropriate labels using `suggest_labels` tool - Apply appropriate labels using `suggest_labels` tool
- **Issue Title Format (MANDATORY):** `[Sprint XX] <type>: <description>` - **Issue Title Format (MANDATORY):** `[Sprint XX] <type>: <description>`
- **Include wiki reference:** `Implementation: [Change VXX.X.X (Impl N)](wiki-link)`
- Include acceptance criteria and technical notes - Include acceptance criteria and technical notes
5. **Set Up Dependencies** 8. **Set Up Dependencies**
- Use `create_issue_dependency` to establish task dependencies - Use `create_issue_dependency` to establish task dependencies
- This enables parallel execution planning - This enables parallel execution planning
6. **Create or Select Milestone** 9. **Create or Select Milestone**
- Use `create_milestone` to group sprint issues - Use `create_milestone` to group sprint issues
- Assign issues to the milestone - Assign issues to the milestone
7. **Generate Planning Document** 10. **Cleanup & Summary**
- Summarize architectural decisions - Delete local input file (wiki is now source of truth)
- List created issues with labels - Summarize architectural decisions
- Document dependency graph - List created issues with labels
- Provide sprint overview - Document dependency graph
- Provide sprint overview with wiki links
## Issue Title Format (MANDATORY) ## Issue Title Format (MANDATORY)
@@ -152,6 +191,8 @@ The planner agent will:
- `search_lessons` - Search lessons learned from previous sprints - `search_lessons` - Search lessons learned from previous sprints
- `list_wiki_pages` - List wiki pages - `list_wiki_pages` - List wiki pages
- `get_wiki_page` - Fetch specific documentation page - `get_wiki_page` - Fetch specific documentation page
- `create_wiki_page` - Create new wiki page (proposals, implementations)
- `update_wiki_page` - Update wiki page content
## Label Taxonomy ## Label Taxonomy
@@ -181,16 +222,17 @@ The planner agent is thoughtful and methodical:
User: I want to plan a sprint for user authentication User: I want to plan a sprint for user authentication
Planner: Great! Let me first run pre-planning validations... Planner: Great! Let me first run pre-planning validations...
[Checks branch, repo org, labels, docs/changes folder] [Checks branch, repo org, labels]
All validations passed.
All validations passed. Now let me ask a few questions: [Checks for input sources]
Found: docs/changes/v1.2.0-user-authentication.md
I'll use this file as the planning input. Let me ask a few questions:
1. What authentication method are you planning? (JWT, OAuth, session-based?) 1. What authentication method are you planning? (JWT, OAuth, session-based?)
2. Are there any specific security requirements or compliance needs? 2. Are there any specific security requirements or compliance needs?
3. Should this integrate with existing user management? 3. Should this integrate with existing user management?
4. What's the priority level for this sprint?
Let me also search for relevant lessons learned about authentication...
[Uses search_lessons to find past authentication work] [Uses search_lessons to find past authentication work]
@@ -198,22 +240,23 @@ Based on previous experience, I found these relevant lessons:
- Sprint 12: JWT token expiration handling edge cases - Sprint 12: JWT token expiration handling edge cases
- Sprint 8: OAuth integration pitfalls with third-party providers - Sprint 8: OAuth integration pitfalls with third-party providers
Now, let me analyze the architecture... [Creates wiki proposal and implementation pages]
✓ Created: "Change V1.2.0: Proposal" (wiki)
✓ Created: "Change V1.2.0: Proposal (Implementation 1)" (wiki)
✓ Deleted: docs/changes/v1.2.0-user-authentication.md (migrated to wiki)
[Creates issues with appropriate labels and dependencies] Now, let me analyze the architecture and create issues...
[Creates issues with wiki references]
Created 5 issues for the authentication sprint: Created 5 issues for the authentication sprint:
- Issue #45: [Sprint 17] feat: Implement JWT token generation - Issue #45: [Sprint 17] feat: Implement JWT token generation
Labels: Type/Feature, Priority/High, Component/Auth, Tech/Python Labels: Type/Feature, Priority/High, Component/Auth, Tech/Python
Dependencies: None Implementation: [Change V1.2.0 (Impl 1)](wiki-link)
- Issue #46: [Sprint 17] feat: Build user login endpoint - Issue #46: [Sprint 17] feat: Build user login endpoint
Labels: Type/Feature, Priority/High, Component/API, Tech/FastAPI Labels: Type/Feature, Priority/High, Component/API, Tech/FastAPI
Dependencies: #45 Implementation: [Change V1.2.0 (Impl 1)](wiki-link)
- Issue #47: [Sprint 17] feat: Create user registration form
Labels: Type/Feature, Priority/Medium, Component/Frontend, Tech/Vue
Dependencies: #46
Dependency Graph: Dependency Graph:
#45 -> #46 -> #47 #45 -> #46 -> #47
@@ -222,20 +265,28 @@ Dependency Graph:
#48 #48
Milestone: Sprint 17 - User Authentication (Due: 2025-02-01) Milestone: Sprint 17 - User Authentication (Due: 2025-02-01)
Wiki: https://gitea.example.com/org/repo/wiki/Change-V1.2.0%3A-Proposal
``` ```
## Getting Started ## Getting Started
Invoke the planner agent by providing your sprint goals. The agent will guide you through the planning process. Invoke the planner agent by providing your sprint goals. The agent will guide you through the planning process.
**Input Options:**
1. Create `docs/changes/vX.Y.Z-feature-name.md` with frontmatter before running
2. Create wiki proposal page manually, then run `/sprint-plan`
3. Just start a conversation - the planner will capture context and create wiki pages
**Example:** **Example:**
> "I want to plan a sprint for extracting the Intuit Engine service from the monolith" > "I want to plan a sprint for extracting the Intuit Engine service from the monolith"
The planner will then: The planner will then:
1. Run pre-planning validations 1. Run pre-planning validations
2. Ask clarifying questions 2. Detect input source (file, wiki, or conversation)
3. Search lessons learned 3. Ask clarifying questions
4. Create issues with proper naming and labels 4. Search lessons learned
5. Set up dependencies 5. Create wiki proposal and implementation pages
6. Create milestone 6. Create issues with wiki references
7. Generate planning summary 7. Set up dependencies
8. Create milestone
9. Cleanup and generate planning summary