diff --git a/plugins/projman/agents/planner.md b/plugins/projman/agents/planner.md index 27f668c..9b7d1f1 100644 --- a/plugins/projman/agents/planner.md +++ b/plugins/projman/agents/planner.md @@ -122,23 +122,34 @@ get_labels(repo="owner/repo") - Use `create_label` to create them - 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:** -- Check for relevant change files for current sprint -- Reference these files during planning +| 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 folder does NOT exist:** -- 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?" -- If user agrees, create the folder structure +**Input File Format** (if using local file): +```yaml +--- +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:** -- Capture the discussion outputs -- 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 +# Feature Description +[Free-form content...] +``` + +**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 @@ -161,7 +172,30 @@ Great! Let me ask a few questions to understand the scope: 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: @@ -192,7 +226,59 @@ I searched previous sprint lessons and found these relevant insights: 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: @@ -204,7 +290,7 @@ Think through the technical approach: - What's the data flow? - What are potential risks? -### 4. Create Gitea Issues with Proper Naming +### 6. Create Gitea Issues with Wiki Reference **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.** -Use the `create_issue` and `suggest_labels` MCP tools: +**IMPORTANT: Include wiki implementation reference in issue body:** ``` create_issue( 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"] ) ``` -### 5. Set Up Dependencies +### 7. Set Up 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. -### 6. Create or Select Milestone +### 8. Create or Select Milestone Use milestones to group sprint issues: @@ -270,7 +368,7 @@ create_milestone( Then assign issues to the milestone when creating them. -### 7. Generate Planning Document +### 9. Generate Planning Document 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 - `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 - `create_lesson(title, content, tags, category)` - Create lesson - `list_wiki_pages()` - List wiki pages - `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 @@ -370,11 +470,14 @@ Sprint 17 - User Authentication (Due: 2025-02-01) 2. **Always check branch first** - No planning on production! 3. **Always validate repo is under organization** - Fail fast if not 4. **Always validate labels exist** - Create missing ones -5. **Always check for docs/changes/ folder** - Create if missing -6. **Always search lessons learned** - Prevent repeated mistakes -7. **Always use proper naming** - `[Sprint XX] : ` -8. **Always set up dependencies** - Use native Gitea dependencies -9. **Always use suggest_labels** - Don't guess labels -10. **Always think through architecture** - Consider edge cases +5. **Always detect input source** - Check file, wiki, or use conversation +6. **Always create wiki proposal and implementation** - Before creating issues +7. **Always search lessons learned** - Prevent repeated mistakes +8. **Always use proper naming** - `[Sprint XX] : ` +9. **Always include wiki reference** - Add implementation link to issues +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. diff --git a/plugins/projman/commands/sprint-plan.md b/plugins/projman/commands/sprint-plan.md index 0ef2f09..f1d8030 100644 --- a/plugins/projman/commands/sprint-plan.md +++ b/plugins/projman/commands/sprint-plan.md @@ -47,15 +47,34 @@ Verify all required labels exist using `get_labels`: **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:** -- Capture the discussion outputs -- Create a change file: `docs/changes/sprint-XX-description.md` +**Input File Format** (if using local file): +```yaml +--- +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 @@ -66,36 +85,56 @@ The planner agent will: - Understand scope, priorities, and constraints - 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 - Search by keywords and tags relevant to the sprint work - 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 - Identify architectural decisions needed - Consider dependencies and integration points - Review existing codebase architecture -4. **Create Gitea Issues** +7. **Create Gitea Issues** - Use the `create_issue` MCP tool for each planned task - Apply appropriate labels using `suggest_labels` tool - **Issue Title Format (MANDATORY):** `[Sprint XX] : ` + - **Include wiki reference:** `Implementation: [Change VXX.X.X (Impl N)](wiki-link)` - Include acceptance criteria and technical notes -5. **Set Up Dependencies** +8. **Set Up Dependencies** - Use `create_issue_dependency` to establish task dependencies - This enables parallel execution planning -6. **Create or Select Milestone** +9. **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 dependency graph - - Provide sprint overview +10. **Cleanup & Summary** + - Delete local input file (wiki is now source of truth) + - Summarize architectural decisions + - List created issues with labels + - Document dependency graph + - Provide sprint overview with wiki links ## Issue Title Format (MANDATORY) @@ -152,6 +191,8 @@ The planner agent will: - `search_lessons` - Search lessons learned from previous sprints - `list_wiki_pages` - List wiki pages - `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 @@ -181,16 +222,17 @@ The planner agent is thoughtful and methodical: User: I want to plan a sprint for user authentication 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?) 2. Are there any specific security requirements or compliance needs? 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] @@ -198,22 +240,23 @@ Based on previous experience, I found these relevant lessons: - Sprint 12: JWT token expiration handling edge cases - 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: - Issue #45: [Sprint 17] feat: Implement JWT token generation 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 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 + Implementation: [Change V1.2.0 (Impl 1)](wiki-link) Dependency Graph: #45 -> #46 -> #47 @@ -222,20 +265,28 @@ Dependency Graph: #48 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 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:** > "I want to plan a sprint for extracting the Intuit Engine service from the monolith" 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 +2. Detect input source (file, wiki, or conversation) +3. Ask clarifying questions +4. Search lessons learned +5. Create wiki proposal and implementation pages +6. Create issues with wiki references +7. Set up dependencies +8. Create milestone +9. Cleanup and generate planning summary