agileflow 2.91.0 → 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

@@ -337,3 +337,77 @@ Claude:
 - "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.md

@@ -1,6 +1,6 @@
 ---
 description: Create a user story with acceptance criteria
-argument-hint: EPIC=<EP-ID> STORY=<US-ID> TITLE=<text> OWNER=<id> [ESTIMATE=<pts>] [AC=<list>]
+argument-hint: EPIC=<EP-ID> STORY=<US-ID> TITLE=<text> OWNER=<id> [ESTIMATE=<pts>] [AC=<list>] [TDD=true]
 compact_context:
   priority: high
   preserve_rules:
@@ -12,12 +12,17 @@ compact_context:
     - "MUST use AskUserQuestion for user confirmation (YES/NO/CANCEL format)"
     - "MUST create test stub in docs/07-testing/test-cases/<STORY>.md referencing AC"
     - "AC format: Given/When/Then bullets (user story format)"
+    - "TDD=true: Generate framework-specific test code BEFORE implementation"
+    - "TDD=true: Parse Given/When/Then into describe/it blocks (Jest) or test functions (pytest)"
+    - "TDD=true: All tests start as .skip or @pytest.mark.skip (pending)"
+    - "TDD=true: Add tdd_mode:true and test_file fields to status.json entry"
   state_fields:
     - story_id
     - epic_id
     - owner
     - estimate
     - ac_count
+    - tdd_mode
 ---
 
 # story-new
@@ -44,7 +49,7 @@ node .agileflow/scripts/obtain-context.js story
 
 ### 🚨 RULE #1: ALWAYS Create TodoWrite Task List FIRST
 
-Create a 6-step task list IMMEDIATELY:
+Create a task list IMMEDIATELY (7 steps if TDD=true, 6 steps otherwise):
 ```xml
 <invoke name="TodoWrite">
 <parameter name="content">1. Parse inputs (EPIC, STORY, TITLE, OWNER, ESTIMATE, AC)
@@ -94,7 +99,45 @@ Test stub MUST reference AC:
 - Map each test to an AC bullet
 - Use BDD format (describe, test cases for each AC)
 
-### 🚨 RULE #5: NEVER Use echo/cat > For JSON Operations
+### 🚨 RULE #5: TDD MODE (Smart Defaults)
+
+**Smart TDD defaults based on OWNER:**
+| Owner | Default | Rationale |
+|-------|---------|-----------|
+| AG-API, AG-UI, AG-DATABASE | TDD=true | Code-focused, tests critical |
+| AG-TESTING, AG-SECURITY, AG-PERFORMANCE | TDD=true | Quality-focused |
+| AG-DOCUMENTATION, AG-RESEARCH, AG-PRODUCT | TDD=false | Non-code work |
+| AG-DEVOPS, AG-CI | TDD=false | Infrastructure, config |
+| Other/Custom | TDD=false | Explicit opt-in |
+
+**Override:** User can always specify `TDD=true` or `TDD=false` explicitly.
+
+When TDD mode is active, generate framework-specific test code:
+
+**Workflow:**
+1. Detect test framework from `environment.json` or `package.json`
+2. Parse AC into Given/When/Then structure
+3. Generate test file using `tdd-test-template.js`
+4. Create test in `__tests__/<STORY>.test.ts` (Jest) or `tests/test_<STORY>.py` (pytest)
+5. All tests start as `.skip` (pending)
+6. Add `tdd_mode: true` and `test_file` to status.json entry
+7. Add TDD badge to story file
+
+**Test File Location:**
+- Jest/Vitest: `__tests__/<STORY_ID>.test.ts`
+- pytest: `tests/test_<STORY_ID>.py`
+- Go: `<package>/<STORY_ID>_test.go`
+
+**Status.json Entry (TDD mode):**
+```json
+{
+  "tdd_mode": true,
+  "test_file": "__tests__/US-0042.test.ts",
+  "test_status": "not_run"
+}
+```
+
+### 🚨 RULE #6: NEVER Use echo/cat > For JSON Operations
 
 **ALWAYS use**:
 - Edit tool for small changes
@@ -114,6 +157,7 @@ OWNER=<id>                 # Agent or person name (required)
 ESTIMATE=<time>            # e.g., 0.5d, 2h (optional, default: 1d)
 AC=<bullets>               # Given/When/Then format (optional)
 DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
+TDD=true|false             # TDD mode (smart default: true for code owners, false for docs/research)
 ```
 
 **Output Files Created**:
@@ -121,6 +165,7 @@ DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
 |------|---------|----------|
 | docs/06-stories/EP-<ID>/US-<ID>-<slug>.md | Story with AC | story-template.md |
 | docs/07-testing/test-cases/US-<ID>.md | Test stub | BDD format |
+| __tests__/US-<ID>.test.ts | TDD test code (if TDD=true) | tdd-test-template.js |
 | docs/09-agents/status.json | Story entry | jq merge |
 | docs/09-agents/bus/log.jsonl | Assign event | JSONL line |
 
@@ -202,8 +247,9 @@ DEPENDENCIES=[<list>]      # Dependent story IDs (optional)
 - ALWAYS create test stub referencing AC
 - ALWAYS preview before confirming (prevents mistakes)
 - ALWAYS validate JSON after merge (prevents corruption)
-- Use TodoWrite for step tracking (6 steps)
+- Use TodoWrite for step tracking (6 steps, or 7 if TDD=true)
 - Files: story file, test file, status.json, bus/log.jsonl
+- **TDD=true**: Also create framework-specific test code in `__tests__/` with pending tests
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -324,3 +370,96 @@ After successfully creating the story, offer next steps:
 - `/agileflow:story-validate` - Validate story completeness
 - `/agileflow:status` - Update story status
 - `/agileflow:epic` - Create parent epic
+
+---
+
+## Expected Output
+
+### Successful Story Creation
+
+```
+📝 Creating Story: US-0042
+
+Epic: EP-0010
+Title: Login Form with Validation
+Owner: AG-UI
+Estimate: 2h
+TDD Mode: true (smart default for AG-UI)
+
+Files to create:
+───────────────────────────
+1. docs/06-stories/EP-0010/US-0042-login-form-validation.md
+   - Story file with 3 acceptance criteria
+
+2. docs/07-testing/test-cases/US-0042.md
+   - Test stub referencing AC
+
+3. __tests__/US-0042.test.ts (TDD mode)
+   - 3 pending test cases from AC
+
+4. docs/09-agents/status.json (merge)
+   + "US-0042": {
+   +   "id": "US-0042",
+   +   "epic": "EP-0010",
+   +   "owner": "AG-UI",
+   +   "status": "ready",
+   +   "estimate": "2h",
+   +   "tdd_mode": true,
+   +   "test_file": "__tests__/US-0042.test.ts"
+   + }
+
+5. docs/09-agents/bus/log.jsonl (append)
+   + {"ts":"...","type":"assign","from":"SYSTEM","to":"AG-UI","story":"US-0042"}
+
+[AskUserQuestion: "Create story US-0042: Login Form with Validation?"]
+
+✅ Story US-0042 created successfully!
+✅ Test stub created: docs/07-testing/test-cases/US-0042.md
+✅ TDD tests created: __tests__/US-0042.test.ts (3 pending)
+✅ Bus message sent: assign → AG-UI
+
+[AskUserQuestion: "What would you like to do next?"]
+```
+
+### Story with Dependencies
+
+```
+📝 Creating Story: US-0043
+
+Dependencies: US-0042 (Login Form)
+
+⚠️ Dependency Status:
+  • US-0042: ready (not yet done)
+
+[AskUserQuestion: "Create story with pending dependency?"]
+  - Yes, create anyway (dependency will block)
+  - No, wait for US-0042
+
+✅ Story US-0043 created
+⚠️ Status set to 'blocked' (waiting on US-0042)
+```
+
+### Validation Error
+
+```
+❌ Invalid Input
+
+Missing required parameters:
+  • EPIC - Parent epic ID (e.g., EP-0010)
+  • TITLE - Story title
+
+Usage:
+/agileflow:story EPIC=EP-0010 STORY=US-0042 TITLE="Login Form" OWNER=AG-UI
+```
+
+### TDD Mode Detection
+
+```
+📝 Story Creation
+
+Owner: AG-DOCUMENTATION
+TDD Mode: false (smart default - documentation work)
+
+ℹ️ To enable TDD mode, add TDD=true to the command:
+   /agileflow:story ... TDD=true
+```

package/src/core/templates/agileflow-metadata.json

@@ -1,8 +1,61 @@
 {
+  "schema_version": "2.0.0",
+  "config_schema_version": "2.92.0",
+  "active_profile": null,
   "agileflow": {
     "version": "2.28.0",
-    "setupDate": "TIMESTAMP_PLACEHOLDER",
-    "lastValidated": null,
+    "setup_date": "TIMESTAMP_PLACEHOLDER",
+    "last_validated": null,
+    "config_options": {
+      "claudeMdReinforcement": {
+        "available_since": "2.92.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Add /babysit AskUserQuestion rules to CLAUDE.md"
+      },
+      "sessionStartHook": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Welcome display with project status on session start"
+      },
+      "precompactHook": {
+        "available_since": "2.40.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Context preservation when conversation compacts"
+      },
+      "damageControlHooks": {
+        "available_since": "2.50.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Block destructive commands, protect sensitive paths"
+      },
+      "statusLine": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Custom status bar showing story/epic info"
+      },
+      "autoArchival": {
+        "available_since": "2.35.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Auto-archive completed stories older than threshold"
+      },
+      "autoUpdate": {
+        "available_since": "2.70.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Automatically update AgileFlow on session start"
+      },
+      "ralphLoop": {
+        "available_since": "2.60.0",
+        "configured": false,
+        "enabled": false,
+        "description": "Autonomous story processing with test verification"
+      }
+    },
     "features": {
       "epics": true,
       "stories": true,

package/src/core/templates/plan-template.md

@@ -0,0 +1,125 @@
+---
+plan_id: {{PLAN_ID}}
+epic: {{EPIC_ID}}
+title: {{TITLE}}
+created: {{CREATED}}
+---
+
+# {{TITLE}}
+
+## Overview
+
+{{GOAL}}
+
+---
+
+## Phase 1: Foundation (Sequential)
+
+<!-- Stories that must complete before parallel work can begin -->
+<!-- These have no dependencies or are prerequisites for everything else -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+
+---
+
+## Phase 2: Features (Parallel-eligible)
+
+<!-- Stories that can run in parallel sessions -->
+<!-- All depend only on Phase 1 completion -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session A)
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session B)
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session C)
+
+---
+
+## Phase 3: Integration (Sequential)
+
+<!-- Stories that depend on Phase 2 completion -->
+<!-- Must wait for parallel work to merge -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+
+---
+
+## Deviations Log
+
+<!-- Track decisions that differ from original plan -->
+<!-- Important: Keep this updated so next sessions have context -->
+
+| Date | Phase | Original | Changed To | Reason |
+|------|-------|----------|------------|--------|
+| | | | | |
+
+---
+
+## Session Prompts
+
+<!-- Copy-paste prompts for new parallel sessions -->
+<!-- Customize based on specific stories in Phase 2 -->
+
+### Session A prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task A: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+### Session B prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task B: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+### Session C prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task C: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+---
+
+## Verification Session
+
+<!-- Keep one terminal dedicated to plan verification -->
+<!-- After each phase, run these checks -->
+
+### Phase completion checks:
+```
+After Phase 1:
+- [ ] All Phase 1 checkboxes checked
+- [ ] Tests passing
+- [ ] No uncommitted changes
+- [ ] Ready to spawn parallel sessions
+
+After Phase 2:
+- [ ] All Phase 2 checkboxes checked
+- [ ] All parallel branches merged
+- [ ] No merge conflicts
+- [ ] Integration tests passing
+
+After Phase 3:
+- [ ] All Phase 3 checkboxes checked
+- [ ] Final tests passing
+- [ ] Ready for review/deploy
+```
+
+---
+
+## Notes
+
+<!-- Additional context, risks, or decisions -->
+<!-- Reference ADRs if architectural decisions were made -->
+