agileflow 2.84.2 → 2.86.0

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

@@ -80,8 +80,9 @@ Parse the JSON result. Display:
 ```
 ✓ Created Session {id}
 
-  Workspace: {path}
-  Branch:    {branch}
+  Workspace:   {path}
+  Branch:      {branch}
+  Thread Type: parallel
 
 ┌─────────────────────────────────────────────────────────┐
 │ To start working in this session, run:                  │
@@ -91,6 +92,8 @@ Parse the JSON result. Display:
 └─────────────────────────────────────────────────────────┘
 ```
 
+Note: Worktree sessions default to "parallel" thread type. See docs/02-practices/thread-based-engineering.md for thread type definitions.
+
 ### Step 4b: If "Name this session" Selected
 
 Use AskUserQuestion to get the name:
@@ -133,26 +136,39 @@ Then create with specified branch:
 node .agileflow/scripts/session-manager.js create --branch {branch_name}
 ```
 
-### Step 5: Display Success Message
+### Step 5: Display Success with Switch Command
 
-Show the created session details and the command to start working:
+After session creation succeeds:
 
+1. First, activate boundary protection for the new session:
+```bash
+node .agileflow/scripts/session-manager.js switch {new_session_id}
 ```
-✓ Created Session {id} "{nickname}"
 
-  Workspace: ../project-{name}
-  Branch:    session-{id}-{name}
+2. Then show the `/add-dir` command for the user to switch:
 
-┌─────────────────────────────────────────────────────────┐
-│ To start working in this session, run:                  │
-│                                                         │
-│   cd ../project-{name} && claude                        │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+```
+✅ Created Session {id} "{nickname}"
+
+┌────────────┬────────────────────────────────────────────┐
+│ Session    │ {id} "{nickname}"                          │
+│ Workspace  │ {path}                                     │
+│ Branch     │ {branch}                                   │
+│ Thread     │ parallel                                   │
+└────────────┴────────────────────────────────────────────┘
+
+To switch to this session, run:
+
+  /add-dir {path}
 
-💡 Tip: Use /agileflow:session:resume to see all sessions
+💡 Use /agileflow:session:resume to list all sessions
 ```
 
+**WHY /add-dir instead of cd && claude:**
+- Stays in the same terminal and conversation
+- One short command to type
+- Immediately enables file access to the new session directory
+
 ## Error Handling
 
 - **Directory exists**: Suggest different name or manual cleanup
@@ -228,21 +244,27 @@ If user selects "Auto-create":
 node .agileflow/scripts/session-manager.js create
 ```
 
-Display:
+Parse JSON result, then activate boundary protection:
+```bash
+node .agileflow/scripts/session-manager.js switch {new_id}
 ```
-✓ Created Session {id}
 
-  Workspace: ../project-{id}
-  Branch:    session-{id}
+Then display:
+```
+✅ Created Session {id}
 
-┌─────────────────────────────────────────────────────────┐
-│ To start working in this session, run:                  │
-│                                                         │
-│   cd ../project-{id} && claude                          │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+┌────────────┬────────────────────────────────────────────┐
+│ Session    │ {id}                                       │
+│ Workspace  │ {path}                                     │
+│ Branch     │ {branch}                                   │
+│ Thread     │ parallel                                   │
+└────────────┴────────────────────────────────────────────┘
+
+To switch to this session, run:
 
-💡 Tip: Use /agileflow:session:resume to see all sessions
+  /add-dir {path}
+
+💡 Use /agileflow:session:resume to list all sessions
 ```
 
 ---
@@ -274,21 +296,27 @@ Then create:
 node .agileflow/scripts/session-manager.js create --nickname {name}
 ```
 
-Display:
+Parse JSON result, then activate boundary protection:
+```bash
+node .agileflow/scripts/session-manager.js switch {new_id}
 ```
-✓ Created Session {id} "{name}"
 
-  Workspace: ../project-{name}
-  Branch:    session-{id}-{name}
+Then display:
+```
+✅ Created Session {id} "{name}"
 
-┌─────────────────────────────────────────────────────────┐
-│ To start working in this session, run:                  │
-│                                                         │
-│   cd ../project-{name} && claude                        │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+┌────────────┬────────────────────────────────────────────┐
+│ Session    │ {id} "{name}"                              │
+│ Workspace  │ {path}                                     │
+│ Branch     │ {branch}                                   │
+│ Thread     │ parallel                                   │
+└────────────┴────────────────────────────────────────────┘
+
+To switch to this session, run:
+
+  /add-dir {path}
 
-💡 Tip: Use /agileflow:session:resume to see all sessions
+💡 Use /agileflow:session:resume to list all sessions
 ```
 
 ---
@@ -327,7 +355,12 @@ git branch --format='%(refname:short)'
 node .agileflow/scripts/session-manager.js create --branch {branch_name}
 ```
 
-Display success as above.
+5. Parse JSON result, then activate boundary protection:
+```bash
+node .agileflow/scripts/session-manager.js switch {new_id}
+```
+
+6. Display success as above with `/add-dir` command.
 
 ---
 
@@ -365,21 +398,25 @@ Try running: git status
 
 All three options show same format:
 ```
-✓ Created Session {id} ["{nickname}" OR empty]
+✅ Created Session {id} ["{nickname}" OR empty]
 
-  Workspace: ../project-{path}
-  Branch:    {branch_name}
+┌────────────┬────────────────────────────────────────────┐
+│ Session    │ {id} ["{nickname}" or empty]               │
+│ Workspace  │ {path}                                     │
+│ Branch     │ {branch}                                   │
+│ Thread     │ parallel                                   │
+└────────────┴────────────────────────────────────────────┘
 
-┌─────────────────────────────────────────────────────────┐
-│ To start working in this session, run:                  │
-│                                                         │
-│   {cd_command}                                          │
-│                                                         │
-└─────────────────────────────────────────────────────────┘
+To switch to this session, run:
 
-💡 Tip: Use /agileflow:session:resume to see all sessions
+  /add-dir {path}
+
+💡 Use /agileflow:session:resume to list all sessions
 ```
 
+**Use /add-dir instead of cd && claude** - stays in same terminal/conversation.
+**Thread type**: Worktree sessions default to "parallel". See [Thread-Based Engineering](../../02-practices/thread-based-engineering.md).
+
 ---
 
 ### KEY FILES TO REMEMBER
@@ -400,7 +437,8 @@ All three options show same format:
 4. **User selects** → Option 1, 2, or 3
 5. **Handle selection** → Different flow for each
 6. **Create session** → Call manager script
-7. **Show success** → Display cd command
+7. **Activate boundary** → `session-manager.js switch {new_id}`
+8. **Show success** → Display `/add-dir {path}` command for user to run
 
 ---
 
@@ -420,7 +458,7 @@ All three options show same format:
 ❌ Don't show more/fewer than 3 initial options
 ❌ Don't create session without explicit user choice
 ❌ Don't skip error handling (directory exists, branch conflict)
-❌ Don't forget cd command in success message
+❌ Don't show old "cd && claude" command - use /add-dir instead
 ❌ Show different success formats for different methods
 
 ### DO THESE INSTEAD
@@ -429,7 +467,7 @@ All three options show same format:
 ✅ Always show exactly 3 options
 ✅ Wait for user to select before creating
 ✅ Handle all error cases gracefully
-✅ Always show cd command in success
+✅ Show `/add-dir {path}` command for user to switch
 ✅ Use consistent success format
 
 ---
@@ -442,7 +480,8 @@ All three options show same format:
 - Each option leads to different flow
 - Use AskUserQuestion for user selections
 - Handle all error cases (directory, branch, git)
-- Return success with cd command
+- **Run `session-manager.js switch {new_id}` AFTER creating session** (enables boundary protection)
+- Show `/add-dir {path}` command for user to switch (NOT cd && claude)
 - Show tip to use /agileflow:session:resume
 
 <!-- COMPACT_SUMMARY_END -->

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

@@ -71,18 +71,25 @@ AskUserQuestion:
 
 **If user selects a different session:**
 
-Display the command to switch:
+First, update the active session context for boundary protection:
 
+```bash
+node .agileflow/scripts/session-manager.js switch {session_id}
 ```
-To resume Session 2 "auth":
 
-┌─────────────────────────────────────────────────────────┐
-│   cd ../project-auth && claude --resume                 │
-└─────────────────────────────────────────────────────────┘
+Then display the `/add-dir` command to switch:
+
+```
+To switch to Session 2 "auth":
+
+  /add-dir ../project-auth
 
 Session info:
-  Branch: session-2
-  Story:  US-0038 (in-progress)
+┌──────────┬──────────────────────────┐
+│ Branch   │ session-2                │
+│ Story    │ US-0038 (in-progress)    │
+│ Path     │ ../project-auth          │
+└──────────┴──────────────────────────┘
 ```
 
 **If user selects current session:**
@@ -97,6 +104,11 @@ You're already in Session 1!
 Run /agileflow:session:new to create a new parallel workspace.
 ```
 
+**WHY /add-dir instead of cd && claude:**
+- Stays in the same terminal and conversation
+- One short command to type
+- Immediately enables file access to the session directory
+
 ## Related Commands
 
 - `/agileflow:session:new` - Create new session
@@ -109,7 +121,7 @@ Run /agileflow:session:new to create a new parallel workspace.
 
 ## ⚠️ COMPACT SUMMARY - /agileflow:session:resume IS ACTIVE
 
-**CRITICAL**: This command is the primary way to **switch between parallel sessions**. User selects, you display the cd command.
+**CRITICAL**: This command is the primary way to **switch between parallel sessions**. User selects, you display the `/add-dir` command.
 
 ---
 
@@ -152,16 +164,24 @@ You're already in Session 1!
 ```
 
 **If user selects different session:**
+
+1. First, run switch command (enables boundary protection):
+```bash
+node .agileflow/scripts/session-manager.js switch {session_id}
 ```
-To resume Session 2 "auth":
 
-┌─────────────────────────────────────────────────────────┐
-│   cd ../project-auth && claude --resume                 │
-└─────────────────────────────────────────────────────────┘
+2. Then show the /add-dir command:
+```
+To switch to Session 2 "auth":
+
+  /add-dir ../project-auth
 
 Session info:
-  Branch: session-2
-  Story:  US-0038 (in-progress)
+┌──────────┬──────────────────────────┐
+│ Branch   │ session-2                │
+│ Story    │ US-0038 (in-progress)    │
+│ Path     │ ../project-auth          │
+└──────────┴──────────────────────────┘
 ```
 
 **If user selects "Create new session":**
@@ -169,6 +189,8 @@ Session info:
 Run /agileflow:session:new to create a new parallel workspace.
 ```
 
+**Use /add-dir instead of cd && claude** - stays in same terminal/conversation.
+
 ---
 
 ### 🚨 RULE #3: FORMATTING LABELS & DESCRIPTIONS
@@ -223,7 +245,8 @@ Use these fields to build readable labels.
 2. **Parse JSON** → Extract id, branch, nickname, status, path
 3. **Build options** → Create readable labels with status
 4. **Show AskUserQuestion** → Let user select
-5. **Handle selection** → Show cd command or appropriate response
+5. **Activate boundary** → `session-manager.js switch {selected_id}` (if different session)
+6. **Handle selection** → Show `/add-dir` command or appropriate response
 
 ---
 
@@ -252,6 +275,7 @@ Use these fields to build readable labels.
 - Format labels clearly: `Session {id}: {nickname/branch} {(current)}`
 - Show status in description: `Active now` OR `Inactive (N days ago)`
 - Handle each case: current / different / create new
-- Return cd command when user selects different session
+- **Run `session-manager.js switch {id}` BEFORE showing /add-dir** (enables boundary protection)
+- Show `/add-dir {path}` command when user selects different session (NOT cd && claude)
 
 <!-- COMPACT_SUMMARY_END -->

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

@@ -1,6 +1,6 @@
 ---
 description: View current session state and activity
-argument-hint: (no arguments)
+argument-hint: [--kanban]
 compact_context:
   priority: medium
   preserve_rules:
@@ -9,6 +9,7 @@ compact_context:
     - "Shows current session, then table of other sessions"
     - "Marks active sessions with ● bullet, inactive with ○"
     - "Returns session count and active count"
+    - "--kanban flag shows Kanban-style board with phases (TO DO, CODING, REVIEW, MERGED)"
   state_fields:
     - current_session
     - all_sessions
@@ -26,16 +27,29 @@ Quick view of all sessions and their status.
 
 Display a compact overview of all registered sessions without prompting for action.
 
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `--kanban` | No | Show Kanban-style board with phases instead of table |
+
 ## IMMEDIATE ACTIONS
 
 ### Step 1: Get Session Data
 
+**Standard view:**
 ```bash
 node .agileflow/scripts/session-manager.js list --json
 ```
 
-### Step 2: Display Formatted Table
+**Kanban view (if --kanban flag):**
+```bash
+node .agileflow/scripts/session-manager.js list --kanban
+```
+
+### Step 2: Display Formatted Output
 
+**Standard Table View:**
 ```
 📊 Session Status
 
@@ -53,6 +67,25 @@ Other Sessions:
 Total: 3 sessions │ 2 active
 ```
 
+**Kanban Board View (--kanban):**
+```
+Sessions (Kanban View):
+
+TO DO           CODING          REVIEW          MERGED
+┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+│              │  │[2] auth      │  │[3] payments  │  │[1] main      │
+│              │  │US-0038       │  │US-0042       │  │-             │
+└──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
+
+To Do: 0 │ Coding: 1 │ Review: 1 │ Merged: 1
+```
+
+**Phase Detection Logic:**
+- **TO DO**: No commits since branch creation
+- **CODING**: Has commits, still has uncommitted changes
+- **REVIEW**: Has commits, no uncommitted changes (ready to merge)
+- **MERGED**: Main branch or merged sessions
+
 ### Step 3: Show Quick Actions
 
 ```

package/src/core/templates/session-state.json

@@ -1,15 +1,20 @@
 {
   "$schema": "https://json-schema.org/draft-07/schema#",
   "description": "AgileFlow session state tracking",
-  "schema_version": 2,
+  "schema_version": 3,
   "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
+    "active_agent": null,
+    "thread_type": "base",
+    "thread_complexity": "routine",
+    "expected_duration_minutes": null
   },
+  "_thread_type_enum": ["base", "parallel", "chained", "fusion", "big", "long"],
+  "_thread_complexity_enum": ["trivial", "routine", "complex", "exploratory"],
   "active_command": {
     "_comment": "Tracks which command (babysit, etc.) is currently active for context preservation across compacts",
     "name": null,
@@ -23,5 +28,29 @@
     "final_test_status": "not_run",
     "commits": []
   },
-  "session_history": []
+  "session_history": [],
+  "batch_loop": {
+    "_comment": "State for batch pmap loop mode - iterative processing with quality gates",
+    "enabled": false,
+    "batch_id": null,
+    "pattern": null,
+    "action": null,
+    "quality_gate": "tests",
+    "current_item": null,
+    "items": {},
+    "summary": {
+      "total": 0,
+      "completed": 0,
+      "in_progress": 0,
+      "pending": 0,
+      "failed": 0
+    },
+    "iteration": 0,
+    "max_iterations": 50,
+    "started_at": null,
+    "completed_at": null,
+    "stopped_reason": null,
+    "last_failure": null
+  },
+  "_batch_item_status_enum": ["pending", "in_progress", "completed", "failed", "skipped"]
 }

package/tools/cli/commands/config.js

@@ -11,6 +11,7 @@ const yaml = require('js-yaml');
 const { Installer } = require('../installers/core/installer');
 const { IdeManager } = require('../installers/ide/manager');
 const { displayLogo, displaySection, success, warning, error, info } = require('../lib/ui');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -33,9 +34,12 @@ module.exports = {
 
       if (!status.installed) {
         displayLogo();
-        warning('No AgileFlow installation found');
-        console.log(chalk.dim(`\nRun 'npx agileflow setup' to set up AgileFlow\n`));
-        process.exit(1);
+        const handler = new ErrorHandler('config');
+        handler.warning(
+          'No AgileFlow installation found',
+          'Initialize AgileFlow first',
+          'npx agileflow setup'
+        );
       }
 
       const manifestPath = path.join(status.path, '_cfg', 'manifest.yaml');
@@ -76,11 +80,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('Error:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('config');
+      handler.critical(
+        'Configuration operation failed',
+        'Check manifest file integrity',
+        'npx agileflow doctor --fix',
+        err
+      );
     }
   },
 };
@@ -121,17 +127,24 @@ async function handleList(status) {
  * Handle get subcommand
  */
 async function handleGet(status, key) {
+  const handler = new ErrorHandler('config');
+
   if (!key) {
-    error('Missing key. Usage: npx agileflow config get <key>');
-    process.exit(1);
+    handler.warning(
+      'Missing key',
+      'Provide a config key to get',
+      'npx agileflow config get <key>'
+    );
   }
 
   const validKeys = ['userName', 'ides', 'agileflowFolder', 'docsFolder', 'version'];
 
   if (!validKeys.includes(key)) {
-    error(`Invalid key: ${key}`);
-    console.log(chalk.dim(`Valid keys: ${validKeys.join(', ')}\n`));
-    process.exit(1);
+    handler.warning(
+      `Invalid key: ${key}`,
+      `Valid keys: ${validKeys.join(', ')}`,
+      'npx agileflow config list'
+    );
   }
 
   let value;
@@ -160,17 +173,24 @@ async function handleGet(status, key) {
  * Handle set subcommand
  */
 async function handleSet(directory, status, manifestPath, key, value) {
+  const handler = new ErrorHandler('config');
+
   if (!key || value === undefined) {
-    error('Missing arguments. Usage: npx agileflow config set <key> <value>');
-    process.exit(1);
+    handler.warning(
+      'Missing arguments',
+      'Provide both key and value',
+      'npx agileflow config set <key> <value>'
+    );
   }
 
   const validKeys = ['userName', 'ides', 'agileflowFolder', 'docsFolder'];
 
   if (!validKeys.includes(key)) {
-    error(`Invalid key: ${key}`);
-    console.log(chalk.dim(`Valid keys: ${validKeys.join(', ')}\n`));
-    process.exit(1);
+    handler.warning(
+      `Invalid key: ${key}`,
+      `Valid keys: ${validKeys.join(', ')}`,
+      'npx agileflow config list'
+    );
   }
 
   displayLogo();
@@ -198,9 +218,11 @@ async function handleSet(directory, status, manifestPath, key, value) {
       // Validate IDEs
       for (const ide of newIdes) {
         if (!validIdes.includes(ide)) {
-          error(`Invalid IDE: ${ide}`);
-          console.log(chalk.dim(`Valid IDEs: ${validIdes.join(', ')}\n`));
-          process.exit(1);
+          handler.warning(
+            `Invalid IDE: ${ide}`,
+            `Valid IDEs: ${validIdes.join(', ')}`,
+            'npx agileflow config set ides "claude-code,cursor"'
+          );
         }
       }
 

package/tools/cli/commands/doctor.js

@@ -20,6 +20,7 @@ const {
 } = require('../lib/ui');
 const { IdeManager } = require('../installers/ide/manager');
 const { getCurrentVersion } = require('../lib/version-checker');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 
@@ -306,11 +307,13 @@ module.exports = {
 
       process.exit(issues > 0 ? 1 : 0);
     } catch (err) {
-      console.error(chalk.red('Error:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('doctor');
+      handler.critical(
+        'Diagnostics failed',
+        'Check permissions and installation',
+        'npx agileflow setup',
+        err
+      );
     }
   },
 };

package/tools/cli/commands/setup.js

@@ -22,6 +22,7 @@ const {
 } = require('../lib/ui');
 const { createDocsStructure } = require('../lib/docs-setup');
 const { getLatestVersion } = require('../lib/npm-utils');
+const { ErrorHandler } = require('../lib/error-handler');
 
 const installer = new Installer();
 const ideManager = new IdeManager();
@@ -101,8 +102,12 @@ module.exports = {
       const coreResult = await installer.install(config);
 
       if (!coreResult.success) {
-        error('Core setup failed');
-        process.exit(1);
+        const handler = new ErrorHandler('setup');
+        handler.warning(
+          'Core setup failed',
+          'Check directory permissions',
+          'npx agileflow doctor'
+        );
       }
 
       success(`Installed ${coreResult.counts.agents} agents`);
@@ -144,11 +149,13 @@ module.exports = {
 
       process.exit(0);
     } catch (err) {
-      console.error(chalk.red('\nSetup failed:'), err.message);
-      if (process.env.DEBUG) {
-        console.error(err.stack);
-      }
-      process.exit(1);
+      const handler = new ErrorHandler('setup');
+      handler.critical(
+        'Setup failed',
+        'Check directory exists and has write permissions',
+        'npx agileflow doctor',
+        err
+      );
     }
   },
 };