agileflow 2.90.7 → 2.92.0

package/src/core/commands/session/spawn.md

@@ -0,0 +1,197 @@
+---
+description: Spawn multiple parallel Claude Code sessions in git worktrees
+argument-hint: [--count N | --branches a,b,c | --from-epic EP-XXX]
+compact_context:
+  priority: high
+  preserve_rules:
+    - "ACTIVE COMMAND: /agileflow:session:spawn - Spawn multiple parallel sessions"
+    - "Creates multiple git worktrees with session-manager.js"
+    - "Auto-copies .env files to each worktree"
+    - "Optionally spawns Claude in tmux windows"
+    - "Options: --count N, --branches 'a,b,c', --from-epic EP-XXX"
+    - "Flags: --init (run claude init), --dangerous (skip permissions), --no-tmux"
+  state_fields:
+    - session_count
+    - branches_list
+    - epic_id
+    - tmux_session_name
+---
+
+# /agileflow:session:spawn
+
+Spawn multiple parallel Claude Code sessions in git worktrees with optional tmux integration.
+
+---
+
+## Purpose
+
+When you need to run multiple Claude Code instances in parallel on isolated tasks, this command:
+- Creates N git worktrees (each with its own branch)
+- Auto-copies `.env` files to each worktree
+- Optionally spawns Claude in tmux windows for easy navigation
+- Tracks all sessions in the session registry
+
+Based on the [git worktrees parallel sessions research](../../../10-research/20260121-claude-code-git-worktrees-parallel.md).
+
+---
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Parse Arguments
+
+Extract from ARGUMENTS:
+- `--count N` - Number of sessions to create (e.g., `--count 4`)
+- `--branches "a,b,c"` - Specific branch names (comma-separated)
+- `--from-epic EP-XXX` - Create sessions for ready stories in epic
+- `--init` - Run `claude init` in each worktree
+- `--dangerous` - Use `--dangerouslySkipPermissions`
+- `--no-tmux` - Just create worktrees, output commands manually
+
+At least one of `--count`, `--branches`, or `--from-epic` is required.
+
+### Step 2: Create Todo List
+
+```xml
+<invoke name="TodoWrite">
+<parameter name="todos">[
+  {"content": "Validate arguments", "status": "in_progress", "activeForm": "Validating arguments"},
+  {"content": "Create parallel sessions", "status": "pending", "activeForm": "Creating sessions"},
+  {"content": "Spawn in tmux (if applicable)", "status": "pending", "activeForm": "Spawning in tmux"},
+  {"content": "Display navigation help", "status": "pending", "activeForm": "Displaying help"}
+]</parameter>
+</invoke>
+```
+
+### Step 3: Run Spawn Script
+
+Build the command based on arguments:
+
+```bash
+# Example: Create 4 sessions
+node .agileflow/scripts/spawn-parallel.js spawn --count 4
+
+# Example: Create from branches
+node .agileflow/scripts/spawn-parallel.js spawn --branches "auth,dashboard,api"
+
+# Example: Create from epic
+node .agileflow/scripts/spawn-parallel.js spawn --from-epic EP-0025
+
+# Example: With init and no tmux
+node .agileflow/scripts/spawn-parallel.js spawn --count 3 --init --no-tmux
+```
+
+### Step 4: Display Results
+
+The script will output:
+- Created session IDs and paths
+- Copied env files
+- Tmux session name and navigation keys (if tmux available)
+- Manual commands (if --no-tmux or no tmux available)
+
+---
+
+## Examples
+
+### Create 4 Generic Parallel Sessions
+
+```
+/agileflow:session:spawn --count 4
+```
+
+Creates:
+- `../Project-1/` (branch: parallel-1)
+- `../Project-2/` (branch: parallel-2)
+- `../Project-3/` (branch: parallel-3)
+- `../Project-4/` (branch: parallel-4)
+
+### Create Sessions for Specific Features
+
+```
+/agileflow:session:spawn --branches "auth,dashboard,api,admin"
+```
+
+Creates:
+- `../Project-auth/` (branch: feature/auth)
+- `../Project-dashboard/` (branch: feature/dashboard)
+- `../Project-api/` (branch: feature/api)
+- `../Project-admin/` (branch: feature/admin)
+
+### Create Sessions from Epic Stories
+
+```
+/agileflow:session:spawn --from-epic EP-0025
+```
+
+Creates one session per "ready" story in the epic.
+
+### With Claude Init (Primes Context)
+
+```
+/agileflow:session:spawn --count 2 --init
+```
+
+Runs `claude init` in each worktree to generate CLAUDE.md with project context.
+
+### Without Tmux (Manual Mode)
+
+```
+/agileflow:session:spawn --count 4 --no-tmux
+```
+
+Just creates worktrees and outputs commands to run manually.
+
+---
+
+## Tmux Navigation
+
+If tmux is available, the script creates a tmux session with one window per Claude instance:
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+b n` | Next window |
+| `Ctrl+b p` | Previous window |
+| `Ctrl+b 0-9` | Go to window N |
+| `Ctrl+b d` | Detach (sessions keep running) |
+| `tmux attach -t <name>` | Reattach to session |
+
+---
+
+## Managing Spawned Sessions
+
+```bash
+# List all parallel sessions
+/agileflow:session:status
+
+# Check on a specific session
+/agileflow:session:resume 2
+
+# End and merge a session
+/agileflow:session:end 3 --merge
+
+# Kill all tmux parallel sessions
+node .agileflow/scripts/spawn-parallel.js kill-all
+```
+
+---
+
+## Environment Files
+
+The following files are automatically copied to each worktree:
+- `.env`
+- `.env.local`
+- `.env.development`
+- `.env.test`
+- `.env.production`
+
+This ensures each Claude instance has access to necessary environment variables.
+
+---
+
+## Related Commands
+
+- `/agileflow:session:new` - Create a single parallel session interactively
+- `/agileflow:session:status` - View all sessions
+- `/agileflow:session:end` - End a session with optional merge
+- `/agileflow:session:resume` - Switch to another session

package/src/core/commands/sprint.md

@@ -563,6 +563,28 @@ Committed: X stories, Y.Z estimated days (Y% of capacity)
    - Has 1 story in review (US-0038) likely to complete soon
    - If US-0038 completes early, can pick up deferred US-0055
 
+🔀 PARALLELIZATION ANALYSIS
+---------------------------
+Stories grouped by execution phase for multi-session workflows:
+
+Phase 1 (Sequential - Foundation):
+  These must complete first - no dependencies, prerequisite for others.
+  - US-0043: POST /auth/login endpoint (AG-API)
+
+Phase 2 (Parallel-eligible):
+  Can run in separate Claude Code sessions simultaneously.
+  All depend only on Phase 1 completion.
+  - US-0042: User login form (Session A)
+  - US-0045: User profile page (Session B)
+  └─ Run `/agileflow:session:new` for each parallel task
+
+Phase 3 (Integration - Sequential):
+  Must wait for Phase 2 completion.
+  - US-0050: E2E tests for auth flow (depends on Phase 2)
+
+💡 For multi-session work, create plan.md with:
+   `/agileflow:templates/plan-template.md` or copy from templates/
+
 💡 RECOMMENDATIONS
 ------------------
 1. Sequence stories: US-0043 (AG-API) → US-0042 (AG-UI) → US-0050 (AG-CI)

package/src/core/commands/status.md

@@ -12,11 +12,14 @@ compact_context:
     - "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)"
+    - "PHASE HANDOFF: Prompt for summary on phase transitions (ready→in-progress, in-progress→in-review, in-review→done)"
   state_fields:
     - story_id
     - current_status
     - new_status
     - pr_url
+    - phase_from
+    - phase_to
 ---
 
 # status
@@ -105,6 +108,7 @@ TO=<agent-id>           # Recipient agent for bus message (optional)
   "stories": {
     "US-0042": {
       "status": "in-progress",
+      "phase": "execute",
       "summary": "Started work on login form",
       "pr": "https://github.com/.../pull/42",
       "last_update": "ISO-timestamp"
@@ -113,6 +117,15 @@ TO=<agent-id>           # Recipient agent for bus message (optional)
 }
 ```
 
+**Phase Field** (auto-set based on status):
+| Status | Phase |
+|--------|-------|
+| ready | plan |
+| in-progress | execute |
+| blocked | execute |
+| in-review | audit |
+| done | complete |
+
 **Append to bus/log.jsonl**:
 ```json
 {"ts":"ISO-timestamp","from":"SYSTEM","to":"<TO or ALL>","type":"status","story":"<STORY>","status":"<STATUS>","text":"<SUMMARY>"}
@@ -146,6 +159,7 @@ docs/09-agents/status.json
 
 - "status": "ready",
 + "status": "in-progress",
++ "phase": "execute",
 + "summary": "Started work on login form",
 + "pr": "https://github.com/.../pull/42",
 ```
@@ -178,6 +192,7 @@ docs/09-agents/status.json
 - ALWAYS show diff before confirming
 - Status values: ready, in-progress, blocked, in-review, done
 - Text escaping handled automatically by jq
+- **PHASE HANDOFF**: On phase transitions (ready→in-progress, in-progress→in-review, in-review→done), prompt for handoff summary and log to bus/log.jsonl with type "phase_handoff"
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -192,7 +207,8 @@ STORY=<US-ID>  STATUS=in-progress|blocked|in-review|done
 SUMMARY=<1–2 lines>  PR=<url optional>  TO=<agent id optional>
 
 ACTIONS
-1) Update docs/09-agents/status.json (status,summary,last_update,pr).
+1) Update docs/09-agents/status.json (status,phase,summary,last_update,pr).
+   - Set phase based on status: ready→plan, in-progress/blocked→execute, in-review→audit, done→complete
    **CRITICAL**: Always use jq for JSON operations to prevent corruption.
 2) **Validate JSON after update**:
    ```bash
@@ -212,3 +228,186 @@ ACTIONS
 - If validation fails, restore from backup: docs/09-agents/status.json.backup
 
 Diff-first; YES/NO.
+
+---
+
+## Phase Handoff (GSD Integration)
+
+When status transitions indicate a phase change, prompt for a handoff summary to capture context for the next phase.
+
+### Phase Transitions
+
+| Status Change | Phase Transition | Handoff Prompt |
+|--------------|------------------|----------------|
+| ready → in-progress | plan → execute | "What's the plan for implementing this story?" |
+| in-progress → in-review | execute → audit | "What was implemented? Any issues encountered?" |
+| in-review → done | audit → complete | "Final summary: What was delivered?" |
+
+### Handoff Workflow
+
+**Step 1: Detect Phase Transition**
+
+Before updating status, check if this is a phase-changing transition:
+```javascript
+const phaseTransitions = {
+  'ready→in-progress': { from: 'plan', to: 'execute' },
+  'in-progress→in-review': { from: 'execute', to: 'audit' },
+  'in-review→done': { from: 'audit', to: 'complete' }
+};
+const key = `${currentStatus}→${newStatus}`;
+const transition = phaseTransitions[key];
+```
+
+**Step 2: Prompt for Handoff Summary**
+
+If a phase transition is detected, prompt BEFORE the status confirmation:
+
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Phase transition: {{FROM}} → {{TO}}. Summarize what was accomplished:",
+  "header": "Handoff",
+  "multiSelect": false,
+  "options": [
+    {"label": "Enter summary", "description": "Capture context for next phase"},
+    {"label": "Skip handoff", "description": "No summary needed"}
+  ]
+}]</parameter>
+</invoke>
+```
+
+**Step 3: Log Phase Handoff**
+
+If summary provided, append to bus/log.jsonl:
+```json
+{
+  "ts": "2026-01-19T12:00:00Z",
+  "type": "phase_handoff",
+  "story": "US-0130",
+  "from": "plan",
+  "to": "execute",
+  "summary": "User's handoff summary here"
+}
+```
+
+### Example Flow
+
+```
+User: /agileflow:status US-0042 STATUS=in-progress
+
+Claude:
+📋 Phase Transition Detected: plan → execute
+
+Before updating status, let's capture a handoff summary.
+
+[AskUserQuestion: "What's the plan for implementing this story?"]
+
+User: "Adding login form with email/password validation, using React Hook Form"
+
+Claude:
+✅ Handoff captured
+
+docs/09-agents/status.json
+- "status": "ready",
++ "status": "in-progress",
++ "last_update": "2026-01-19T12:00:00Z"
+
+[AskUserQuestion: "Update US-0042 to in-progress?"]
+
+User: "Yes, update"
+
+Claude:
+✅ Status updated: US-0042 → in-progress
+✅ Phase handoff logged: plan → execute
+```
+
+### Handoff Prompts by Transition
+
+**plan → execute** (ready → in-progress):
+- "What's the implementation approach?"
+- "Any architectural decisions made?"
+- "Key files to be modified?"
+
+**execute → audit** (in-progress → in-review):
+- "What was implemented?"
+- "Any issues or blockers encountered?"
+- "Tests passing? Coverage notes?"
+
+**audit → complete** (in-review → done):
+- "Final summary of what was delivered"
+- "Any technical debt introduced?"
+- "Lessons learned?"
+
+---
+
+## Expected Output
+
+### Successful Status Update
+
+```
+📋 Status Update for US-0042
+
+Current: ready (plan phase)
+New: in-progress (execute phase)
+
+docs/09-agents/status.json
+───────────────────────────
+- "status": "ready",
+- "phase": "plan",
++ "status": "in-progress",
++ "phase": "execute",
++ "summary": "Started work on login form",
++ "last_update": "2026-01-21T14:30:00Z"
+
+[AskUserQuestion: "Update US-0042 to in-progress?"]
+
+✅ Status updated: US-0042 → in-progress
+✅ Bus message sent to: ALL
+```
+
+### With Phase Handoff
+
+```
+📋 Phase Transition Detected: plan → execute
+
+Before updating status, let's capture a handoff summary.
+
+[AskUserQuestion: "What's the plan for implementing this story?"]
+
+User: "Adding login form with email/password validation"
+
+✅ Handoff captured
+
+docs/09-agents/status.json
+───────────────────────────
+- "status": "ready",
++ "status": "in-progress",
++ "summary": "Adding login form with email/password validation"
+
+[AskUserQuestion: "Update US-0042 to in-progress?"]
+
+✅ Status updated: US-0042 → in-progress
+✅ Phase handoff logged: plan → execute
+```
+
+### Validation Error
+
+```
+❌ Invalid status value: "in_progress"
+
+Valid values are:
+  • 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
+```
+
+### JSON Corruption Recovery
+
+```
+❌ ERROR: status.json is now invalid JSON after update!
+
+Fix: Restoring from backup: docs/09-agents/status.json.backup
+✅ Backup restored successfully
+```

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

@@ -76,17 +76,17 @@ Format output as table grouped by epic:
 ## 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 |
+| Story | Title | Status | Phase | Owner | Estimate |
+|-------|-------|--------|-------|-------|----------|
+| US-0001 | Login form | done | complete | AG-UI | 2h |
+| US-0002 | Password reset | in_progress | execute | AG-API | 3h |
+| US-0003 | Session management | ready | plan | 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 |
+| Story | Title | Status | Phase | Owner | Estimate |
+|-------|-------|--------|-------|-------|----------|
+| US-0004 | Dashboard layout | ready | plan | AG-UI | 2h |
+| US-0005 | Activity feed | ready | plan | AG-UI | 3h |
 
 ---
 **Summary**: 5 stories (1 done, 1 in_progress, 3 ready)

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

@@ -92,6 +92,7 @@ cat docs/07-testing/test-cases/<STORY>.md
 
 **Epic**: EP-0001 (Authentication System)
 **Status**: in_progress
+**Phase**: execute
 **Owner**: AG-UI
 **Estimate**: 3h
 **Created**: 2024-12-28