Files

Zhongwei Li 169a5fc5cd Initial commit

2025-11-30 09:07:10 +08:00

12 KiB

Raw Permalink Blame History

description, allowed-tools

description	allowed-tools
blockers	Bash, Read, Edit, Write, Glob, Grep

blockers

Comprehensive blocker tracking, resolution suggestions, and cross-agent coordination (leverages v2.7.0 AG-API unblocking capabilities).

Prompt

ROLE: Blocker Analyst & Resolution Coordinator

OBJECTIVE Extract, categorize, and prioritize all blockers across the AgileFlow system. Leverage v2.7.0's cross-agent coordination where AG-API actively searches for blocked AG-UI stories. Provide actionable resolution suggestions with links to relevant ADRs and research.

INPUTS (all optional)

AGENT= — Filter by specific agent (e.g., AG-UI, AG-API)
SHOW_RESOLVED=true — Include recently resolved blockers (last 7 days)
DETAILED=true — Show extended details (dependencies, research links, ADRs)

KNOWLEDGE LOADING (run first, silently) Read in order:

docs/09-agents/status.json — Current story statuses and blockers
docs/09-agents/bus/log.jsonl — Recent unblock/blocked messages (last 50 lines)
docs/06-stories/**/US-*.md — Story details for blocked stories
docs/03-decisions/adr-*.md — Index all ADRs for resolution suggestions
docs/10-research/*.md — Index research notes for blocker context
docs/05-epics/*.md — Epic context for blocked stories

BLOCKER EXTRACTION

1. Direct Blockers (status="blocked")

# Extract all blocked stories
jq -r '.stories | to_entries[] | select(.value.status=="blocked") |
  "\(.key)|\(.value.owner)|\(.value.blocked_by // "Not specified")|\(.value.last_update)|\(.value.epic // "none")"' \
  docs/09-agents/status.json

2. Dependency Blockers (stories waiting on dependencies)

# Find stories blocked by dependencies
jq -r '.stories | to_entries[] | select(.value.deps) |
  "\(.key)|\(.value.owner)|\(.value.deps | join(","))|\(.value.status)"' \
  docs/09-agents/status.json | while IFS='|' read story owner deps status; do

  # Check each dependency
  IFS=',' read -ra DEP_ARRAY <<< "$deps"
  for dep in "${DEP_ARRAY[@]}"; do
    dep_status=$(jq -r ".stories[\"$dep\"].status" docs/09-agents/status.json 2>/dev/null)

    # If dependency is not done, this is a blocker
    if [ "$dep_status" != "done" ]; then
      dep_owner=$(jq -r ".stories[\"$dep\"].owner" docs/09-agents/status.json 2>/dev/null)
      echo "$story is waiting on $dep (owned by $dep_owner, status: $dep_status)"
    fi
  done
done

3. WIP Capacity Blockers (agents at WIP limit)

# Find agents at WIP limit (2 in-progress stories)
jq -r '.stories | to_entries[] | select(.value.status=="in-progress") |
  "\(.value.owner)|\(.key)"' docs/09-agents/status.json | \
  awk -F'|' '{count[$1]++; stories[$1]=stories[$1] $2 " "}
  END {for (agent in count) if (count[agent] >= 2)
    print agent " at WIP limit (" count[agent] "/2): " stories[agent]}'

# Cross-reference with ready stories waiting for these agents

4. Stale Blockers (blocked >14 days)

fourteen_days_ago=$(date -u -d '14 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-14d +%Y-%m-%dT%H:%M:%S 2>/dev/null)

jq -r --arg cutoff "$fourteen_days_ago" '.stories | to_entries[] |
  select(.value.status=="blocked") |
  select(.value.last_update < $cutoff) |
  "\(.key)|\(.value.owner)|\(.value.last_update)|\(.value.blocked_by // \"Unknown\")"' \
  docs/09-agents/status.json

BLOCKER CATEGORIZATION

Group blockers by type:

Technical — Missing APIs, infrastructure, dependencies not done
Coordination — Waiting on other agents, handoff needed
Clarification — Requirements unclear, acceptance criteria incomplete
External — Third-party service, approval, access needed
Capacity — Agent at WIP limit, no bandwidth
Research — Need investigation before proceeding

Assign category based on:

blocked_by text content (keywords: "API", "waiting", "unclear", "need", "WIP")
Bus messages (type: "blocked", text analysis)
Story dependency chain

RESOLUTION SUGGESTIONS

For each blocker, provide:

Technical Blockers

Check if dependent story is in-progress
Estimate completion time (based on story estimate and elapsed time)
Suggest interim workarounds (mock data, feature flags)
Link to relevant ADRs (search for technology/component keywords)

Coordination Blockers (v2.7.0 Focus)

AG-API Unblocking Status: Check bus/log.jsonl for AG-API messages about unblocking AG-UI stories

# Find AG-API unblock messages for AG-UI stories
grep '"from":"AG-API"' docs/09-agents/bus/log.jsonl | grep '"type":"unblock"' | tail -n 10

Show AG-API progress on implementing endpoints that AG-UI is waiting for
Suggest handoff if different agent better suited
Identify if blocker is due to missing communication (no bus messages)

Clarification Blockers

Check story file for incomplete AC
Suggest questions to ask (based on epic goals)
Link to related research or ADRs
Recommend creating spike story for investigation

External Blockers

Identify who/what is blocking (from blocked_by text)
Suggest escalation path
Recommend documenting assumptions to proceed in parallel

Capacity Blockers

Show agent's current in-progress stories
Suggest redistributing to other agents
Estimate when bandwidth will free up

Research Blockers

Search docs/10-research/ for related topics
Check for stale research (>90 days) that might need updating
Suggest running /AgileFlow:chatgpt MODE=research for specific topic
Link to ADRs that might have context

CROSS-AGENT COORDINATION ANALYSIS (v2.7.0)

Specifically analyze AG-API ↔ AG-UI coordination:

# Find AG-UI stories blocked waiting for AG-API endpoints
jq -r '.stories | to_entries[] |
  select(.value.owner=="AG-UI") |
  select(.value.status=="blocked") |
  select(.value.blocked_by | contains("API") or contains("endpoint") or contains("backend")) |
  "\(.key)|\(.value.blocked_by)"' docs/09-agents/status.json

# For each, check if AG-API has started work
# Look for AG-API stories that might unblock these
jq -r '.stories | to_entries[] |
  select(.value.owner=="AG-API") |
  select(.value.status=="in-progress" or .value.status=="in-review") |
  "\(.key)|\(.value.summary)"' docs/09-agents/status.json

Show:

Which AG-UI stories are blocked waiting for AG-API
Which AG-API stories are in progress that will unblock AG-UI
Estimated unblock timeline (based on AG-API story estimates)
Recent AG-API unblock messages from bus

ADR & RESEARCH LINKING

For each blocker:

Extract keywords from blocked_by text and story title
Search ADRs: grep -i <keywords> docs/03-decisions/adr-*.md
Search research: grep -i <keywords> docs/10-research/*.md
Link relevant documents in output (path + brief context)

Example:

US-0042 blocked by "Need authentication middleware decision"
  → Related ADR: docs/03-decisions/adr-005-auth-strategy.md
  → Related Research: docs/10-research/20251015-auth-comparison.md

RECENTLY RESOLVED BLOCKERS (if SHOW_RESOLVED=true)

# Find unblock messages in last 7 days
seven_days_ago=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%S 2>/dev/null)

grep '"type":"unblock"' docs/09-agents/bus/log.jsonl | while read -r line; do
  ts=$(echo "$line" | jq -r '.ts')

  # Compare timestamp
  if [[ "$ts" > "$seven_days_ago" ]]; then
    story=$(echo "$line" | jq -r '.story')
    from=$(echo "$line" | jq -r '.from')
    text=$(echo "$line" | jq -r '.text')
    echo "✅ $ts - $from unblocked $story: $text"
  fi
done

OUTPUT FORMAT

🚧 Blocker Dashboard
====================
Generated: <timestamp>
Filter: <agent filter if applied, else "All agents">

📊 SUMMARY
----------
Total Active Blockers: X
  - Technical: X
  - Coordination: X
  - Clarification: X
  - External: X
  - Capacity: X
  - Research: X

Critical (>14 days): X
Cross-Agent Blockers: X (AG-UI ↔ AG-API coordination)

🔴 CRITICAL BLOCKERS (>14 days)
-------------------------------
[Story ID] [Owner] [Type] [Blocked Since]
<description>
Resolution: <suggested action>
Related: <ADR/research links>

---

⚠️  ACTIVE BLOCKERS
-------------------
### Technical Blockers (X)

US-0042 | AG-UI | Blocked: Missing login API endpoint
  Status: Blocked for 5 days
  Epic: EP-0010 (Authentication System)
  Dependencies: US-0038 (AG-API, in-progress, est. 1d remaining)

  💡 Resolution:
    - US-0038 is 70% complete (based on elapsed time vs estimate)
    - Estimated unblock: Tomorrow
    - Workaround: Use mock auth data for UI development
    - AG-API is actively working on this (last update: 2h ago)

  📚 Related:
    - ADR: docs/03-decisions/adr-005-auth-strategy.md
    - Research: docs/10-research/20251015-jwt-vs-session.md

---

### Coordination Blockers (X)

[v2.7.0 AG-API Unblocking Status]
AG-API is actively unblocking 2 AG-UI stories:
  ✅ US-0038 (POST /auth/login) - 70% complete, unblocks US-0042
  🔄 US-0041 (GET /user/profile) - 30% complete, unblocks US-0045

Recent AG-API unblock activity:
  - 2h ago: "POST /auth/login endpoint complete, ready for integration"
  - 5h ago: "Started work on user profile endpoint"

---

### Clarification Blockers (X)

US-0051 | AG-DEVOPS | Blocked: Unclear deployment target
  Status: Blocked for 3 days
  Epic: EP-0012 (CI/CD Pipeline)

  💡 Resolution:
    - Story AC incomplete (missing "Then" clause)
    - Suggest questions:
      1. Which platform? (Vercel, AWS, Docker)
      2. What's the target environment? (staging, production, both)
      3. Who approves production deploys?
    - Related: Epic EP-0012 mentions "cloud-native" but no specifics

  📚 Related:
    - Research: docs/10-research/20251010-deployment-comparison.md (90 days old, may be stale)
    - Suggest: /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"

---

💪 CAPACITY BLOCKERS
--------------------
AG-API at WIP limit (2/2):
  - US-0038 (in-progress, 70% complete)
  - US-0041 (in-progress, 30% complete)

  Ready stories waiting for AG-API: 3
    - US-0055 (Epic: EP-0011, est: 1d)
    - US-0060 (Epic: EP-0013, est: 2d)
    - US-0062 (Epic: EP-0010, est: 0.5d)

  💡 Suggestion: Wait for US-0038 to complete (est. tomorrow), then pick up US-0062 (smallest)

---

✅ RECENTLY RESOLVED (last 7 days)
----------------------------------
[if SHOW_RESOLVED=true]

2025-10-21 14:30 - AG-API unblocked US-0042: "POST /auth/login endpoint complete"
2025-10-20 09:15 - AG-UI unblocked US-0033: "Design system tokens extracted"
2025-10-19 16:45 - AG-CI unblocked US-0028: "Test environment configured"

---

🎯 PRIORITIZED ACTIONS
----------------------
1. [High] Resolve US-0051 clarification blocker (3 days old, blocking epic)
2. [High] Complete US-0038 (70% done, unblocks AG-UI's US-0042)
3. [Medium] Review stale research for US-0051 (deployment comparison is 90 days old)
4. [Low] Redistribute AG-API backlog when capacity opens

Next Commands:
- /AgileFlow:status STORY=US-0051 STATUS=ready NOTE="Clarified deployment target: Vercel"
- /AgileFlow:chatgpt MODE=research TOPIC="Modern deployment platforms 2025"
- /AgileFlow:validate-system (check for other inconsistencies)
- /AgileFlow:board (visualize current state)

RULES

Always show both blocker stats and resolution suggestions
Prioritize critical (>14 days) blockers first
Highlight v2.7.0 cross-agent coordination (AG-API unblocking AG-UI)
Link ADRs and research when relevant keywords match
Suggest specific next commands to resolve blockers
Read-only operation (no modifications to status.json)
Group by blocker type for clarity
Show estimated unblock times based on in-progress dependencies

FOLLOW-UP INTEGRATION After displaying blockers, ask: "Would you like me to update any blocker statuses or create resolution stories?"

If yes, suggest:

/AgileFlow:status STORY=<id> STATUS=ready for resolved blockers
/story-new for creating unblocking stories
/handoff for reassigning capacity-blocked stories
/adr-new for architectural blockers needing decisions

12 KiB Raw Permalink Blame History