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 <noreply@anthropic.com>

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
+"""
 )
 ```
 

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,

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
+1. **Progress Comments** - Parse `### Blockers` section from structured comments
-2. **Comment Keywords** - Checks for "blocked", "blocker", "waiting for"
+2. **Status Labels** - Check for `Status/Blocked` label on issue
-3. **Stale Issues** - Issues with no recent activity (>7 days)
+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