From 008187a0a4056ba73d0b8667fb4bce10fa0c0e5e Mon Sep 17 00:00:00 2001 From: lmiranda Date: Wed, 28 Jan 2026 10:43:28 -0500 Subject: [PATCH] feat(projman): add structured progress comments for real-time visibility (#232) Add structured progress comment format for agents: - Standard format with Status, Phase, Tool Calls budget - Completed/In-Progress/Blockers/Next sections - Clear examples for starting, blocked, and failed states - Guidance on when to post (every 20-30 tool calls) Update sprint-status.md: - Document how to parse progress comments - Show enhanced in-progress display with tool call tracking - Add progress comment detection to blocker analysis This enables users to see: - Real-time agent progress - Tool call budget consumption - Current phase and step - Blockers as they occur Closes #232 Co-Authored-By: Claude Opus 4.5 --- plugins/projman/agents/executor.md | 100 ++++++++++++++++++++-- plugins/projman/agents/orchestrator.md | 60 ++++++++++++- plugins/projman/commands/sprint-status.md | 52 ++++++++++- 3 files changed, 198 insertions(+), 14 deletions(-) diff --git a/plugins/projman/agents/executor.md b/plugins/projman/agents/executor.md index 49ab1b0..1ba39d8 100644 --- a/plugins/projman/agents/executor.md +++ b/plugins/projman/agents/executor.md @@ -108,31 +108,115 @@ git branch --show-current ## Your Responsibilities -### 1. Status Reporting +### 1. Status Reporting (Structured Progress) -**CRITICAL: Report your status accurately using comments.** +**CRITICAL: Post structured progress comments for visibility.** -**When starting work:** +**Standard Progress Comment Format:** +```markdown +## Progress Update +**Status:** In Progress | Blocked | Failed +**Phase:** [current phase name] +**Tool Calls:** X (budget: Y) + +### Completed +- [x] Step 1 +- [x] Step 2 + +### In Progress +- [ ] Current step (estimated: Z more calls) + +### Blockers +- None | [blocker description] + +### Next +- What happens after current step +``` + +**When to Post Progress Comments:** +- **Immediately on starting** - Post initial status +- **Every 20-30 tool calls** - Show progress +- **On phase transitions** - Moving from implementation to testing +- **When blocked or encountering errors** +- **Before budget limit** - If approaching turn limit + +**Starting Work Example:** ``` add_comment( issue_number=45, - body="🔄 **Status: In Progress**\nStarting implementation of JWT service." + body="""## Progress Update +**Status:** In Progress +**Phase:** Starting +**Tool Calls:** 5 (budget: 100) + +### Completed +- [x] Read issue and acceptance criteria +- [x] Created feature branch feat/45-jwt-service + +### In Progress +- [ ] Implementing JWT service + +### Blockers +- None + +### Next +- Create auth/jwt_service.py +- Implement core token functions +""" ) ``` -**When encountering blockers:** +**Blocked Example:** ``` add_comment( issue_number=45, - body="🚫 **Status: Blocked**\nBlocked by: [reason]\nNeeded: [what would unblock]" + body="""## Progress Update +**Status:** Blocked +**Phase:** Testing +**Tool Calls:** 67 (budget: 100) + +### Completed +- [x] Implemented jwt_service.py +- [x] Wrote unit tests + +### In Progress +- [ ] Running tests - BLOCKED + +### Blockers +- Missing PyJWT dependency in requirements.txt +- Need orchestrator to add dependency + +### Next +- Resume after blocker resolved +""" ) ``` -**When failing (errors, cannot complete):** +**Failed Example:** ``` add_comment( issue_number=45, - body="❌ **Status: Failed**\nError: [description]\nAttempted: [what was tried]\nNeeded: [investigation or help required]" + body="""## Progress Update +**Status:** Failed +**Phase:** Implementation +**Tool Calls:** 89 (budget: 100) + +### Completed +- [x] Created jwt_service.py +- [x] Implemented generate_token() + +### In Progress +- [ ] verify_token() - FAILED + +### Blockers +- Critical: Cannot decode tokens - algorithm mismatch +- Attempted: HS256, HS384, RS256 +- Error: InvalidSignatureError consistently + +### Next +- Needs human investigation +- Possible issue with secret key encoding +""" ) ``` diff --git a/plugins/projman/agents/orchestrator.md b/plugins/projman/agents/orchestrator.md index 57db621..b2f9469 100644 --- a/plugins/projman/agents/orchestrator.md +++ b/plugins/projman/agents/orchestrator.md @@ -284,11 +284,65 @@ update_issue( - Remove Status labels when closing successfully - Always add comment explaining status changes -### 5. Progress Tracking (Comment Updates) +### 5. Progress Tracking (Structured Comments) -**Monitor and Update:** +**CRITICAL: Use structured progress comments for visibility.** -**Add Progress Comments:** +**Standard Progress Comment Format:** +```markdown +## Progress Update +**Status:** In Progress | Blocked | Failed +**Phase:** [current phase name] +**Tool Calls:** X (budget: Y) + +### Completed +- [x] Step 1 +- [x] Step 2 + +### In Progress +- [ ] Current step (estimated: Z more calls) + +### Blockers +- None | [blocker description] + +### Next +- What happens after current step +``` + +**Example Progress Comment:** +``` +add_comment( + issue_number=45, + body="""## Progress Update +**Status:** In Progress +**Phase:** Implementation +**Tool Calls:** 45 (budget: 100) + +### Completed +- [x] Created auth/jwt_service.py +- [x] Implemented generate_token() +- [x] Implemented verify_token() + +### In Progress +- [ ] Writing unit tests (estimated: 20 more calls) + +### Blockers +- None + +### Next +- Run tests and fix any failures +- Commit and push +""" +) +``` + +**When to Post Progress Comments:** +- After completing each major phase (every 20-30 tool calls) +- When status changes (blocked, failed) +- When encountering unexpected issues +- Before approaching tool call budget limit + +**Simple progress updates (for minor milestones):** ``` add_comment( issue_number=45, diff --git a/plugins/projman/commands/sprint-status.md b/plugins/projman/commands/sprint-status.md index 9417fea..ccd76e1 100644 --- a/plugins/projman/commands/sprint-status.md +++ b/plugins/projman/commands/sprint-status.md @@ -79,7 +79,12 @@ Completed Issues (3): In Progress (2): #46: [Sprint 18] feat: Build login endpoint [Type/Feature, Priority/High] + Status: In Progress | Phase: Implementation | Tool Calls: 45/100 + Progress: 3/5 steps | Current: Writing validation logic + #49: [Sprint 18] test: Add auth tests [Type/Test, Priority/Medium] + Status: In Progress | Phase: Testing | Tool Calls: 30/100 + Progress: 2/4 steps | Current: Testing edge cases Ready to Start (2): #50: [Sprint 18] feat: Integrate OAuth providers [Type/Feature, Priority/Low] @@ -137,12 +142,53 @@ Show only backend issues: list_issues(labels=["Component/Backend"]) ``` +## Progress Comment Parsing + +Agents post structured progress comments in this format: + +```markdown +## Progress Update +**Status:** In Progress | Blocked | Failed +**Phase:** [current phase name] +**Tool Calls:** X (budget: Y) + +### Completed +- [x] Step 1 + +### In Progress +- [ ] Current step + +### Blockers +- None | [blocker description] +``` + +**To extract real-time progress:** +1. Fetch issue comments: `get_issue(number)` includes recent comments +2. Look for comments containing `## Progress Update` +3. Parse the **Status:** line for current state +4. Parse **Tool Calls:** for budget consumption +5. Extract blockers from `### Blockers` section + +**Progress Summary Display:** +``` +In Progress Issues: + #45: [Sprint 18] feat: JWT service + Status: In Progress | Phase: Testing | Tool Calls: 67/100 + Completed: 4/6 steps | Current: Writing unit tests + + #46: [Sprint 18] feat: Login endpoint + Status: Blocked | Phase: Implementation | Tool Calls: 23/100 + Blocker: Waiting for JWT service (#45) +``` + ## Blocker Detection The command identifies blocked issues by: -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) +1. **Progress Comments** - Parse `### Blockers` section from structured comments +2. **Status Labels** - Check for `Status/Blocked` label on issue +3. **Dependency Analysis** - Uses `list_issue_dependencies` to find unmet dependencies +4. **Comment Keywords** - Checks for "blocked", "blocker", "waiting for" +5. **Stale Issues** - Issues with no recent activity (>7 days) ## When to Use