agileflow 2.51.0 → 2.55.0

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

@@ -3,484 +3,82 @@ description: Initialize session harness with test verification
 argument-hint: (no arguments)
 ---
 
-# Session Harness Initialization
+# /agileflow:session:init
 
-You are running the `/agileflow:session:init` command to set up test verification and session management.
+Initialize or verify the session management system.
 
-## IMMEDIATE ACTIONS
-
-**Execute these steps NOW in order:**
-
-### Step 1: Check if already initialized
-```bash
-ls docs/00-meta/environment.json 2>/dev/null && echo "Already initialized" || echo "Not initialized"
-ls docs/09-agents/session-state.json 2>/dev/null
-```
-If both files exist, ask user if they want to reinitialize.
-
-### Step 2: Detect project type
-```bash
-ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
-```
-Identify: nodejs (package.json), python (pyproject.toml), rust (Cargo.toml), go (go.mod)
-
-### Step 3: Detect test command
-For Node.js:
-```bash
-jq -r '.scripts.test // "npm test"' package.json 2>/dev/null
-```
-
-### Step 4: Create environment.json
-Use Write tool to create `docs/00-meta/environment.json`:
-```json
-{
-  "project_type": "{detected}",
-  "test_command": "{detected}",
-  "test_timeout_ms": 60000,
-  "created_at": "{now}",
-  "updated_at": "{now}"
-}
-```
-
-### Step 5: Ensure session-state.json exists
-Check if `docs/09-agents/session-state.json` exists. If not, create it with the MVP schema.
-
-### Step 6: Display summary
-Output what was created and next steps.
-
-## TODO LIST TRACKING
-
-**CRITICAL**: Immediately create a todo list using TodoWrite tool:
-```
-1. Check if already initialized
-2. Detect project type
-3. Detect test command
-4. Create docs/00-meta/environment.json
-5. Ensure session-state.json exists
-6. Display summary
-```
-
-Mark each step complete as you finish it.
-
-## Prerequisites
-
-- AgileFlow must be initialized (`/agileflow:setup` must have been run)
-- Project must have a test suite configured
-- Must be in project root directory
-
-## Execution Flow
-
-### 1. Pre-flight Checks
+---
 
-```bash
-# Verify AgileFlow is initialized
-if [ ! -f "docs/09-agents/status.json" ]; then
-  echo "❌ AgileFlow not initialized"
-  echo ""
-  echo "Run /agileflow:setup first to create the docs structure"
-  exit 1
-fi
+## Purpose
 
-# Verify not already initialized
-if [ -f "docs/00-meta/environment.json" ]; then
-  echo "⚠️  Session harness already initialized"
-  echo ""
-  echo "Found existing docs/00-meta/environment.json"
-  echo ""
-  echo "Options:"
-  echo "  1. Continue (overwrite existing configuration)"
-  echo "  2. Skip initialization"
-  echo ""
-  read -p "Choice [1/2]: " choice
+Sets up session tracking infrastructure:
+- Creates `.agileflow/sessions/` directory
+- Initializes `registry.json` if missing
+- Registers the current session
+- Displays session status
 
-  if [ "$choice" != "1" ]; then
-    echo "Skipping initialization"
-    exit 0
-  fi
-fi
-```
+This command is typically called automatically by the SessionStart hook.
 
-### 2. Project Type Detection
+## IMMEDIATE ACTIONS
 
-Auto-detect project type and test framework:
+### Step 1: Ensure Session Infrastructure
 
-**Node.js Detection:**
 ```bash
-if [ -f "package.json" ]; then
-  PROJECT_TYPE="nodejs"
-
-  # Detect test command from package.json
-  if grep -q '"test":' package.json; then
-    TEST_COMMAND=$(jq -r '.scripts.test // "npm test"' package.json)
-  else
-    TEST_COMMAND="npm test"
-  fi
-
-  # Detect dev server
-  if grep -q '"dev":' package.json; then
-    DEV_COMMAND=$(jq -r '.scripts.dev // "npm run dev"' package.json)
-  fi
-fi
+node .agileflow/scripts/session-manager.js register
 ```
 
-**Python Detection:**
-```bash
-if [ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
-  PROJECT_TYPE="python"
-
-  # Detect test framework
-  if grep -q pytest requirements.txt 2>/dev/null; then
-    TEST_COMMAND="pytest"
-  elif grep -q unittest requirements.txt 2>/dev/null; then
-    TEST_COMMAND="python -m unittest discover"
-  else
-    TEST_COMMAND="pytest"
-  fi
-fi
-```
+This will:
+- Create `.agileflow/sessions/` if missing
+- Create `registry.json` with schema if missing
+- Register current directory as a session
+- Create lock file with current PID
 
-**Rust Detection:**
-```bash
-if [ -f "Cargo.toml" ]; then
-  PROJECT_TYPE="rust"
-  TEST_COMMAND="cargo test"
-  DEV_COMMAND="cargo run"
-fi
-```
+### Step 2: Check for Other Active Sessions
 
-**Go Detection:**
 ```bash
-if [ -f "go.mod" ]; then
-  PROJECT_TYPE="go"
-  TEST_COMMAND="go test ./..."
-  DEV_COMMAND="go run ."
-fi
-```
-
-**Detection Summary:**
-```
-🔍 Project Detection Results
-
-Project type: nodejs
-Test command: npm test
-Dev server: npm run dev (port 3000)
+node .agileflow/scripts/session-manager.js count
 ```
 
-### 3. User Confirmation
+If `count > 0`, there are other active sessions.
 
-Confirm detected settings with user:
+### Step 3: Display Status
 
+**If no other sessions:**
 ```
-Detected configuration:
-  Project Type: nodejs
-  Test Command: npm test
-  Dev Server: npm run dev
+✓ Session initialized
 
-Is this correct? [Y/n]: _
-```
+  Session ID: 1
+  Path: /home/user/project
+  Branch: main
 
-If not correct:
-```
-Enter test command (or press Enter to skip): _
-Enter dev server command (or press Enter to skip): _
-Enter dev server port (default 3000): _
-Enter ready pattern (default "Ready"): _
+No other active sessions detected.
 ```
 
-### 4. Create environment.json
-
-Generate `docs/00-meta/environment.json` from template:
-
-```json
-{
-  "$schema": "https://json-schema.org/draft-07/schema#",
-  "description": "AgileFlow session harness environment configuration",
-  "project_type": "nodejs",
-  "init_script": "./docs/00-meta/init.sh",
-  "test_command": "npm test",
-  "test_timeout_ms": 60000,
-  "dev_server": {
-    "command": "npm run dev",
-    "port": 3000,
-    "ready_pattern": "Ready on"
-  },
-  "verification_policy": "warn",
-  "baseline_commit": null,
-  "baseline_established": null,
-  "created_at": "2025-12-06T10:00:00Z",
-  "updated_at": "2025-12-06T10:00:00Z"
-}
+**If other sessions active:**
 ```
+✓ Session initialized
 
-### 5. Create init.sh
+  Session ID: 1 (current)
+  Path: /home/user/project
+  Branch: main
 
-Copy template from `templates/init.sh` to `docs/00-meta/init.sh`:
-
-```bash
-cp templates/init.sh docs/00-meta/init.sh
-chmod +x docs/00-meta/init.sh
-
-# Customize based on project type
-sed -i "s/{{PROJECT_TYPE}}/$PROJECT_TYPE/g" docs/00-meta/init.sh
+⚠️ {count} other session(s) active in this repo.
+   Run /agileflow:session:status to see all sessions.
+   Run /agileflow:session:new to create isolated workspace.
 ```
 
-### 6. Create session-state.json
-
-Initialize session state file:
+## Already Initialized Case
 
-```json
-{
-  "$schema": "https://json-schema.org/draft-07/schema#",
-  "description": "AgileFlow session state tracking",
-  "current_session": {
-    "id": "sess-20251206-100000",
-    "started_at": "2025-12-06T10:00:00Z",
-    "baseline_verified": false,
-    "initial_test_status": "not_run",
-    "current_story": null,
-    "active_agent": null
-  },
-  "last_session": {
-    "id": null,
-    "ended_at": null,
-    "stories_completed": [],
-    "final_test_status": "not_run",
-    "commits": []
-  },
-  "session_history": []
-}
+If session is already registered:
 ```
+✓ Session already active
 
-### 7. Run Initial Test Verification
-
-Run `/agileflow:verify` to establish baseline test status:
-
-```
-🧪 Running initial test verification...
-
-Command: npm test
-```
-
-**If tests pass:**
-```
-✅ Tests passed (42/42)
-
-Baseline test status: passing
-All systems ready for session tracking
-```
-
-**If tests fail:**
-```
-⚠️  Tests failed (40/42)
-
-Failed tests:
-  ❌ auth.test.ts:42 - Expected redirect
-  ❌ auth.test.ts:67 - Session not persisting
-
-Recommendation: Fix failing tests before proceeding
-Continue anyway? [y/N]: _
-```
-
-### 8. Create Baseline Tag (Optional)
-
-If tests are passing, offer to create baseline:
-
-```
-Create baseline git tag? [Y/n]: _
-```
-
-If yes:
-```bash
-TAG_NAME="agileflow-baseline-$(date +%Y%m%d-%H%M%S)"
-git tag -a "$TAG_NAME" -m "AgileFlow baseline: all tests passing"
-
-# Update environment.json
-COMMIT_SHA=$(git rev-parse HEAD)
-# Update baseline_commit and baseline_established fields
-```
-
-### 9. Configure SessionStart Hook
-
-Offer to add automatic session resumption:
-
-```
-Enable automatic session resumption on startup? [Y/n]: _
-
-This will:
-  - Run session resume script on every Claude Code session start
-  - Verify tests and load context automatically
-  - Show session summary with recent activity
-```
-
-If yes:
-```bash
-# Copy resume script from AgileFlow plugin
-cp ~/.claude-code/plugins/AgileFlow/templates/resume-session.sh docs/00-meta/resume-session.sh
-chmod +x docs/00-meta/resume-session.sh
-
-# Create or update .claude/settings.json
-mkdir -p .claude
-
-if [ -f ".claude/settings.json" ]; then
-  # Merge with existing settings using jq
-  echo "Updating existing .claude/settings.json..."
-
-  # Add SessionStart hook if it doesn't exist
-  jq '.hooks.SessionStart += [{
-    "matcher": "",
-    "hooks": [{
-      "type": "command",
-      "command": "bash docs/00-meta/resume-session.sh"
-    }]
-  }]' .claude/settings.json > .claude/settings.json.tmp && mv .claude/settings.json.tmp .claude/settings.json
-else
-  # Create new settings.json
-  cat > .claude/settings.json <<'EOF'
-{
-  "hooks": {
-    "SessionStart": [{
-      "matcher": "",
-      "hooks": [{
-        "type": "command",
-        "command": "bash docs/00-meta/resume-session.sh"
-      }]
-    }]
-  }
-}
-EOF
-fi
-
-echo "✅ SessionStart hook configured"
-echo "✅ docs/00-meta/resume-session.sh created"
-```
-
-**IMPORTANT**: The hook calls a **shell script** (`bash docs/00-meta/resume-session.sh`), NOT the slash command `/agileflow:session:resume`. This is because:
-- Hooks execute shell commands, not Claude Code slash commands
-- The shell script replicates `/agileflow:session:resume` functionality
-- This enables true automatic session resumption
-
-### 10. Final Summary
-
-Display setup completion summary:
-
-```
-✅ Session Harness Initialized
-
-Files Created:
-  ✅ docs/00-meta/environment.json
-  ✅ docs/00-meta/init.sh
-  ✅ docs/00-meta/resume-session.sh (auto-resume script)
-  ✅ docs/09-agents/session-state.json
-  ✅ .claude/settings.json (hook configured)
-
-Baseline Status:
-  ✅ Tests: 42/42 passing
-  ✅ Git tag: agileflow-baseline-20251206-103000
-  ✅ Commit: abc123def456
-
-Configuration:
-  Project Type: nodejs
-  Test Command: npm test
-  Verification Policy: warn
-  Auto-Resume: enabled (via shell script hook)
-
-Next Steps:
-  1. Restart Claude Code to activate SessionStart hook
-  2. Run /agileflow:verify to check tests anytime
-  3. Run /agileflow:baseline to mark new baselines
-  4. Run /agileflow:session:resume manually or let the hook run it
-
-On Next Session:
-  - Hook will automatically run: bash docs/00-meta/resume-session.sh
-  - Init script executes, tests verify, context loads
-  - You'll see session summary and be ready to code!
-
-Session harness is ready! 🚀
+  Session ID: 1
+  Path: /home/user/project
+  Branch: main
 ```
 
 ## Related Commands
 
-| Command | Purpose |
-|---------|---------|
-| `/agileflow:session:resume` | Start session with verification and context loading |
-| `/agileflow:session:status` | View current session state and activity |
-| `/agileflow:session:end` | Cleanly end session and record summary |
-| `/agileflow:session:history` | View past session history and metrics |
-
-## Error Handling
-
-### No Test Command Found
-```
-⚠️  Could not detect test command
-
-Please specify test command manually:
-  Test command: _
-
-Or skip test verification:
-  Skip tests? [y/N]: _
-```
-
-### Test Command Fails
-```
-❌ Test command failed: npm test
-Error: npm: command not found
-
-Possible causes:
-  1. Dependencies not installed
-  2. Test command incorrect
-  3. Node.js not in PATH
-
-Would you like to:
-  1. Run init script (install dependencies)
-  2. Specify different test command
-  3. Skip test verification
-
-Choice [1/2/3]: _
-```
-
-### Init Script Execution Fails
-```
-❌ Init script failed
-Error: ...
-
-The init script at docs/00-meta/init.sh encountered an error.
-
-Review the script and try again, or continue without running init.
-
-Continue without init? [y/N]: _
-```
-
-### Git Not Available
-```
-⚠️  Git not found - baseline tagging unavailable
-
-Session harness will be created without git baseline tracking.
-
-This is optional - you can add baseline tags manually later using:
-  git tag -a agileflow-baseline-YYYYMMDD -m "Baseline"
-```
-
-## Integration Points
-
-### Called By
-- `/agileflow:setup` - Optionally runs session:init during initial setup
-
-### Calls
-- `/agileflow:verify` - For initial test verification
-- Template system - Uses templates/environment.json, templates/init.sh
-
-### Creates
-- `docs/00-meta/environment.json` - Session harness config
-- `docs/00-meta/init.sh` - Environment initialization script
-- `docs/09-agents/session-state.json` - Session state tracking
-- `.claude/settings.json` - SessionStart hook (if enabled)
-- Git tag (optional) - Baseline marker
-
-## Implementation Notes
-
-1. **Idempotent**: Safe to run multiple times (asks before overwriting)
-2. **Interactive**: Confirms all detected settings before creating files
-3. **Graceful Degradation**: Works even if tests fail or git unavailable
-4. **User Control**: Every optional feature requires explicit consent
-5. **Clear Output**: Step-by-step progress with clear status indicators
-6. **Error Recovery**: Provides options to retry, skip, or fix issues
+- `/agileflow:session:status` - View all sessions
+- `/agileflow:session:new` - Create parallel session

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

@@ -0,0 +1,152 @@
+---
+description: Create a new parallel session with git worktree
+argument-hint: (no arguments)
+---
+
+# /agileflow:session:new
+
+Create a new isolated session for parallel Claude Code work.
+
+---
+
+## Purpose
+
+When you need to work on multiple things simultaneously in the same repo, this command creates a new session with:
+- A separate git worktree (isolated directory)
+- Its own branch
+- Independent session tracking
+
+## IMMEDIATE ACTIONS
+
+Upon invocation, execute these steps:
+
+### Step 1: Check Prerequisites
+
+```bash
+# Verify git is available and we're in a git repo
+git rev-parse --is-inside-work-tree
+```
+
+If not in a git repo, display error and exit.
+
+### Step 2: Run Session Manager to Get Current State
+
+```bash
+node .agileflow/scripts/session-manager.js status
+```
+
+Parse the JSON output to understand current sessions.
+
+### Step 3: Present Options with AskUserQuestion
+
+Use AskUserQuestion to let user choose how to create the session:
+
+```
+AskUserQuestion:
+  question: "How would you like to create your new session?"
+  header: "New session"
+  multiSelect: false
+  options:
+    - label: "Auto-create Session {next_id} (Recommended)"
+      description: "Creates ../project-{next_id} with new branch session-{next_id}"
+    - label: "Name this session"
+      description: "Give it a memorable name like 'auth' or 'bugfix'"
+    - label: "Use existing branch"
+      description: "Create session from one of your existing branches"
+```
+
+### Step 4a: If "Auto-create" Selected
+
+```bash
+node .agileflow/scripts/session-manager.js create
+```
+
+Parse the JSON result. Display:
+
+```
+✓ Created Session {id}
+
+  Workspace: {path}
+  Branch:    {branch}
+
+┌─────────────────────────────────────────────────────────┐
+│ To start working in this session, run:                  │
+│                                                         │
+│   {command}                                             │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Step 4b: If "Name this session" Selected
+
+Use AskUserQuestion to get the name:
+
+```
+AskUserQuestion:
+  question: "What should this session be called?"
+  header: "Session name"
+  multiSelect: false
+  options:
+    - label: "auth"
+      description: "Working on authentication"
+    - label: "bugfix"
+      description: "Fixing bugs"
+    - label: "feature"
+      description: "New feature work"
+    - label: "experiment"
+      description: "Trying something out"
+```
+
+Then create with nickname:
+
+```bash
+node .agileflow/scripts/session-manager.js create --nickname {name}
+```
+
+### Step 4c: If "Use existing branch" Selected
+
+List branches:
+
+```bash
+git branch --format='%(refname:short)'
+```
+
+Use AskUserQuestion to present branch options (limit to 4-5 most recent).
+
+Then create with specified branch:
+
+```bash
+node .agileflow/scripts/session-manager.js create --branch {branch_name}
+```
+
+### Step 5: Display Success Message
+
+Show the created session details and the command to start working:
+
+```
+✓ Created Session {id} "{nickname}"
+
+  Workspace: ../project-{name}
+  Branch:    session-{id}-{name}
+
+┌─────────────────────────────────────────────────────────┐
+│ To start working in this session, run:                  │
+│                                                         │
+│   cd ../project-{name} && claude                        │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+💡 Tip: Use /agileflow:session:resume to see all sessions
+```
+
+## Error Handling
+
+- **Directory exists**: Suggest different name or manual cleanup
+- **Branch conflict**: Offer to use existing branch or create new one
+- **Git errors**: Display error message and suggest manual resolution
+
+## Related Commands
+
+- `/agileflow:session:resume` - Switch between sessions
+- `/agileflow:session:status` - View all sessions
+- `/agileflow:session:end` - End current session