agileflow 2.77.0 → 2.79.0

package/src/core/commands/blockers.md

@@ -1,7 +1,23 @@
 ---
 description: Track and resolve blockers with actionable suggestions
-argument-hint: [AGENT=<id>] [SHOW_RESOLVED=true] [DETAILED=true]
+argument-hint: "[AGENT=<id>] [SHOW_RESOLVED=true] [DETAILED=true]"
 model: haiku
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:blockers - Blocker analyst and resolver (read-only analysis)"
+    - "MUST read docs/09-agents/status.json (extract blockers and blocked_by)"
+    - "MUST read docs/09-agents/bus/log.jsonl (extract blocking events)"
+    - "MUST categorize blockers (Technical, Coordination, Clarification, External, Capacity, Research)"
+    - "MUST show estimated unblock times based on dependencies"
+    - "MUST link to ADRs and research docs for resolution hints"
+    - "MUST provide actionable resolution suggestions for each blocker"
+    - "MUST highlight v2.7.0 cross-agent coordination (AG-API unblocking AG-UI)"
+  state_fields:
+    - blocker_count
+    - critical_count
+    - agent_filter
+    - show_resolved
 ---
 
 # blockers
@@ -17,61 +33,164 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Purpose**: Track and resolve all blockers across AgileFlow with actionable suggestions and cross-agent coordination.
+## ⚠️ COMPACT SUMMARY - /agileflow:blockers IS ACTIVE
 
-**Key Features**:
-- Extract blockers from status.json (direct, dependency, capacity, stale)
-- Categorize by type (Technical, Coordination, Clarification, External, Capacity, Research)
-- Provide resolution suggestions with ADR/research links
-- Highlight v2.7.0 AG-API ↔ AG-UI cross-agent coordination
-- Show estimated unblock times based on in-progress dependencies
-- Display recently resolved blockers (optional)
-
-**Arguments** (all optional):
-- `AGENT`: <id> (filter by specific agent: AG-UI, AG-API, etc.)
-- `SHOW_RESOLVED`: true (include recently resolved blockers, last 7 days)
-- `DETAILED`: true (show extended details: dependencies, research links, ADRs)
-
-**Data Sources** (parsing required):
-1. `status.json` - Current story statuses and blockers (JSON parsing)
-2. `bus/log.jsonl` - Recent unblock/blocked messages (JSON parsing + timestamp filtering)
-3. Story files (`US-*.md`) - Detailed story information (YAML frontmatter parsing)
-4. ADRs (`adr-*.md`) - Architecture decisions (keyword matching)
-5. Research notes (`10-research/*.md`) - Background research (keyword matching)
-
-**Blocker Types Detected**:
-1. **Direct** - Stories with status="blocked" (extract from status.json)
-2. **Dependency** - Stories waiting on incomplete dependencies (parse frontmatter deps_on)
-3. **WIP Capacity** - Agents at WIP limit (count in-progress stories per agent)
-4. **Stale** - Blocked >14 days (timestamp comparison)
-
-**Workflow**:
-1. Extract all blockers from status.json → Parse bus/log.jsonl for recent activity
-2. Categorize by type (Technical/Coordination/Clarification/External/Capacity/Research)
-3. For each blocker: Match to ADRs/research via keyword search
-4. Generate resolution suggestions (estimated unblock time, workarounds, escalation)
-5. If SHOW_RESOLVED=true: Extract unblock messages from last 7 days
-6. Prioritize actions and display dashboard
-
-**Example Usage**:
-```bash
-/agileflow:blockers
-/agileflow:blockers AGENT=AG-UI
-/agileflow:blockers SHOW_RESOLVED=true DETAILED=true
+**CRITICAL**: You are the Blocker Analyst. This command analyzes blocking patterns (read-only).
+
+---
+
+### 🚨 RULE #1: ALWAYS Read status.json (Extract Blocker Data)
+
+Extract blockers by:
+1. Find stories with status="blocked"
+2. Find stories with dependencies not status="done"
+3. Count in-progress + in-review per agent (>2 = capacity blocker)
+4. Calculate blocking duration (last_update timestamp)
+
+### 🚨 RULE #2: ALWAYS Categorize Blockers
+
+Classify each blocker as ONE of:
+1. **Technical** - Missing APIs, infrastructure, dependencies not done
+2. **Coordination** - Waiting on other agents, handoff needed
+3. **Clarification** - Requirements unclear, AC incomplete
+4. **External** - Third-party service, approval, access needed
+5. **Capacity** - Agent at WIP limit, no bandwidth
+6. **Research** - Need investigation before proceeding
+
+### 🚨 RULE #3: ALWAYS Link to Resolution
+
+For each blocker provide:
+- Category and reason
+- Estimated unblock time (based on dependency progress)
+- ADR links (keyword search in adr-*.md)
+- Research links (keyword search in 10-research/*.md)
+- Actionable next step
+
+### 🚨 RULE #4: ALWAYS Highlight Cross-Agent Coordination
+
+Show v2.7.0 AG-API ↔ AG-UI coordination:
+- Which AG-UI stories blocked waiting for AG-API endpoints
+- Which AG-API stories in-progress that will unblock them
+- Estimated unblock timeline
+- Recent progress messages from bus log
+
+---
+
+## Key Files & Data
+
+**Input Parameters** (all optional):
 ```
+AGENT=<id>           # Filter by specific agent (e.g., AG-UI)
+SHOW_RESOLVED=true   # Include recently resolved (last 7 days)
+DETAILED=true        # Show extended details (dependencies, ADRs, research)
+```
+
+**Data Sources** (read-only):
+1. docs/09-agents/status.json - Blocker data + blocked_by field
+2. docs/09-agents/bus/log.jsonl - Blocking events + timestamps
+3. docs/06-stories/**/US-*.md - Story dependencies
+4. docs/03-decisions/adr-*.md - Architecture decisions (keyword match)
+5. docs/10-research/*.md - Research notes (keyword match)
+
+**Blocker Detection**:
+- Direct: status="blocked"
+- Dependency: deps not all status="done"
+- Capacity: in-progress + in-review count >2
+- Stale: blocked >14 days old
+
+---
+
+## Output Structure
+
+**Summary Section**:
+- Total active blockers
+- Breakdown by category (Technical, Coordination, etc.)
+- Critical count (>14 days)
+- Cross-agent coordination needs
+
+**Critical Blockers** (>14 days):
+- Listed first (highest priority)
+- Include story ID, owner, type, reason, duration
+
+**Active Blockers** (grouped by category):
+- Category heading
+- List of stories with:
+  - ID, owner, blocker type
+  - Blocker reason
+  - Estimated unblock time
+  - Related ADR/research links
+  - Actionable resolution
+
+**AG-API Coordination Status**:
+- Which AG-UI stories blocked waiting for AG-API
+- Which AG-API stories in-progress that will unblock them
+- Recent AG-API progress messages
+- Estimated unblock timeline
+
+**Recently Resolved** (if SHOW_RESOLVED=true):
+- Last 7 days of unblock events
+- Who unblocked, when, what blocker
+
+**Prioritized Actions**:
+- Ranked next steps (HIGH/MEDIUM/LOW)
+- Specific commands to resolve
+
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Modify status.json (read-only analysis)
+- Skip categorization (helps identify patterns)
+- Ignore cross-agent coordination
+- Hide stale blockers (>14 days)
+
+✅ **DO**:
+- Read status.json (no updates)
+- Categorize all blockers
+- Show AG-API unblocking progress
+- Highlight stale blockers for escalation
+
+---
+
+## Confirmation & Integration
+
+After displaying blockers:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do?",
+  "header": "Blocker Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Update blocker status", "description": "Mark blocker as resolved"},
+    {"label": "Create unblocking story", "description": "Create story to unblock"},
+    {"label": "View ADR details", "description": "See related architecture decisions"},
+    {"label": "Escalate blocker", "description": "Escalate for decision"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Integration with other commands:
+- `/status` - Update blocker statuses
+- `/story-new` - Create unblocking stories
+- `/adr-new` - Document blocker decisions
+- `/board` - Visualize blocked stories
+
+---
+
+## REMEMBER AFTER COMPACTION
 
-**Output Sections**:
-- Summary Stats (count by type, critical count)
-- Critical Blockers (stale >14 days)
-- Active Blockers (grouped by category with solutions)
-- AG-API Unblocking Status (v2.7.0 coordination)
-- Capacity Analysis (agents at WIP limit)
-- Recently Resolved (last 7 days if requested)
-- Prioritized Actions (ranked next steps)
+- Command is read-only (analyzes status.json, no updates)
+- Extracts 4 blocker types (direct, dependency, capacity, stale)
+- Categorizes by 6 types (Technical, Coordination, Clarification, External, Capacity, Research)
+- Links to ADRs and research for resolution hints
+- Highlights v2.7.0 AG-API ↔ AG-UI cross-agent coordination
+- Shows estimated unblock times and actionable next steps
+- Highlights stale blockers (>14 days) for escalation
 
-**Integration**: With `/status`, `/story-new`, `/handoff`, `/adr-new`, `/board`, `/validate-system`
 <!-- COMPACT_SUMMARY_END -->
 
 Comprehensive blocker tracking, resolution suggestions, and cross-agent coordination (leverages v2.7.0 AG-API unblocking capabilities).

package/src/core/commands/board.md

@@ -1,7 +1,23 @@
 ---
 description: Display visual kanban board with WIP limits
-argument-hint: (no arguments)
+argument-hint: "[EPIC=<id>] [OWNER=<id>] [FORMAT=ascii|markdown|html] [GROUP_BY=status|owner|epic]"
 model: haiku
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:board - Kanban board visualizer (read-only)"
+    - "MUST read docs/09-agents/status.json (do NOT modify)"
+    - "MUST organize stories by status (ready, in-progress, in-review, done, blocked)"
+    - "MUST show WIP limits (2 stories per agent)"
+    - "MUST highlight blockers and WIP violations"
+    - "MUST provide ASCII art board visualization"
+    - "MUST show statistics (throughput, velocity, completion %)"
+    - "MUST suggest next actions based on board state"
+  state_fields:
+    - epic_filter
+    - owner_filter
+    - format
+    - group_by
 ---
 
 # board
@@ -17,82 +33,133 @@ node .agileflow/scripts/obtain-context.js board
 This gathers git status, stories/epics, session state, and registers for PreCompact.
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
 
-**Command**: `board`
-**Purpose**: Generate visual kanban board from current story statuses
+## ⚠️ COMPACT SUMMARY - /agileflow:board IS ACTIVE
 
-**Quick Usage**:
+**CRITICAL**: You are the Board Visualizer. This command displays project state (read-only).
+
+---
+
+### 🚨 RULE #1: ALWAYS Read status.json (NEVER Modify)
+
+- Read-only operation (visualization only)
+- NEVER update status.json from this command
+- Extract story data and calculate WIP metrics
+- No file writes, no state changes
+
+### 🚨 RULE #2: ALWAYS Show Four Columns
+
+**Column Layout** (by default):
+1. **READY** (status="ready")
+2. **IN PROGRESS** (status="in-progress")
+3. **IN REVIEW** (status="in-review")
+4. **DONE** (status="done")
+
+Special handling:
+- Separate BLOCKED stories (show with 🔴 red)
+- Show WIP limits per agent (max 2 in-progress + in-review)
+
+### 🚨 RULE #3: ALWAYS Calculate & Show WIP Violations
+
+- Count in-progress + in-review per agent
+- Highlight if >2 stories (WIP limit exceeded)
+- Show with ⚠️ warning icon
+- Suggest unblocking action
+
+### 🚨 RULE #4: ALWAYS Include Statistics
+
+Show these stats:
+- Total stories in each status
+- WIP status per agent
+- Blockers count and reasons
+- Throughput (stories completed this week)
+- Velocity trend (↗ ↘ →)
+
+---
+
+## Key Parameters & Output
+
+**Input Parameters**:
+```
+EPIC=<EP_ID>           # Filter by specific epic (optional)
+OWNER=<agent_id>       # Filter by owner (optional)
+FORMAT=ascii|markdown|html  # Output format (default: ascii)
+GROUP_BY=status|owner|epic  # Grouping method (default: status)
+```
+
+**Output Formats**:
+| Format | Use Case | Visual |
+|--------|----------|--------|
+| ascii | Terminal viewing | Box drawing chars (╔╗╚╝) |
+| markdown | Documentation/wiki | Markdown tables |
+| html | Web export | Full HTML page |
+
+**Data Source**:
+- Read: docs/09-agents/status.json
+- Extract: story status, owner, epic, estimate
+
+---
+
+## Board Visualization Rules
+
+**ASCII Format** (default):
+- Box drawing characters (╔═╗║╚╝├┤┬┴┼)
+- Columns for each status
+- Story cards with ID, title, owner, estimate, epic
+- Color coded via emoji (🟢🟡🔵⚪🔴)
+- Max 80 char width for terminal viewing
+
+**Card Contents**:
 ```
-/agileflow:board
-/agileflow:board EPIC=EP-0010
-/agileflow:board OWNER=AG-UI FORMAT=markdown
-/agileflow:board GROUP_BY=owner
+🟢 US-0042
+Login form
+AG-UI · 1d
+EP-0010
 ```
 
-**What It Does**:
-1. Reads `docs/09-agents/status.json` for story data
-2. Organizes stories by status (or owner/epic if specified)
-3. Calculates WIP limits and identifies violations
-4. Renders visual board with color coding
-5. Shows statistics (throughput, velocity, blockers)
-6. Suggests actions based on board state
-
-**Input Options**:
-- `EPIC=<EP_ID>` - Filter by specific epic
-- `OWNER=<agent_id>` - Filter by owner
-- `FORMAT=ascii|markdown|html` - Output format (default: ascii)
-- `GROUP_BY=status|owner|epic` - Grouping method (default: status)
-
-**Board Layout** (ASCII):
+**WIP Indicator**:
 ```
-╔══════════════════════════════════════════════════════════════╗
-║                   AGILEFLOW KANBAN BOARD                      ║
-║                  Updated: 2025-12-22 14:30                    ║
-╠══════════════════════════════════════════════════════════════╣
-║ 📊 Summary: 15 stories | 3 ready | 4 in-progress | 6 done   ║
-║ ⚠️  WIP Limit: 2/agent (AG-UI: 2/2 ⚠️, AG-API: 1/2 ✓)       ║
-╚══════════════════════════════════════════════════════════════╝
-
-┌──────────────┬──────────────┬──────────────┬──────────────┐
-│ 📋 READY (3) │ 🔄 IN PROG   │ 👀 REVIEW    │ ✅ DONE (6)  │
-│              │ (4) WIP: 4/6 │ (2)          │              │
-├──────────────┼──────────────┼──────────────┼──────────────┤
-│ 🟢 US-0042   │ 🟡 US-0038   │ 🔵 US-0035   │ ⚪ US-0030   │
-│ Login form   │ OAuth flow   │ Pwd reset    │ User reg     │
-│ AG-UI · 1d   │ AG-API · 1.5d│ AG-API · 1d  │ AG-API · 1d  │
-└──────────────┴──────────────┴──────────────┴──────────────┘
+🔄 IN PROGRESS (4)
+WIP: 4/6 ⚠️ (at limit)
 ```
 
-**Color Coding**:
-- 🟢 Green: High priority / ready to start
-- 🟡 Yellow: In progress / medium priority
-- 🔵 Blue: In review / low priority
-- ⚪ White: Done
-- 🔴 Red: Blocked
-- ⚠️ Warning: WIP limit exceeded
+**Blocked Indicator**:
+```
+🔴 BLOCKED (1)
+US-0041: Waiting on API keys
+```
+
+---
 
-**Statistics Provided**:
-- Throughput (stories completed per week)
-- Velocity (points per week)
-- Status distribution
-- Owner workload
-- Blockers and warnings
+## Action Suggestions
 
-**Action Suggestions**:
+After displaying board, suggest actions:
 - "AG-UI at WIP limit. Complete US-0038 before starting new work."
-- "US-0041 blocked. Unblock by reviewing US-0035?"
+- "US-0041 blocked >3 days. Escalate for API access?"
 - "3 stories ready. Which should we prioritize?"
+- "AG-DEVOPS has no work. Assign unblocking tasks?"
 
-**Best Practices**:
-- Review board daily to identify bottlenecks
-- Keep WIP limits respected (default: 2/agent)
-- Export board snapshots to track velocity over time
-- Use GROUP_BY=owner to balance workload
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Modify status.json (read-only command)
+- Hide blockers or WIP violations
+- Skip statistics and trend data
+- Make board too wide (>80 chars)
+
+✅ **DO**:
+- Read status.json (no updates)
+- Highlight WIP violations clearly
+- Include statistics and trends
+- Suggest next actions based on board state
+
+---
 
-**Tool Usage Examples**:
+## Confirmation & Follow-up
 
-AskUserQuestion (for actions after displaying board):
+After displaying board:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
@@ -100,15 +167,26 @@ AskUserQuestion (for actions after displaying board):
   "header": "Board Actions",
   "multiSelect": false,
   "options": [
-    {"label": "Update a story status", "description": "Change story status on board"},
-    {"label": "Export board", "description": "Save board snapshot to file"},
-    {"label": "View story details", "description": "See full story information"},
-    {"label": "Filter board", "description": "Filter by epic/owner"}
+    {"label": "Update story status", "description": "Change status on board"},
+    {"label": "View blockers", "description": "See blocker details"},
+    {"label": "Filter board", "description": "Filter by epic/owner"},
+    {"label": "Export snapshot", "description": "Save board to file"}
   ]
 }]</parameter>
 </invoke>
 ```
 
+---
+
+## REMEMBER AFTER COMPACTION
+
+- Command is read-only (displays status.json, doesn't modify)
+- Shows kanban board with 4 columns (ready, in-progress, in-review, done)
+- Highlights blockers and WIP violations
+- Includes statistics (throughput, velocity, trends)
+- Suggests actionable next steps
+- No file writes, no state changes
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/changelog.md

@@ -1,5 +1,20 @@
 ---
 description: Auto-generate changelog from commit history
+compact_context:
+  priority: high
+  preserve_rules:
+    - "Auto-detect version from latest git tag if VERSION not provided"
+    - "Parse conventional commits (feat:→Added, fix:→Fixed, perf:→Changed, security:→Security)"
+    - "Detect BREAKING CHANGES (! suffix or BREAKING CHANGE: footer)"
+    - "Follow Keep a Changelog format strictly (standard markdown structure)"
+    - "Include PR/issue numbers for traceability (#123)"
+    - "ALWAYS show diff-first preview before updating CHANGELOG.md"
+    - "Suggest semantic version bump based on changes (major/minor/patch)"
+    - "Never remove old changelog entries"
+  state_fields:
+    - next_version
+    - version_suggestion_accepted
+    - changelog_updated
 ---
 
 # generate-changelog