agileflow 3.3.0 → 3.4.1

package/src/core/commands/{audit → code}/security.md

@@ -1,14 +1,14 @@
 ---
 description: Multi-agent security vulnerability analysis with consensus voting for finding exploitable weaknesses
-argument-hint: "[file|directory] [DEPTH=quick|deep] [FOCUS=injection|auth|authz|secrets|input|deps|infra|api|all]"
+argument-hint: "[file|directory] [DEPTH=quick|deep|ultradeep|extreme] [FOCUS=injection|auth|authz|secrets|input|deps|infra|api|all] [MODEL=haiku|sonnet|opus]"
 compact_context:
   priority: high
   preserve_rules:
-    - "ACTIVE COMMAND: /agileflow:audit:security - Multi-agent security vulnerability analysis"
+    - "ACTIVE COMMAND: /agileflow:code:security - Multi-agent security vulnerability analysis"
     - "CRITICAL: Deploy analyzers IN PARALLEL in ONE message with multiple Task calls"
     - "CRITICAL: Wait for all results before running consensus (use TaskOutput with block=true)"
     - "CRITICAL: Confidence scoring: CONFIRMED (2+ agree), LIKELY (1 with evidence), INVESTIGATE (1 weak)"
-    - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep), FOCUS (injection|auth|authz|secrets|input|deps|infra|api|all)"
+    - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (injection|auth|authz|secrets|input|deps|infra|api|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
   state_fields:
     - target_path
@@ -18,7 +18,7 @@ compact_context:
     - findings_collected
 ---
 
-# /agileflow:audit:security
+# /agileflow:code:security
 
 Deploy multiple specialized security vulnerability analyzers in parallel to find exploitable weaknesses, then synthesize results through consensus voting into a prioritized Security Audit Report.
 
@@ -27,11 +27,14 @@ Deploy multiple specialized security vulnerability analyzers in parallel to find
 ## Quick Reference
 
 ```
-/agileflow:audit:security app/                                # Analyze app directory (quick, core 5 analyzers)
-/agileflow:audit:security . DEPTH=deep                        # Deep analysis - all 8 analyzers
-/agileflow:audit:security src/ FOCUS=injection,auth            # Focus on specific areas
-/agileflow:audit:security . DEPTH=deep FOCUS=all               # Comprehensive full audit
-/agileflow:audit:security app/api/ FOCUS=api                   # Check API routes specifically
+/agileflow:code:security app/                                # Analyze app directory (quick, core 5 analyzers)
+/agileflow:code:security . DEPTH=deep                        # Deep analysis - all 8 analyzers
+/agileflow:code:security src/ FOCUS=injection,auth            # Focus on specific areas
+/agileflow:code:security . DEPTH=deep FOCUS=all               # Comprehensive full audit
+/agileflow:code:security . DEPTH=ultradeep                     # Each analyzer in its own tmux session
+/agileflow:code:security src/ MODEL=sonnet                     # Use Sonnet for all analyzers
+/agileflow:code:security . DEPTH=ultradeep MODEL=opus          # Ultradeep with Opus
+/agileflow:code:security app/api/ FOCUS=api                   # Check API routes specifically
 ```
 
 ---
@@ -40,7 +43,7 @@ Deploy multiple specialized security vulnerability analyzers in parallel to find
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                 /agileflow:audit:security                    │
+│                 /agileflow:code:security                    │
 │                                                              │
 │  1. Parse arguments (target, depth, focus)                   │
 │  2. Deploy analyzers IN PARALLEL                             │
@@ -73,8 +76,9 @@ Deploy multiple specialized security vulnerability analyzers in parallel to find
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep | quick | quick = core 5 analyzers, deep = all 8 |
+| DEPTH | quick, deep, ultradeep | quick | quick = core 5, deep = all 8, ultradeep = separate tmux sessions |
 | FOCUS | injection,auth,authz,secrets,input,deps,infra,api,all | all | Which analyzers to deploy |
+| MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents. Default preserves existing behavior. |
 
 ---
 
@@ -107,6 +111,52 @@ FOCUS = all (default) or comma-separated list
 **DEPTH behavior**:
 - `quick` (default): Deploy core 5 analyzers. Focus on CRITICAL/HIGH issues only.
 - `deep`: Deploy all 8 analyzers. Include MEDIUM/LOW findings.
+- `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:
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=security --target=TARGET --focus=FOCUS --model=MODEL --dry-run
+   ```
+2. Confirm with user before launching
+3. Spawn sessions (use `--json` to capture trace ID):
+   ```bash
+   node .agileflow/scripts/spawn-audit-sessions.js --audit=security --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=security --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
 
@@ -368,13 +418,13 @@ Total: 7 findings (2 false positives excluded)
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Command**: `/agileflow:audit:security` - Multi-agent security vulnerability analysis with consensus
+**Command**: `/agileflow:code:security` - Multi-agent security vulnerability analysis with consensus
 
 **Quick Usage**:
 ```
-/agileflow:audit:security app/                        # Quick scan (core 5 analyzers)
-/agileflow:audit:security . DEPTH=deep                # All 8 analyzers
-/agileflow:audit:security src/ FOCUS=injection,auth    # Specific areas
+/agileflow:code:security app/                        # Quick scan (core 5 analyzers)
+/agileflow:code:security . DEPTH=deep                # All 8 analyzers
+/agileflow:code:security src/ FOCUS=injection,auth    # Specific areas
 ```
 
 **What It Does**: Deploy security analyzers in parallel -> Each finds different vulnerability classes -> Consensus coordinator validates, filters by project type, maps to OWASP/CWE -> Actionable Security Audit Report
@@ -409,8 +459,8 @@ Total: 7 findings (2 false positives excluded)
 
 ## Boundary Rules (No Overlap)
 
-- **vs audit:logic**: No race conditions, type bugs, control flow, edge cases - those are logic domain
-- **vs audit:legal**: No breach notification, PCI-DSS compliance, encryption requirements, negligence liability - those are legal domain
+- **vs code:logic**: No race conditions, type bugs, control flow, edge cases - those are logic domain
+- **vs code:legal**: No breach notification, PCI-DSS compliance, encryption requirements, negligence liability - those are legal domain
 - **vs security agent**: The `security.md` agent is a team member for story work. This is an on-demand analysis tool
 
 ---
@@ -436,8 +486,8 @@ Fix before merging? [Y/n]
 
 ## Related Commands
 
-- `/agileflow:audit:logic` - Logic bug analysis (similar architecture)
-- `/agileflow:audit:legal` - Legal compliance analysis (similar architecture)
+- `/agileflow:code:logic` - Logic bug analysis (similar architecture)
+- `/agileflow:code:legal` - Legal compliance analysis (similar architecture)
 - `/agileflow:review` - Code review (includes some security checks)
 - `/agileflow:multi-expert` - General multi-expert analysis
 - `/agileflow:verify` - Run tests

package/src/core/commands/{audit → code}/test.md

@@ -1,14 +1,14 @@
 ---
 description: Multi-agent test quality analysis with consensus voting for finding test suite weaknesses
-argument-hint: "[file|directory] [DEPTH=quick|deep] [FOCUS=coverage|fragility|mocking|assertions|structure|integration|maintenance|patterns|all]"
+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:
-    - "ACTIVE COMMAND: /agileflow:audit:test - Multi-agent test quality analysis"
+    - "ACTIVE COMMAND: /agileflow:code:test - Multi-agent test quality analysis"
     - "CRITICAL: Deploy analyzers IN PARALLEL in ONE message with multiple Task calls"
     - "CRITICAL: Wait for all results before running consensus (use TaskOutput with block=true)"
     - "CRITICAL: Confidence scoring: CONFIRMED (2+ agree), LIKELY (1 with evidence), INVESTIGATE (1 weak)"
-    - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep), FOCUS (coverage|fragility|mocking|assertions|structure|integration|maintenance|patterns|all)"
+    - "MUST parse arguments: TARGET (file/dir), DEPTH (quick/deep/ultradeep), FOCUS (coverage|fragility|mocking|assertions|structure|integration|maintenance|patterns|all)"
     - "Pass consensus all analyzer outputs, let it synthesize the final report"
   state_fields:
     - target_path
@@ -18,7 +18,7 @@ compact_context:
     - findings_collected
 ---
 
-# /agileflow:audit:test
+# /agileflow:code:test
 
 Deploy multiple specialized test quality analyzers in parallel to find weaknesses in the test suite, then synthesize results through consensus voting into a prioritized Test Quality Audit Report.
 
@@ -27,11 +27,11 @@ Deploy multiple specialized test quality analyzers in parallel to find weaknesse
 ## Quick Reference
 
 ```
-/agileflow:audit:test app/                                # Analyze app tests (quick, core 5 analyzers)
-/agileflow:audit:test . DEPTH=deep                        # Deep analysis - all 8 analyzers
-/agileflow:audit:test src/ FOCUS=coverage,mocking          # Focus on specific areas
-/agileflow:audit:test . DEPTH=deep FOCUS=all               # Comprehensive full audit
-/agileflow:audit:test __tests__/ FOCUS=fragility            # Check test fragility specifically
+/agileflow:code:test app/                                # Analyze app tests (quick, core 5 analyzers)
+/agileflow:code:test . DEPTH=deep                        # Deep analysis - all 8 analyzers
+/agileflow:code:test src/ FOCUS=coverage,mocking          # Focus on specific areas
+/agileflow:code:test . DEPTH=deep FOCUS=all               # Comprehensive full audit
+/agileflow:code:test __tests__/ FOCUS=fragility            # Check test fragility specifically
 ```
 
 ---
@@ -40,7 +40,7 @@ Deploy multiple specialized test quality analyzers in parallel to find weaknesse
 
 ```
 +-------------------------------------------------------------+
-|                    /agileflow:audit:test                      |
+|                    /agileflow:code:test                      |
 |                                                               |
 |  1. Parse arguments (target, depth, focus)                    |
 |  2. Deploy analyzers IN PARALLEL                              |
@@ -73,8 +73,9 @@ Deploy multiple specialized test quality analyzers in parallel to find weaknesse
 | Argument | Values | Default | Description |
 |----------|--------|---------|-------------|
 | TARGET | file/directory | `.` | What to analyze |
-| DEPTH | quick, deep | quick | quick = core 5 analyzers, deep = all 8 |
+| DEPTH | quick, deep, ultradeep | quick | quick = core 5, deep = all 8, ultradeep = separate tmux sessions |
 | FOCUS | coverage,fragility,mocking,assertions,structure,integration,maintenance,patterns,all | all | Which analyzers to deploy |
+| MODEL | haiku, sonnet, opus | haiku | Model for analyzer subagents. Default preserves existing behavior. |
 
 ---
 
@@ -107,6 +108,52 @@ FOCUS = all (default) or comma-separated list
 **DEPTH behavior**:
 - `quick` (default): Deploy core 5 analyzers. Focus on CRITICAL/HIGH issues only.
 - `deep`: Deploy all 8 analyzers. Include MEDIUM/LOW findings.
+- `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:
+   ```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 (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
 
@@ -368,13 +415,13 @@ FIX THIS SPRINT
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Command**: `/agileflow:audit:test` - Multi-agent test quality analysis with consensus
+**Command**: `/agileflow:code:test` - Multi-agent test quality analysis with consensus
 
 **Quick Usage**:
 ```
-/agileflow:audit:test app/                        # Quick scan (core 5 analyzers)
-/agileflow:audit:test . DEPTH=deep                # All 8 analyzers
-/agileflow:audit:test src/ FOCUS=coverage,mocking  # Specific areas
+/agileflow:code:test app/                        # Quick scan (core 5 analyzers)
+/agileflow:code:test . DEPTH=deep                # All 8 analyzers
+/agileflow:code:test src/ FOCUS=coverage,mocking  # Specific areas
 ```
 
 **What It Does**: Deploy test quality analyzers in parallel -> Each finds different test weakness classes -> Consensus coordinator validates, filters by project type, assesses false confidence risk -> Actionable Test Quality Audit Report
@@ -409,7 +456,7 @@ FIX THIS SPRINT
 
 ## Boundary Rules (No Overlap)
 
-- **vs audit:logic**: No logic bugs in application code — only test quality
+- **vs code:logic**: No logic bugs in application code — only test quality
 - **vs qa agent**: The `qa.md` agent is a team member for story work. This is an on-demand test analysis tool
 
 ---
@@ -435,8 +482,8 @@ Add error handling tests before merging? [Y/n]
 
 ## Related Commands
 
-- `/agileflow:audit:logic` - Logic bug analysis (similar architecture)
-- `/agileflow:audit:security` - Security vulnerability analysis (similar architecture)
-- `/agileflow:audit:performance` - Performance bottleneck analysis (similar architecture)
-- `/agileflow:audit:legal` - Legal compliance analysis (similar architecture)
+- `/agileflow:code:logic` - Logic bug analysis (similar architecture)
+- `/agileflow:code:security` - Security vulnerability analysis (similar architecture)
+- `/agileflow:code:performance` - Performance bottleneck analysis (similar architecture)
+- `/agileflow:code:legal` - Legal compliance analysis (similar architecture)
 - `/agileflow:verify` - Run tests

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