agileflow 2.76.0 → 2.78.0

package/src/core/commands/status.md

@@ -1,6 +1,22 @@
 ---
 description: Update story status and progress
 argument-hint: STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:status - Status updater broadcasting to message bus"
+    - "MUST update docs/09-agents/status.json (use jq or Edit tool, never echo/cat >)"
+    - "MUST validate JSON after modification (jq empty check)"
+    - "MUST append bus message to docs/09-agents/bus/log.jsonl"
+    - "MUST use AskUserQuestion for user confirmation (YES/NO format)"
+    - "MUST show diff preview before confirming (diff-first pattern)"
+    - "Status values: ready|in-progress|blocked|in-review|done"
+    - "MUST escape user text automatically (jq handles escaping)"
+  state_fields:
+    - story_id
+    - current_status
+    - new_status
+    - pr_url
 ---
 
 # status
@@ -33,30 +49,112 @@ This gathers git status, stories/epics, session state, and registers for PreComp
 ---
 
 <!-- COMPACT_SUMMARY_START -->
-## Compact Summary
-- **Command**: /agileflow:status
-- **Purpose**: Update story status and broadcast to agents
-- **Arguments**: STORY=<US-ID> STATUS=<status> [SUMMARY=<text>] [PR=<url>] [TO=<agent-id>]
-- **Status Values**: in-progress, blocked, in-review, done
-- **Key Actions**:
-  1. Update docs/09-agents/status.json (status, summary, last_update, pr)
-  2. Validate JSON after update using jq
-  3. Append bus line to docs/09-agents/bus/log.jsonl
-- **JSON Safety**: ALWAYS use jq or Edit tool (never echo/cat > status.json)
-- **Validation**: Run jq empty check after ANY modification
-- **Bus Message**: {ts, from, to, type:"status", story, text}
-- **Backup**: Restore from docs/09-agents/status.json.backup if validation fails
-- **Output**: Diff-first, then YES/NO confirmation
-- **Critical**: User text automatically escaped by jq
-- **Related**: docs/09-agents/status.json, bus/log.jsonl
-
-**Tool Usage Examples**:
-
-AskUserQuestion:
+
+## ⚠️ COMPACT SUMMARY - /agileflow:status IS ACTIVE
+
+**CRITICAL**: You update story status and broadcast to agents. This command updates core project state.
+
+---
+
+### 🚨 RULE #1: ALWAYS Use jq or Edit Tool (NEVER echo/cat >)
+
+**REQUIRED**:
+- ALWAYS use jq for status.json updates (prevents corruption)
+- ALWAYS validate after modification:
+```bash
+if ! jq empty docs/09-agents/status.json 2>/dev/null; then
+  echo "❌ ERROR: status.json is now invalid JSON!"
+  exit 1
+fi
+```
+
+### 🚨 RULE #2: ALWAYS Show Diff Preview Before Confirming
+
+**Workflow**:
+1. Parse inputs (STORY, STATUS, SUMMARY, PR, TO)
+2. Prepare status.json update
+3. Show diff of changes
+4. Ask YES/NO confirmation
+5. Only on YES: Execute update + append bus message
+
+### 🚨 RULE #3: VALID STATUS VALUES ONLY
+
+Status must be one of:
+- `ready` - Story ready to start
+- `in-progress` - Currently being worked on
+- `blocked` - Waiting on dependency
+- `in-review` - Code review/PR in progress
+- `done` - Completed and verified
+
+---
+
+## Key Files & Actions
+
+**Input Parameters**:
+```
+STORY=<US-ID>           # e.g., US-0042 (required)
+STATUS=<status>         # ready|in-progress|blocked|in-review|done (required)
+SUMMARY=<text>          # 1-2 lines explaining status (optional)
+PR=<url>                # Pull request URL for in-review (optional)
+TO=<agent-id>           # Recipient agent for bus message (optional)
+```
+
+**Update status.json**:
+```json
+{
+  "stories": {
+    "US-0042": {
+      "status": "in-progress",
+      "summary": "Started work on login form",
+      "pr": "https://github.com/.../pull/42",
+      "last_update": "ISO-timestamp"
+    }
+  }
+}
+```
+
+**Append to bus/log.jsonl**:
+```json
+{"ts":"ISO-timestamp","from":"SYSTEM","to":"<TO or ALL>","type":"status","story":"<STORY>","status":"<STATUS>","text":"<SUMMARY>"}
+```
+
+---
+
+## Anti-Patterns & Correct Usage
+
+❌ **DON'T**:
+- Use echo or cat to write to status.json
+- Skip validation after JSON changes
+- Use invalid status values (e.g., "in_progress")
+- Forget to show diff before confirming
+- Let user text corrupt JSON (use jq escaping)
+
+✅ **DO**:
+- Use jq for all JSON operations
+- Validate with `jq empty` after every write
+- Use only valid status values
+- Show diff preview before confirmation
+- Let jq handle text escaping automatically
+
+---
+
+## Confirmation Flow
+
+1. **Show diff preview**:
+```
+docs/09-agents/status.json
+
+- "status": "ready",
++ "status": "in-progress",
++ "summary": "Started work on login form",
++ "pr": "https://github.com/.../pull/42",
+```
+
+2. **Ask confirmation**:
 ```xml
 <invoke name="AskUserQuestion">
 <parameter name="questions">[{
-  "question": "Update US-0042 to in-review?",
+  "question": "Update US-0042 to in-progress?",
   "header": "Confirm Status Update",
   "multiSelect": false,
   "options": [
@@ -67,6 +165,20 @@ AskUserQuestion:
 </invoke>
 ```
 
+3. **On YES**: Execute update + validate JSON + append bus message
+4. **On NO**: Abort without changes
+
+---
+
+## REMEMBER AFTER COMPACTION
+
+- Updates status.json (uses jq for safety)
+- Broadcasts to agents via bus/log.jsonl
+- ALWAYS validate JSON after modification
+- ALWAYS show diff before confirming
+- Status values: ready, in-progress, blocked, in-review, done
+- Text escaping handled automatically by jq
+
 <!-- COMPACT_SUMMARY_END -->
 
 ---

package/src/core/commands/story/list.md

@@ -0,0 +1,176 @@
+---
+description: List all stories with status and filters
+argument-hint: [EPIC=<EP-ID>] [STATUS=<status>] [OWNER=<id>]
+---
+
+# /agileflow:story:list
+
+Display all user stories with filtering and quick actions.
+
+---
+
+## Purpose
+
+Shows all stories from `docs/09-agents/status.json` with:
+- Status (ready, in_progress, blocked, done)
+- Epic grouping
+- Owner assignment
+- Quick action options
+
+**This is a read-only command** - no files are written.
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:story:list [EPIC=<EP-ID>] [STATUS=<status>] [OWNER=<id>]`
+**Purpose**: Display stories with filters and offer quick actions
+
+### Flow
+1. Read status.json
+2. Apply filters (epic, status, owner)
+3. Display formatted table
+4. Offer actions: view details, start work, create new
+
+### Critical Rules
+- **Read-only**: No file writes
+- **Always offer actions**: End with AskUserQuestion for next steps
+- **Group by epic**: Show stories organized by their parent epic
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| EPIC | No | Filter by epic (e.g., EP-0001) |
+| STATUS | No | Filter by status (ready, in_progress, blocked, done) |
+| OWNER | No | Filter by owner |
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Read Status File
+
+```bash
+cat docs/09-agents/status.json
+```
+
+### Step 2: Apply Filters
+
+If filters provided:
+- EPIC: Show only stories in that epic
+- STATUS: Show only stories with that status
+- OWNER: Show only stories assigned to that owner
+
+### Step 3: Display Stories
+
+Format output as table grouped by epic:
+
+```markdown
+## Stories
+
+### EP-0001: Authentication System
+| Story | Title | Status | Owner | Estimate |
+|-------|-------|--------|-------|----------|
+| US-0001 | Login form | done | AG-UI | 2h |
+| US-0002 | Password reset | in_progress | AG-API | 3h |
+| US-0003 | Session management | ready | AG-API | 4h |
+
+### EP-0002: User Dashboard
+| Story | Title | Status | Owner | Estimate |
+|-------|-------|--------|-------|----------|
+| US-0004 | Dashboard layout | ready | AG-UI | 2h |
+| US-0005 | Activity feed | ready | AG-UI | 3h |
+
+---
+**Summary**: 5 stories (1 done, 1 in_progress, 3 ready)
+```
+
+### Step 4: Offer Actions
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "View story details", "description": "See full story with acceptance criteria"},
+    {"label": "Start working on a story", "description": "Mark a ready story as in_progress"},
+    {"label": "Create new story", "description": "Add a new story to an epic"},
+    {"label": "Done", "description": "Exit"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "View story details"**:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which story would you like to view?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "US-0003: Session management (ready)", "description": "EP-0001 - AG-API"},
+    {"label": "US-0004: Dashboard layout (ready)", "description": "EP-0002 - AG-UI"},
+    {"label": "US-0005: Activity feed (ready)", "description": "EP-0002 - AG-UI"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+Then invoke: `/agileflow:story:view STORY=<selected>`
+
+**If "Start working on a story"**:
+Show only `ready` stories, then invoke:
+`/agileflow:status <selected> STATUS=in_progress`
+
+**If "Create new story"**:
+Invoke: `/agileflow:story`
+
+---
+
+## Example Usage
+
+```bash
+# List all stories
+/agileflow:story:list
+
+# List stories for specific epic
+/agileflow:story:list EPIC=EP-0001
+
+# List only ready stories
+/agileflow:story:list STATUS=ready
+
+# List stories assigned to specific owner
+/agileflow:story:list OWNER=AG-UI
+
+# Combined filters
+/agileflow:story:list EPIC=EP-0001 STATUS=ready
+```
+
+---
+
+## Rules
+
+- **Read-only**: No file writes
+- **Group by epic**: Always organize stories under their parent epic
+- **Show summary**: Include counts by status at the bottom
+- **Always offer actions**: End with next step options
+
+---
+
+## Related Commands
+
+- `/agileflow:story:view` - View full story details
+- `/agileflow:story` - Create new story
+- `/agileflow:story-validate` - Validate story completeness
+- `/agileflow:status` - Update story status
+- `/agileflow:board` - Visual kanban board view

package/src/core/commands/story/view.md

@@ -0,0 +1,265 @@
+---
+description: View story details with contextual actions
+argument-hint: STORY=<US-ID>
+---
+
+# /agileflow:story:view
+
+View full story details and take contextual actions based on story state.
+
+---
+
+## Purpose
+
+Displays complete story information and offers **context-aware actions** based on the story's current status:
+- **ready** → Start work, validate, assign
+- **in_progress** → View progress, mark blocked, complete
+- **blocked** → View blockers, unblock, reassign
+- **done** → View summary, reopen if needed
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:story:view STORY=<US-ID>`
+**Purpose**: View story details with context-aware action suggestions
+
+### Flow
+1. Read story file and status.json entry
+2. Display full story details (AC, tests, progress)
+3. Offer actions based on current status
+4. Execute selected action
+
+### Critical Rules
+- **Context-aware actions**: Different options based on story status
+- **Show everything**: AC, test status, dependencies, blockers
+- **Always offer next steps**: End with relevant AskUserQuestion
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| STORY | Yes | Story ID (e.g., US-0042) |
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Validate Input
+
+If STORY not provided, list recent stories:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which story would you like to view?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "US-0042: Latest story", "description": "in_progress - AG-UI"},
+    {"label": "US-0041: Previous story", "description": "ready - AG-API"},
+    {"label": "Show all stories", "description": "View full story list"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 2: Read Story Data
+
+Read from multiple sources:
+
+```bash
+# Story file
+cat docs/06-stories/<EPIC>/<STORY>-*.md
+
+# Status entry
+cat docs/09-agents/status.json | jq '.stories["<STORY>"]'
+
+# Test status (if exists)
+cat docs/07-testing/test-cases/<STORY>.md
+```
+
+### Step 3: Display Story Details
+
+```markdown
+## US-0042: User Login Form
+
+**Epic**: EP-0001 (Authentication System)
+**Status**: in_progress
+**Owner**: AG-UI
+**Estimate**: 3h
+**Created**: 2024-12-28
+**Updated**: 2024-12-30
+
+---
+
+### Acceptance Criteria
+
+- [x] Given a user on the login page
+      When they enter valid credentials
+      Then they are redirected to dashboard
+
+- [ ] Given a user on the login page
+      When they enter invalid credentials
+      Then they see an error message
+
+- [ ] Given a user on the login page
+      When they click "Forgot Password"
+      Then they are taken to password reset flow
+
+---
+
+### Dependencies
+
+- US-0040: API authentication endpoint (done)
+- US-0041: Session management (ready) ⚠️ Not started yet
+
+---
+
+### Test Status
+
+| Test | Status |
+|------|--------|
+| Unit: LoginForm.test.tsx | passing |
+| Integration: auth-flow.test.ts | pending |
+| E2E: login.spec.ts | not created |
+
+---
+
+### Progress Notes
+
+- 2024-12-30: Started form implementation
+- 2024-12-29: Design approved
+```
+
+### Step 4: Offer Context-Aware Actions
+
+**Based on story status, show different options:**
+
+#### If STATUS = ready
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "This story is ready to start. What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Start working on this story (Recommended)", "description": "Mark as in_progress and begin implementation"},
+    {"label": "Validate story first", "description": "Check if AC and dependencies are complete"},
+    {"label": "View related research", "description": "Find research notes linked to this epic"},
+    {"label": "Back to story list", "description": "Return to /agileflow:story:list"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Start working"**:
+- Run `/agileflow:status <STORY> STATUS=in_progress`
+- Suggest: "Enter plan mode to explore implementation?"
+
+#### If STATUS = in_progress
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "This story is in progress. What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "Mark as complete", "description": "All AC done, move to done status"},
+    {"label": "Mark as blocked", "description": "Hit a blocker, need help"},
+    {"label": "View/run tests", "description": "Check test status for this story"},
+    {"label": "Add progress note", "description": "Document current progress"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Mark as complete"**:
+- First ask: "Have all acceptance criteria been met?"
+- If yes: Run `/agileflow:status <STORY> STATUS=done`
+- Suggest: "View next ready story?"
+
+**If "Mark as blocked"**:
+- Ask: "What is blocking this story?"
+- Run `/agileflow:status <STORY> STATUS=blocked BLOCKER=<reason>`
+- Suggest: "Create blocker resolution task?"
+
+#### If STATUS = blocked
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "This story is blocked. What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "View blocker details", "description": "See what's blocking this story"},
+    {"label": "Unblock and resume", "description": "Blocker resolved, continue work"},
+    {"label": "Reassign story", "description": "Assign to different owner"},
+    {"label": "Create research task", "description": "Need to research the blocker"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**If "Unblock and resume"**:
+- Run `/agileflow:status <STORY> STATUS=in_progress`
+- Clear blocker note
+
+#### If STATUS = done
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "This story is complete. What would you like to do?",
+  "header": "Actions",
+  "multiSelect": false,
+  "options": [
+    {"label": "View completion summary", "description": "See what was delivered"},
+    {"label": "Reopen story", "description": "Found issue, needs more work"},
+    {"label": "View next story in epic", "description": "Continue with related work"},
+    {"label": "Back to story list", "description": "Return to /agileflow:story:list"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Example Usage
+
+```bash
+# View specific story
+/agileflow:story:view STORY=US-0042
+
+# Will prompt for selection if no ID
+/agileflow:story:view
+```
+
+---
+
+## Rules
+
+- **Context-aware**: Actions must match current story status
+- **Show everything**: AC, tests, dependencies, blockers, notes
+- **Always offer next steps**: End with relevant action options
+- **Connect to related commands**: Link to status, validate, tests, research
+
+---
+
+## Related Commands
+
+- `/agileflow:story:list` - View all stories
+- `/agileflow:story` - Create new story
+- `/agileflow:story-validate` - Validate story completeness
+- `/agileflow:status` - Update story status
+- `/agileflow:tests` - Run/view tests
+- `/agileflow:research:analyze` - Analyze related research