agileflow 3.4.0 → 3.4.2

package/src/core/commands/code/test.md

@@ -1,6 +1,6 @@
 ---
 description: Multi-agent test quality analysis with consensus voting for finding test suite weaknesses
-argument-hint: "[file|directory] [DEPTH=quick|deep|ultradeep] [FOCUS=coverage|fragility|mocking|assertions|structure|integration|maintenance|patterns|all] [MODEL=haiku|sonnet|opus]"
+argument-hint: "[file|directory] [DEPTH=quick|deep|ultradeep|extreme] [FOCUS=coverage|fragility|mocking|assertions|structure|integration|maintenance|patterns|all] [MODEL=haiku|sonnet|opus]"
 compact_context:
   priority: high
   preserve_rules:
@@ -111,12 +111,49 @@ FOCUS = all (default) or comma-separated list
 - `ultradeep`: Spawn each analyzer as a separate Claude Code session in tmux. Requires tmux. Uses model profiles from metadata. Falls back to `deep` if tmux unavailable.
 
 **ULTRADEEP mode** (DEPTH=ultradeep):
-1. Show cost estimate: `node .agileflow/scripts/spawn-audit-sessions.js --audit=test --target=TARGET --focus=FOCUS --model=MODEL --dry-run`
+1. Show cost estimate:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=test --target=TARGET --focus=FOCUS --model=MODEL --dry-run
+   ```
 2. Confirm with user before launching
-3. Spawn sessions: `node .agileflow/scripts/spawn-audit-sessions.js --audit=test --target=TARGET --focus=FOCUS --model=MODEL`
-4. Monitor sentinel files in `docs/09-agents/ultradeep/{trace_id}/` for completion
-5. Collect all findings and run consensus coordinator (same as deep mode)
-6. If tmux unavailable, fall back to `DEPTH=deep` with warning
+3. Spawn sessions (use `--json` to capture trace ID):
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=test --target=TARGET --focus=FOCUS --model=MODEL --json
+   ```
+   Parse the JSON output to get `traceId`. Example: `{"ok":true,"traceId":"abc123ef",...}`
+4. Wait for all analyzers to complete:
+   ```bash
+   node .agileflow/scripts/lib/tmux-audit-monitor.js wait TRACE_ID --timeout=1800
+   ```
+   - Exit 0 = all complete (JSON results on stdout)
+   - Exit 1 = timeout (partial results on stdout, `missing` array shows what's left)
+   - To check progress without blocking: `node .agileflow/scripts/lib/tmux-audit-monitor.js status TRACE_ID`
+   - To retry stalled analyzers: `node .agileflow/scripts/lib/tmux-audit-monitor.js retry TRACE_ID`
+5. Parse `results` array from the JSON output. Pass all findings to consensus coordinator (same as deep mode).
+6. If tmux unavailable (spawn exits code 2), fall back to `DEPTH=deep` with warning
+
+**EXTREME mode** (DEPTH=extreme):
+Partition-based multi-agent audit. Instead of 1 analyzer per tmux window, the codebase is split into partitions and each partition runs ALL analyzers.
+1. Scan the target directory to understand the codebase structure:
+   - Use Glob to find top-level source directories
+   - Group related directories into 3-7 logical partitions (coherent domains: auth, api, ui, etc.)
+   - If user provided PARTITIONS=N (a number), split into exactly N partitions
+   - If user provided PARTITIONS=dir1,dir2,dir3, use those exact directories
+2. Show the partition plan and agent count to the user, confirm before launching:
+   Example: "5 partitions x 8 analyzers = 40 agents. Estimated cost: $X. Proceed?"
+3. Spawn sessions with partitions:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=test --target=TARGET --depth=extreme --partitions=dir1,dir2,dir3 --model=MODEL --json
+   ```
+4. Wait and collect results (same as ultradeep - use tmux-audit-monitor.js)
+5. Run consensus on combined results from all partitions
+
+**PARTITIONS argument** (only used with DEPTH=extreme):
+| Value | Behavior |
+|-------|----------|
+| Not set | AI decides partitions (3-7 based on codebase size) |
+| `PARTITIONS=5` | AI creates exactly 5 partitions |
+| `PARTITIONS=src/auth,src/api,lib` | Use these exact directories |
 
 ### STEP 2: Deploy Analyzers in Parallel
 

package/src/core/commands/configure.md

@@ -1,5 +1,6 @@
 ---
 description: Configure AgileFlow features, hooks, and project infrastructure (Visual E2E, CI, git)
+phase: pre-story
 argument-hint: "[--profile=<name>] [--save-profile=<name>] [--list-profiles] [--export-profile=<name>] [--import-profile=<file>] [--enable/--disable=features]"
 compact_context:
   priority: critical

package/src/core/commands/council.md

@@ -1,5 +1,6 @@
 ---
 description: Convene AI Council for strategic decisions with three perspectives (Optimist, Advocate, Analyst)
+phase: planning
 argument-hint: "<question> [--mode parallel|debate] [--rounds N]"
 compact_context:
   priority: high

package/src/core/commands/deploy.md

@@ -1,5 +1,6 @@
 ---
 description: Set up automated deployment pipeline
+phase: implementation
 argument-hint: "(no arguments)"
 compact_context:
   priority: high

package/src/core/commands/diagnose.md

@@ -1,5 +1,6 @@
 ---
 description: System health diagnostics
+phase: post-impl
 argument-hint: "(no arguments)"
 compact_context:
   priority: high

package/src/core/commands/docs.md

@@ -1,5 +1,6 @@
 ---
 description: Synchronize documentation with code changes
+phase: post-impl
 argument-hint: "[BRANCH=<name>] [BASE=<branch>] [AUTO_CREATE=true|false]"
 compact_context:
   priority: high

package/src/core/commands/epic/edit.md

@@ -0,0 +1,213 @@
+---
+description: Edit an existing epic's fields (title, owner, goal, status)
+argument-hint: "EPIC=<EP-ID> [TITLE=<text>] [OWNER=<id>] [GOAL=<text>] [STATUS=<status>]"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:epic:edit - Edit epic fields with diff-preview-confirm"
+    - "{{RULES:json_operations}}"
+    - "{{RULES:user_confirmation}}"
+    - "{{RULES:file_preview}}"
+    - "MUST read current epic from status.json BEFORE proposing changes"
+    - "MUST show diff of old vs new values"
+    - "MUST confirm with AskUserQuestion before writing"
+    - "MUST log edit event to bus/log.jsonl"
+    - "MUST update epic file in docs/05-epics/ if it exists"
+  state_fields:
+    - epic_id
+    - fields_changed
+---
+
+# /agileflow:epic:edit
+
+Edit an existing epic's metadata fields with diff preview and confirmation.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js epic:edit
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:epic:edit EPIC=<EP-ID> [TITLE=...] [OWNER=...] [GOAL=...] [STATUS=...]`
+**Purpose**: Edit epic fields in status.json with diff-preview-confirm workflow
+
+### Flow
+1. Parse EPIC parameter (required) and optional field overrides
+2. Read current epic from status.json
+3. Show diff of proposed changes
+4. Confirm via AskUserQuestion
+5. Apply changes to status.json
+6. Update epic file in docs/05-epics/ if it exists
+7. Log edit event to bus/log.jsonl
+
+### Critical Rules
+- **Diff preview**: Always show old vs new before writing
+- **Confirmation**: Never write without user approval
+- **Bus logging**: Always append epic-edited event
+- **Epic file sync**: Update markdown file if it exists
+- **Validation**: Verify JSON integrity after write
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| EPIC | Yes | Epic ID (e.g., EP-0041) |
+| TITLE | No | New epic title |
+| OWNER | No | New owner (e.g., AG-DEVOPS, AG-API) |
+| GOAL | No | New epic goal description |
+| STATUS | No | New status (ready, active, complete, on-hold) |
+
+At least one optional field must be provided (otherwise suggest `/agileflow:epic:view`).
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Validate Input
+
+If EPIC not provided:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which epic would you like to edit?",
+  "header": "Select",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter epic ID", "description": "Provide an EP-XXXX identifier"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 2: Read Current Epic
+
+Read the epic entry from `docs/09-agents/status.json`:
+
+```javascript
+const data = JSON.parse(fs.readFileSync('docs/09-agents/status.json', 'utf8'));
+const epic = data.epics[epicId];
+```
+
+If epic not found, show error: "Epic {EPIC} not found in status.json"
+
+### Step 3: Build Change Set
+
+Compare provided fields against current values. Skip fields that match current values (no-op).
+
+If no fields would change, inform user: "No changes detected. Current values match provided values."
+
+### Step 4: Show Diff Preview
+
+Display a clear diff of what will change:
+
+```markdown
+## Editing EP-0041: Current Title
+
+| Field | Current | New |
+|-------|---------|-----|
+| title | "DX Quick Wins" | "DX Quick Wins - March 2026" |
+| owner | AG-DEVOPS | AG-API |
+| status | ready | active |
+
+Files modified:
+1. docs/09-agents/status.json (epic entry update)
+2. docs/05-epics/EP-0041-*.md (if exists, update frontmatter)
+3. docs/09-agents/bus/log.jsonl (edit event append)
+```
+
+### Step 5: Confirm Changes
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Apply these changes to EP-0041?",
+  "header": "Confirm edit",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, apply changes (Recommended)", "description": "Update status.json and log edit event"},
+    {"label": "No, cancel", "description": "Discard changes"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+### Step 6: Apply Changes
+
+On confirmation:
+
+1. **Update status.json** using Edit tool or jq:
+   - Update only the changed fields in the epic entry
+   - Set `updated` timestamp to current ISO date
+
+2. **Update epic file** (if exists in `docs/05-epics/`):
+   - Find matching file: `docs/05-epics/EP-XXXX-*.md`
+   - Update title in heading and frontmatter
+   - Update owner, status, goal fields
+
+3. **Validate JSON**:
+```bash
+node -e "JSON.parse(require('fs').readFileSync('docs/09-agents/status.json','utf8')); console.log('valid')"
+```
+
+4. **Append to bus/log.jsonl**:
+```json
+{"ts":"<ISO>","type":"epic-edited","from":"USER","epic":"<EPIC>","changes":{"field":"old_value->new_value"},"text":"Epic edited: <changed fields>"}
+```
+
+### Step 7: Confirm Success
+
+```
+Epic EP-0041 updated:
+  title: "DX Quick Wins" -> "DX Quick Wins - March 2026"
+  status: ready -> active
+```
+
+---
+
+## Example Usage
+
+```bash
+# Edit title
+/agileflow:epic:edit EPIC=EP-0041 TITLE="Updated Title"
+
+# Change owner and status
+/agileflow:epic:edit EPIC=EP-0041 OWNER=AG-API STATUS=active
+
+# Update goal
+/agileflow:epic:edit EPIC=EP-0041 GOAL="New goal description for this epic"
+
+# Multiple fields at once
+/agileflow:epic:edit EPIC=EP-0041 TITLE="New Title" OWNER=AG-UI STATUS=active
+```
+
+---
+
+## Rules
+
+- **Always preview**: Show diff before applying
+- **Always confirm**: Use AskUserQuestion before writes
+- **Always log**: Append edit event to bus/log.jsonl
+- **Always validate**: Check JSON integrity after write
+- **Sync epic file**: Update docs/05-epics/ markdown if it exists
+- **No silent changes**: Every change must be visible to the user
+
+---
+
+## Related Commands
+
+- `/agileflow:epic:view` - View epic details
+- `/agileflow:epic:list` - List all epics
+- `/agileflow:epic` - Create new epic
+- `/agileflow:story:edit` - Edit story fields
+- `/agileflow:status` - Quick status update

package/src/core/commands/epic.md

@@ -1,5 +1,6 @@
 ---
 description: Create a new epic with stories
+phase: pre-story
 argument-hint: "EPIC=<EP-ID> TITLE=<text> OWNER=<id> GOAL=<text> [STORIES=<list>] [RESEARCH=<file>]"
 compact_context:
   priority: high

package/src/core/commands/export.md

@@ -0,0 +1,238 @@
+---
+description: Export stories and epics to CSV, JSON, or Markdown for stakeholder reporting
+argument-hint: "FORMAT=csv|json|md [EPIC=<EP-ID>] [STATUS=<status>] [OWNER=<id>]"
+compact_context:
+  priority: medium
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:export - Export stories/epics to CSV/JSON/Markdown"
+    - "{{RULES:json_operations}}"
+    - "MUST read status.json as data source"
+    - "MUST support FORMAT=csv|json|md (default: csv)"
+    - "MUST support optional filters: EPIC, STATUS, OWNER"
+    - "MUST save output to docs/08-project/exports/"
+  state_fields:
+    - format
+    - filter_epic
+    - filter_status
+    - filter_owner
+    - output_path
+---
+
+# /agileflow:export
+
+Export stories and epics from status.json to CSV, JSON, or Markdown for stakeholder reporting.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js export
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+## Compact Summary
+
+**Command**: `/agileflow:export FORMAT=csv|json|md [EPIC=...] [STATUS=...] [OWNER=...]`
+**Purpose**: Export filtered stories to CSV, JSON, or Markdown files
+
+### Flow
+1. Parse FORMAT and optional filters
+2. Read status.json
+3. Apply filters (epic, status, owner)
+4. Generate output in requested format
+5. Save to docs/08-project/exports/export-YYYYMMDD.{csv|json|md}
+6. Show summary and file path
+
+### Critical Rules
+- **Default format**: CSV if not specified
+- **CSV must be Excel-compatible**: Proper quoting, comma-separated
+- **JSON mirrors status.json**: Filtered subset of stories structure
+- **Markdown generates table**: Paste-ready for docs/reports
+- **Always show count**: "Exported N stories to <path>"
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+## Arguments
+
+| Argument | Required | Default | Description |
+|----------|----------|---------|-------------|
+| FORMAT | No | csv | Output format: `csv`, `json`, or `md` |
+| EPIC | No | all | Filter by epic ID (e.g., EP-0041) |
+| STATUS | No | all | Filter by status: ready, in_progress, blocked, done, completed |
+| OWNER | No | all | Filter by owner (e.g., AG-API, AG-UI) |
+
+Multiple filters can be combined. All are AND-joined (stories must match all filters).
+
+---
+
+## IMMEDIATE ACTIONS
+
+### Step 1: Parse Arguments
+
+```
+FORMAT = argument or "csv" (default)
+EPIC = optional epic filter
+STATUS = optional status filter
+OWNER = optional owner filter
+```
+
+Validate FORMAT is one of: csv, json, md. If invalid, show error and suggest valid values.
+
+### Step 2: Read and Filter Data
+
+Read `docs/09-agents/status.json` and filter stories:
+
+```javascript
+const data = JSON.parse(fs.readFileSync('docs/09-agents/status.json', 'utf8'));
+let stories = Object.entries(data.stories).map(([id, s]) => ({ id, ...s }));
+
+// Apply filters
+if (EPIC) stories = stories.filter(s => s.epic === EPIC);
+if (STATUS) stories = stories.filter(s => s.status === STATUS);
+if (OWNER) stories = stories.filter(s => s.owner === OWNER);
+```
+
+If no stories match, inform user: "No stories match the given filters."
+
+### Step 3: Generate Output
+
+#### CSV Format
+
+Columns: ID, Title, Epic, Status, Owner, Priority, Estimate
+
+```csv
+ID,Title,Epic,Status,Owner,Priority,Estimate
+US-0380,"Add story:edit and epic:edit commands",EP-0041,done,AG-API,high,3h
+US-0381,"Add status:undo command for story status rollback",EP-0041,done,AG-API,high,2h
+```
+
+Rules:
+- First row is header
+- Quote fields containing commas or quotes
+- Escape quotes by doubling them
+- Use UTF-8 encoding
+
+#### JSON Format
+
+```json
+{
+  "exported_at": "2026-03-03T12:00:00Z",
+  "filters": { "epic": "EP-0041", "status": null, "owner": null },
+  "count": 8,
+  "stories": [
+    {
+      "id": "US-0380",
+      "title": "Add story:edit and epic:edit commands",
+      "epic": "EP-0041",
+      "status": "done",
+      "owner": "AG-API",
+      "priority": "high",
+      "estimate": "3h"
+    }
+  ]
+}
+```
+
+#### Markdown Format
+
+```markdown
+# Story Export - 2026-03-03
+
+**Filters**: Epic: EP-0041
+**Count**: 8 stories
+
+| ID | Title | Epic | Status | Owner | Priority | Estimate |
+|----|-------|------|--------|-------|----------|----------|
+| US-0380 | Add story:edit and epic:edit commands | EP-0041 | done | AG-API | high | 3h |
+| US-0381 | Add status:undo command | EP-0041 | done | AG-API | high | 2h |
+```
+
+### Step 4: Save Output
+
+Create output directory if needed:
+```bash
+mkdir -p docs/08-project/exports
+```
+
+Save to: `docs/08-project/exports/export-YYYYMMDD.{csv|json|md}`
+
+If file already exists for today, append a counter: `export-YYYYMMDD-2.csv`
+
+### Step 5: Show Summary
+
+```
+Exported 8 stories to docs/08-project/exports/export-20260303.csv
+
+Filters applied:
+  Epic: EP-0041
+  Status: all
+  Owner: all
+
+Preview (first 3 rows):
+  US-0380 | Add story:edit and epic:edit commands | done
+  US-0381 | Add status:undo command | done
+  US-0382 | Add export command | in_progress
+```
+
+Then offer next steps:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Export complete. What next?",
+  "header": "Next steps",
+  "multiSelect": false,
+  "options": [
+    {"label": "Open/view the exported file", "description": "Display full file contents"},
+    {"label": "Export in another format", "description": "Re-export as json/md/csv"},
+    {"label": "Done", "description": "Export saved successfully"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+---
+
+## Example Usage
+
+```bash
+# Export all stories as CSV (default)
+/agileflow:export
+
+# Export specific epic as JSON
+/agileflow:export FORMAT=json EPIC=EP-0041
+
+# Export ready stories as Markdown
+/agileflow:export FORMAT=md STATUS=ready
+
+# Export specific owner's stories as CSV
+/agileflow:export OWNER=AG-API STATUS=done
+
+# Combine filters
+/agileflow:export FORMAT=md EPIC=EP-0041 STATUS=ready OWNER=AG-API
+```
+
+---
+
+## Rules
+
+- **CSV Excel-compatible**: Proper quoting, commas, UTF-8
+- **JSON well-formed**: Pretty-printed, includes metadata
+- **Markdown paste-ready**: Standard table format
+- **Always show preview**: Display first few rows after export
+- **Always show path**: User needs to know where the file is
+- **No destructive overwrites**: Counter suffix for same-day exports
+
+---
+
+## Related Commands
+
+- `/agileflow:story:list` - Interactive story listing
+- `/agileflow:epic:list` - Interactive epic listing
+- `/agileflow:board` - Visual kanban board
+- `/agileflow:sprint` - Sprint planning view
+- `/agileflow:changelog` - Generate changelog

package/src/core/commands/help.md

@@ -87,7 +87,22 @@ Print a concise, one-screen overview:
 - What Epics, Stories, ADRs are; how docs/09-agents/status.json + bus/log.jsonl work
 - Daily flow: Pick story → Implement to AC → Tests → PR → Update status
 - WIP limit: max 2 stories/agent
-- List ALL available commands with one-line examples
+- List ALL available commands grouped by lifecycle phase
+- Show the current detected phase (from smart-detect.json) to highlight relevant commands
+
+### Lifecycle Phases
+
+Commands are organized by the project phase where they're most useful:
+
+| Phase | Description | Key Commands |
+|-------|------------|--------------|
+| **Pre-Story** | Story selection and project setup | epic, story, board, sprint, choose, configure |
+| **Planning** | Architecture and research decisions | adr, impact, council, multi-expert, baseline |
+| **Implementation** | Active development work | babysit, tdd, tests, verify, ci, workflow |
+| **Post-Impl** | Review, docs, and quality checks | audit, review, docs, changelog, diagnose |
+| **Pre-PR** | Final checks before pull request | pr, compress |
+
+**Tip**: Commands have a `phase` tag in their frontmatter. Run the command most relevant to your current phase.
 
 <!-- {{COMMAND_LIST}} -->
 

package/src/core/commands/ideate/discover.md

@@ -1,6 +1,6 @@
 ---
 description: Run structured discovery workflow - brainstorm, research, and generate a Product Brief
-argument-hint: "TOPIC=<text> [DEPTH=quick|guided|deep]"
+argument-hint: "TOPIC=<text> [DEPTH=quick|guided|deep] [MODEL=haiku|sonnet|opus]"
 compact_context:
   priority: critical
   preserve_rules:
@@ -10,11 +10,12 @@ compact_context:
     - "Phase 2: Research via /agileflow:research:ask (optional in quick mode)"
     - "Phase 3: Generate Product Brief via /agileflow:ideate:brief"
     - "Output: docs/08-project/briefs/{date}-{topic-slug}-brief.md"
-    - "MUST parse TOPIC (required) and DEPTH (default: guided)"
+    - "MUST parse TOPIC (required), DEPTH (default: guided), and MODEL (default: haiku, passed to ideate:new)"
     - "After brief generation, offer: create epic, refine brief, or done"
   state_fields:
     - topic
     - depth
+    - model
     - brainstorm_complete
     - research_complete
     - brief_generated
@@ -57,6 +58,7 @@ node .agileflow/scripts/obtain-context.js ideate:discover
 /agileflow:ideate:discover TOPIC="Mobile time tracking app"
 /agileflow:ideate:discover TOPIC="AI code review tool" DEPTH=deep
 /agileflow:ideate:discover TOPIC="Internal dashboard" DEPTH=quick
+/agileflow:ideate:discover TOPIC="Enterprise CRM" MODEL=opus
 ```
 
 **Phases**:
@@ -142,6 +144,7 @@ Parse the user's input:
 |----------|----------|---------|-------------|
 | TOPIC | Yes | - | The product/feature idea to explore |
 | DEPTH | No | guided | Discovery depth: quick, guided, or deep |
+| MODEL | No | haiku | Model for expert subagents (haiku, sonnet, opus). Passed through to ideate:new brainstorm phase. |
 
 **If TOPIC is missing**, ask the user:
 
@@ -191,7 +194,7 @@ From your {DOMAIN} perspective, generate 3-5 ideas covering:
 Be specific and actionable. Reference real-world examples where helpful.
 ```
 
-Deploy all experts with `run_in_background: true`, then collect results with TaskOutput.
+Deploy all experts with `run_in_background: true`, then collect results with TaskOutput. **If MODEL is specified**, pass it to each Task call via the `model` parameter.
 
 #### Guided Mode
 Same as Quick, but after collecting results:
@@ -343,6 +346,7 @@ Present the completed brief and ask what to do next:
 |----------|--------|---------|-------------|
 | TOPIC | Free text | (required) | The product/feature idea to explore |
 | DEPTH | quick, guided, deep | guided | Discovery depth level |
+| MODEL | haiku, sonnet, opus | haiku | Model for expert subagents. Passed to brainstorm phase Task calls. |
 
 {{argument}}