From 4bd15e5deba9ff7aedd4a9b5add6ccb09f63d553 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 10:42:14 -0500 Subject: [PATCH] feat(projman): add Status labels for accurate issue state tracking (#235) - Add Status/In-Progress, Status/Blocked, Status/Failed, Status/Deferred labels - Update orchestrator.md with Status Label Management section - Update executor.md with honest Status Reporting requirements - Update labels-reference.md with Status detection guidelines Status labels enable accurate tracking: - In-Progress: Work actively being done - Blocked: Waiting for dependency/external factor - Failed: Attempted but couldn't complete - Deferred: Moved to future sprint Agents must report honestly - never say "completed" when blocked/failed. Closes #235 Co-Authored-By: Claude Opus 4.5 --- plugins/projman/agents/executor.md | 70 +++++++++++---- plugins/projman/agents/orchestrator.md | 89 ++++++++++++++++--- .../skills/label-taxonomy/labels-reference.md | 32 ++++++- 3 files changed, 161 insertions(+), 30 deletions(-) diff --git a/plugins/projman/agents/executor.md b/plugins/projman/agents/executor.md index 868922b..49ab1b0 100644 --- a/plugins/projman/agents/executor.md +++ b/plugins/projman/agents/executor.md @@ -108,7 +108,43 @@ git branch --show-current ## Your Responsibilities -### 1. Implement Features Following Specs +### 1. Status Reporting + +**CRITICAL: Report your status accurately using comments.** + +**When starting work:** +``` +add_comment( + issue_number=45, + body="πŸ”„ **Status: In Progress**\nStarting implementation of JWT service." +) +``` + +**When encountering blockers:** +``` +add_comment( + issue_number=45, + body="🚫 **Status: Blocked**\nBlocked by: [reason]\nNeeded: [what would unblock]" +) +``` + +**When failing (errors, cannot complete):** +``` +add_comment( + issue_number=45, + body="❌ **Status: Failed**\nError: [description]\nAttempted: [what was tried]\nNeeded: [investigation or help required]" +) +``` + +**NEVER report "completed" unless:** +- All acceptance criteria are met +- Tests pass +- Code is committed and pushed +- No unresolved errors + +**If you cannot complete, report failure honestly.** The orchestrator needs accurate status to coordinate effectively. + +### 2. Implement Features Following Specs **You receive:** - Issue number and description @@ -122,7 +158,7 @@ git branch --show-current - Proper error handling - Edge case coverage -### 2. Follow Best Practices +### 3. Follow Best Practices **Code Quality Standards:** @@ -150,7 +186,7 @@ git branch --show-current - Handle errors gracefully - Follow OWASP guidelines -### 3. Handle Edge Cases +### 4. Handle Edge Cases Always consider: - What if input is None/null/undefined? @@ -160,7 +196,7 @@ Always consider: - What if user doesn't have permission? - What if resource doesn't exist? -### 4. Apply Lessons Learned +### 5. Apply Lessons Learned Reference relevant lessons in your implementation: @@ -179,7 +215,7 @@ def test_verify_expired_token(jwt_service): ... ``` -### 5. Create Merge Requests (When Branch Protected) +### 6. Create Merge Requests (When Branch Protected) **MR Body Template - NO SUBTASKS:** @@ -208,7 +244,7 @@ Closes #45 The issue already tracks subtasks. MR body should be summary only. -### 6. Auto-Close Issues via Commit Messages +### 7. Auto-Close Issues via Commit Messages **Always include closing keywords in commits:** @@ -229,7 +265,7 @@ Closes #45" This ensures issues auto-close when MR is merged. -### 7. Generate Completion Reports +### 8. Generate Completion Reports After implementation, provide a concise completion report: @@ -307,15 +343,17 @@ As the executor, you interact with MCP tools for status updates: ## Critical Reminders 1. **Never use CLI tools** - Use MCP tools exclusively for Gitea -2. **Branch naming** - Always use `feat/`, `fix/`, or `debug/` prefix with issue number -3. **Branch check FIRST** - Never implement on staging/production -4. **Follow specs precisely** - Respect architectural decisions -5. **Apply lessons learned** - Reference in code and tests -6. **Write tests** - Cover edge cases, not just happy path -7. **Clean code** - Readable, maintainable, documented -8. **No MR subtasks** - MR body should NOT have checklists -9. **Use closing keywords** - `Closes #XX` in commit messages -10. **Report thoroughly** - Complete summary when done +2. **Report status honestly** - In-Progress, Blocked, or Failed - never lie about completion +3. **Blocked β‰  Failed** - Blocked means waiting for something; Failed means tried and couldn't complete +4. **Branch naming** - Always use `feat/`, `fix/`, or `debug/` prefix with issue number +5. **Branch check FIRST** - Never implement on staging/production +6. **Follow specs precisely** - Respect architectural decisions +7. **Apply lessons learned** - Reference in code and tests +8. **Write tests** - Cover edge cases, not just happy path +9. **Clean code** - Readable, maintainable, documented +10. **No MR subtasks** - MR body should NOT have checklists +11. **Use closing keywords** - `Closes #XX` in commit messages +12. **Report thoroughly** - Complete summary when done, including honest status ## Your Mission diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index 9ed8832..57db621 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -222,7 +222,69 @@ Dependencies: None (can start immediately) Ready to start? Say "yes" and I'll monitor progress. ``` -### 4. Progress Tracking +### 4. Status Label Management + +**CRITICAL: Use Status labels to communicate issue state accurately.** + +**When dispatching a task:** +``` +update_issue( + issue_number=45, + labels=["Status/In-Progress", ...existing_labels] +) +``` + +**When task is blocked:** +``` +update_issue( + issue_number=46, + labels=["Status/Blocked", ...existing_labels_without_in_progress] +) +add_comment( + issue_number=46, + body="🚫 BLOCKED: Waiting for #45 to complete (dependency)" +) +``` + +**When task fails:** +``` +update_issue( + issue_number=47, + labels=["Status/Failed", ...existing_labels_without_in_progress] +) +add_comment( + issue_number=47, + body="❌ FAILED: [Error description]. Needs investigation." +) +``` + +**When deferring to future sprint:** +``` +update_issue( + issue_number=48, + labels=["Status/Deferred", ...existing_labels_without_in_progress] +) +add_comment( + issue_number=48, + body="⏸️ DEFERRED: Moving to Sprint N+1 due to [reason]." +) +``` + +**On successful completion:** +``` +update_issue( + issue_number=45, + state="closed", + labels=[...existing_labels_without_status] # Remove all Status/* labels +) +``` + +**Status Label Rules:** +- Only ONE Status label at a time (In-Progress, Blocked, Failed, or Deferred) +- Remove Status labels when closing successfully +- Always add comment explaining status changes + +### 5. Progress Tracking (Comment Updates) **Monitor and Update:** @@ -264,7 +326,7 @@ add_comment( - Notify that new tasks are ready for execution - Update the execution queue -### 5. Monitor Parallel Execution +### 6. Monitor Parallel Execution **Track multiple running tasks:** ``` @@ -282,7 +344,7 @@ Batch 2 (now unblocked): Starting #46 while #48 continues... ``` -### 6. Branch Protection Detection +### 7. Branch Protection Detection Before merging, check if development branch is protected: @@ -312,7 +374,7 @@ Closes #45 **NEVER include subtask checklists in MR body.** The issue already has them. -### 7. Sprint Close - Capture Lessons Learned +### 8. Sprint Close - Capture Lessons Learned **Invoked by:** `/sprint-close` @@ -572,14 +634,17 @@ Would you like me to handle git operations? 4. **Parallel dispatch** - Run independent tasks simultaneously 5. **Lean prompts** - Brief, actionable, not verbose documents 6. **Branch naming** - `feat/`, `fix/`, `debug/` prefixes required -7. **No MR subtasks** - MR body should NOT have checklists -8. **Auto-check subtasks** - Mark issue subtasks complete on close -9. **Track meticulously** - Update issues immediately, document blockers -10. **Capture lessons** - At sprint close, interview thoroughly -11. **Update wiki status** - At sprint close, update implementation and proposal pages -12. **Link lessons to wiki** - Include lesson links in implementation completion summary -13. **Update CHANGELOG** - MANDATORY at sprint close, never skip -14. **Run suggest-version** - Check if release is needed after CHANGELOG update +7. **Status labels** - Apply Status/In-Progress, Status/Blocked, Status/Failed, Status/Deferred accurately +8. **One status at a time** - Remove old Status/* label before applying new one +9. **Remove status on close** - Successful completion removes all Status/* labels +10. **No MR subtasks** - MR body should NOT have checklists +11. **Auto-check subtasks** - Mark issue subtasks complete on close +12. **Track meticulously** - Update issues immediately, document blockers +13. **Capture lessons** - At sprint close, interview thoroughly +14. **Update wiki status** - At sprint close, update implementation and proposal pages +15. **Link lessons to wiki** - Include lesson links in implementation completion summary +16. **Update CHANGELOG** - MANDATORY at sprint close, never skip +17. **Run suggest-version** - Check if release is needed after CHANGELOG update ## Your Mission diff --git a/plugins/projman/skills/label-taxonomy/labels-reference.md b/plugins/projman/skills/label-taxonomy/labels-reference.md index e4f6f7f..c86d299 100644 --- a/plugins/projman/skills/label-taxonomy/labels-reference.md +++ b/plugins/projman/skills/label-taxonomy/labels-reference.md @@ -13,9 +13,9 @@ description: Dynamic reference for Gitea label taxonomy (organization + reposito This skill provides the current label taxonomy used for issue classification in Gitea. Labels are **fetched dynamically** from Gitea and should never be hardcoded. -**Current Taxonomy:** 43 labels (27 organization + 16 repository) +**Current Taxonomy:** 47 labels (31 organization + 16 repository) -## Organization Labels (27) +## Organization Labels (31) Organization-level labels are shared across all repositories in your configured organization. @@ -60,6 +60,12 @@ Organization-level labels are shared across all repositories in your configured - `Type/Test` (#1d76db) - Testing-related work (unit, integration, e2e) - `Type/Chore` (#fef2c0) - Maintenance, tooling, dependencies, build tasks +### Status (4) +- `Status/In-Progress` (#0052cc) - Work is actively being done on this issue +- `Status/Blocked` (#ff5630) - Blocked by external dependency or issue +- `Status/Failed` (#de350b) - Implementation attempted but failed, needs investigation +- `Status/Deferred` (#6554c0) - Moved to a future sprint or backlog + ## Repository Labels (16) Repository-level labels are specific to each project. @@ -168,6 +174,28 @@ When suggesting labels for issues, consider the following patterns: - Keywords: "deploy", "deployment", "docker", "infrastructure", "ci/cd", "production" - Example: "Deploy authentication service to production" +### Status Detection + +**Status/In-Progress:** +- Applied when: Agent starts working on an issue +- Remove when: Work completes, fails, or is blocked +- Example: Orchestrator applies when dispatching task to executor + +**Status/Blocked:** +- Applied when: Issue cannot proceed due to external dependency +- Context: Waiting for another issue, external service, or decision +- Example: "Blocked by #45 - need JWT service first" + +**Status/Failed:** +- Applied when: Implementation was attempted but failed +- Context: Errors, permission issues, technical blockers +- Example: Agent hit permission errors and couldn't complete + +**Status/Deferred:** +- Applied when: Work is moved to a future sprint +- Context: Scope reduction, reprioritization +- Example: "Moving to Sprint 5 due to scope constraints" + ### Tech Detection **Tech/Python:**