agileflow 2.92.1 → 2.93.0

package/scripts/session-manager.js

@@ -231,6 +231,161 @@ async function cleanupStaleLocksAsync(registry, options = {}) {
   return { count: cleanedSessions.length, sessions: cleanedSessions };
 }
 
+/**
+ * Get detailed file information for a session's changes
+ * @param {string} sessionPath - Path to session worktree
+ * @param {string[]} changes - Array of git status lines
+ * @returns {Object[]} Array of file details with analysis
+ */
+function getFileDetails(sessionPath, changes) {
+  return changes.map((change) => {
+    const status = change.substring(0, 2).trim();
+    const file = change.substring(3);
+
+    const detail = { status, file, trivial: false, existsInMain: false, diffLines: 0 };
+
+    // For modified files, get diff stats
+    if (status === 'M') {
+      try {
+        const diffStat = spawnSync('git', ['diff', '--numstat', file], {
+          cwd: sessionPath,
+          encoding: 'utf8',
+          timeout: 3000,
+        });
+        if (diffStat.stdout) {
+          const parts = diffStat.stdout.trim().split('\t');
+          const added = parseInt(parts[0], 10) || 0;
+          const removed = parseInt(parts[1], 10) || 0;
+          detail.diffLines = added + removed;
+          // Trivial if only 1-2 lines changed (likely whitespace)
+          detail.trivial = detail.diffLines <= 2;
+        }
+      } catch (e) {
+        // Can't get diff, assume not trivial
+      }
+    }
+
+    // For untracked files, check if exists in main
+    if (status === '??') {
+      detail.existsInMain = fs.existsSync(path.join(ROOT, file));
+      // Trivial if it's a duplicate
+      detail.trivial = detail.existsInMain;
+    }
+
+    // Config/cache files are trivial
+    if (file.includes('.claude/') || file.includes('.agileflow/cache')) {
+      detail.trivial = true;
+    }
+
+    return detail;
+  });
+}
+
+/**
+ * Get health status for all sessions
+ * Detects: stale sessions, uncommitted changes, orphaned entries
+ * @param {Object} options - { staleDays: 7, detailed: false }
+ * @returns {Object} Health report
+ */
+function getSessionsHealth(options = {}) {
+  const { staleDays = 7, detailed = false } = options;
+  const registry = loadRegistry();
+  const now = Date.now();
+  const staleThreshold = staleDays * 24 * 60 * 60 * 1000;
+
+  const health = {
+    stale: [],           // Sessions with no activity > staleDays
+    uncommitted: [],     // Sessions with uncommitted git changes
+    orphanedRegistry: [], // Registry entries where path doesn't exist
+    orphanedWorktrees: [], // Worktrees not in registry
+    healthy: 0,
+  };
+
+  // Check each registered session
+  for (const [id, session] of Object.entries(registry.sessions)) {
+    if (session.is_main) continue; // Skip main session
+
+    const age = now - new Date(session.last_active).getTime();
+    const pathExists = fs.existsSync(session.path);
+
+    // Check for orphaned registry entry (path missing)
+    if (!pathExists) {
+      health.orphanedRegistry.push({ id, ...session, reason: 'path_missing' });
+      continue;
+    }
+
+    // Check for stale session
+    if (age > staleThreshold) {
+      health.stale.push({
+        id,
+        ...session,
+        ageDays: Math.floor(age / (24 * 60 * 60 * 1000)),
+      });
+    }
+
+    // Check for uncommitted changes
+    try {
+      const result = spawnSync('git', ['status', '--porcelain'], {
+        cwd: session.path,
+        encoding: 'utf8',
+        timeout: 5000,
+      });
+      if (result.stdout && result.stdout.trim()) {
+        // Don't use trim() on the whole string - it removes leading space from first status
+        // Split by newline and filter empty lines instead
+        const changes = result.stdout.split('\n').filter((line) => line.length > 0);
+        const sessionData = {
+          id,
+          ...session,
+          changeCount: changes.length,
+          changes: detailed ? changes : changes.slice(0, 5), // All or first 5
+        };
+
+        // Add detailed file analysis if requested
+        if (detailed) {
+          sessionData.fileDetails = getFileDetails(session.path, changes);
+          // Calculate if session is safe to delete (all changes trivial)
+          sessionData.allTrivial = sessionData.fileDetails.every((f) => f.trivial);
+        }
+
+        health.uncommitted.push(sessionData);
+      } else {
+        health.healthy++;
+      }
+    } catch (e) {
+      // Can't check, skip
+    }
+  }
+
+  // Check for orphaned worktrees (directories not in registry)
+  try {
+    const worktreeList = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+      encoding: 'utf8',
+    });
+    if (worktreeList.stdout) {
+      const worktrees = worktreeList.stdout
+        .split('\n')
+        .filter((line) => line.startsWith('worktree '))
+        .map((line) => line.replace('worktree ', ''));
+
+      const mainPath = ROOT;
+      for (const wtPath of worktrees) {
+        const inRegistry = Object.values(registry.sessions).some((s) => s.path === wtPath);
+        if (!inRegistry && wtPath !== mainPath) {
+          // Check if it's an AgileFlow worktree (has .agileflow folder)
+          if (fs.existsSync(path.join(wtPath, '.agileflow'))) {
+            health.orphanedWorktrees.push({ path: wtPath });
+          }
+        }
+      }
+    }
+  } catch (e) {
+    // Can't list worktrees, skip
+  }
+
+  return health;
+}
+
 // Git command cache (10 second TTL to avoid stale data)
 const gitCache = {
   data: new Map(),
@@ -432,7 +587,11 @@ function progressIndicator(message) {
  * @param {number} timeoutMs - Timeout in milliseconds
  * @returns {Promise<{stdout: string, stderr: string}>}
  */
-function createWorktreeWithTimeout(worktreePath, branchName, timeoutMs = DEFAULT_WORKTREE_TIMEOUT_MS) {
+function createWorktreeWithTimeout(
+  worktreePath,
+  branchName,
+  timeoutMs = DEFAULT_WORKTREE_TIMEOUT_MS
+) {
   return new Promise((resolve, reject) => {
     let stdout = '';
     let stderr = '';
@@ -455,15 +614,15 @@ function createWorktreeWithTimeout(worktreePath, branchName, timeoutMs = DEFAULT
       }, 1000);
     }, timeoutMs);
 
-    proc.stdout.on('data', (data) => {
+    proc.stdout.on('data', data => {
       stdout += data.toString();
     });
 
-    proc.stderr.on('data', (data) => {
+    proc.stderr.on('data', data => {
       stderr += data.toString();
     });
 
-    proc.on('error', (err) => {
+    proc.on('error', err => {
       clearTimeout(timer);
       reject(new Error(`Failed to spawn git: ${err.message}`));
     });
@@ -472,7 +631,11 @@ function createWorktreeWithTimeout(worktreePath, branchName, timeoutMs = DEFAULT
       clearTimeout(timer);
 
       if (timedOut) {
-        reject(new Error(`Worktree creation timed out after ${timeoutMs / 1000}s. Try increasing timeout or check disk space.`));
+        reject(
+          new Error(
+            `Worktree creation timed out after ${timeoutMs / 1000}s. Try increasing timeout or check disk space.`
+          )
+        );
         return;
       }
 
@@ -601,7 +764,9 @@ async function createSession(options = {}) {
   const timeoutMs = options.timeout || DEFAULT_WORKTREE_TIMEOUT_MS;
 
   // Create worktree with timeout and progress feedback
-  const stopProgress = progressIndicator('Creating worktree (this may take a while for large repos)');
+  const stopProgress = progressIndicator(
+    'Creating worktree (this may take a while for large repos)'
+  );
   try {
     await createWorktreeWithTimeout(worktreePath, branchName, timeoutMs);
     stopProgress();
@@ -1300,16 +1465,23 @@ function main() {
       if (options.timeout) {
         options.timeout = parseInt(options.timeout, 10);
         if (isNaN(options.timeout) || options.timeout < 1000) {
-          console.log(JSON.stringify({ success: false, error: 'Timeout must be a number >= 1000 (milliseconds)' }));
+          console.log(
+            JSON.stringify({
+              success: false,
+              error: 'Timeout must be a number >= 1000 (milliseconds)',
+            })
+          );
           return;
         }
       }
       // Handle async createSession
-      createSession(options).then(result => {
-        console.log(JSON.stringify(result));
-      }).catch(err => {
-        console.log(JSON.stringify({ success: false, error: err.message }));
-      });
+      createSession(options)
+        .then(result => {
+          console.log(JSON.stringify(result));
+        })
+        .catch(err => {
+          console.log(JSON.stringify({ success: false, error: err.message }));
+        });
       break;
     }
 
@@ -1361,6 +1533,17 @@ function main() {
       break;
     }
 
+    case 'health': {
+      // Get health status for all sessions
+      // Usage: health [staleDays] [--detailed]
+      const staleDaysArg = args.find((a) => /^\d+$/.test(a));
+      const staleDays = staleDaysArg ? parseInt(staleDaysArg, 10) : 7;
+      const detailed = args.includes('--detailed');
+      const health = getSessionsHealth({ staleDays, detailed });
+      console.log(JSON.stringify(health));
+      break;
+    }
+
     case 'get': {
       const sessionId = args[1];
       if (!sessionId) {

package/scripts/spawn-parallel.js

@@ -64,16 +64,24 @@ function hasScreen() {
  * Build the Claude command for a session
  */
 function buildClaudeCommand(sessionPath, options = {}) {
-  const { init = false, dangerous = false, prompt = null } = options;
+  const { init = false, dangerous = false, prompt = null, claudeArgs = null, noClaude = false } = options;
   const parts = [`cd "${sessionPath}"`];
 
   if (init) {
     parts.push('claude init --yes 2>/dev/null || true');
   }
 
+  // If noClaude is true, just return cd command (no claude startup)
+  if (noClaude) {
+    return parts.join(' && ');
+  }
+
   let claudeCmd = 'claude';
   if (dangerous) {
-    claudeCmd = 'claude --dangerouslySkipPermissions';
+    claudeCmd = 'claude --dangerously-skip-permissions';
+  } else if (claudeArgs) {
+    // Custom claude arguments (e.g., --permission-mode acceptEdits)
+    claudeCmd = `claude ${claudeArgs}`;
   }
 
   if (prompt) {
@@ -215,7 +223,7 @@ function getReadyStoriesFromEpic(epicId) {
 /**
  * Main spawn command
  */
-function spawn(args) {
+async function spawn(args) {
   const count = args.count ? parseInt(args.count, 10) : null;
   const branches = args.branches ? args.branches.split(',').map(b => b.trim()) : null;
   const fromEpic = args['from-epic'] || args.fromEpic;
@@ -223,6 +231,8 @@ function spawn(args) {
   const init = args.init || false;
   const dangerous = args.dangerous || false;
   const prompt = args.prompt || null;
+  const claudeArgs = args['claude-args'] || args.claudeArgs || null;
+  const noClaude = args['no-claude'] || args.noClaude || false;
 
   // Determine what to create
   let sessionsToCreate = [];
@@ -276,7 +286,7 @@ function spawn(args) {
 
   const createdSessions = [];
   for (const sessionSpec of sessionsToCreate) {
-    const result = sessionManager.createSession({
+    const result = await sessionManager.createSession({
       nickname: sessionSpec.nickname,
       branch: sessionSpec.branch,
     });
@@ -311,10 +321,10 @@ function spawn(args) {
   // Spawn in tmux or output commands
   if (noTmux) {
     // User explicitly requested manual mode
-    outputCommands(createdSessions, { init, dangerous, prompt });
+    outputCommands(createdSessions, { init, dangerous, prompt, claudeArgs, noClaude });
   } else if (hasTmux()) {
     // Tmux available - use it
-    const tmuxResult = spawnInTmux(createdSessions, { init, dangerous, prompt });
+    const tmuxResult = spawnInTmux(createdSessions, { init, dangerous, prompt, claudeArgs, noClaude });
 
     if (tmuxResult.success) {
       console.log(success(`\n✅ Tmux session created: ${tmuxResult.sessionName}`));
@@ -326,7 +336,7 @@ function spawn(args) {
       console.log('');
     } else {
       console.error(error(`Failed to create tmux session: ${tmuxResult.error}`));
-      outputCommands(createdSessions, { init, dangerous, prompt });
+      outputCommands(createdSessions, { init, dangerous, prompt, claudeArgs, noClaude });
     }
   } else {
     // Tmux NOT available - require it or use --no-tmux
@@ -392,9 +402,12 @@ function list() {
 /**
  * Add a new window to an existing tmux session
  */
-function addWindow(args) {
+async function addWindow(args) {
   const nickname = args.nickname || args.name || null;
   const branch = args.branch || null;
+  const dangerous = args.dangerous || false;
+  const claudeArgs = args['claude-args'] || args.claudeArgs || null;
+  const noClaude = args['no-claude'] || args.noClaude || false;
 
   // Check if we're inside a tmux session
   const tmuxEnv = process.env.TMUX;
@@ -427,7 +440,7 @@ function addWindow(args) {
     branch: branch || `parallel-${Date.now()}`,
   };
 
-  const result = sessionManager.createSession({
+  const result = await sessionManager.createSession({
     nickname: sessionSpec.nickname,
     branch: sessionSpec.branch,
   });
@@ -438,7 +451,7 @@ function addWindow(args) {
   }
 
   const windowName = sessionSpec.nickname;
-  const cmd = buildClaudeCommand(result.path, {});
+  const cmd = buildClaudeCommand(result.path, { dangerous, claudeArgs, noClaude });
 
   // Create new window in current tmux session
   const newWindowResult = spawnSync(
@@ -551,7 +564,9 @@ ${c.cyan}SPAWN OPTIONS:${c.reset}
   --branches "a,b,c"  Create worktrees for specific branch names
   --from-epic EP-XXX  Create worktrees for ready stories in epic
   --init              Run 'claude init' in each worktree
-  --dangerous         Use --dangerouslySkipPermissions
+  --dangerous         Use --dangerously-skip-permissions
+  --claude-args "..." Custom arguments for claude command
+  --no-claude         Create worktree but don't start claude
   --no-tmux           Output commands without spawning in tmux
   --prompt "TEXT"     Initial prompt to send to each Claude instance
 
@@ -575,6 +590,9 @@ ${c.cyan}ADD-WINDOW OPTIONS:${c.reset}
   --name NAME         Name for the new session/window
   --nickname NAME     Alias for --name
   --branch BRANCH     Use specific branch name
+  --dangerous         Use --dangerously-skip-permissions
+  --claude-args "..." Custom arguments for claude command
+  --no-claude         Create worktree but don't start claude
 
 ${c.cyan}ADD-WINDOW EXAMPLES:${c.reset}
   ${dim('# Add window with auto-generated name (when in tmux)')}
@@ -582,6 +600,15 @@ ${c.cyan}ADD-WINDOW EXAMPLES:${c.reset}
 
   ${dim('# Add named window')}
   node scripts/spawn-parallel.js add-window --name auth
+
+  ${dim('# Add window without starting claude')}
+  node scripts/spawn-parallel.js add-window --name research --no-claude
+
+  ${dim('# Add window with skip permissions')}
+  node scripts/spawn-parallel.js add-window --name trusted --dangerous
+
+  ${dim('# Add window with custom claude args')}
+  node scripts/spawn-parallel.js add-window --name safe --claude-args "--permission-mode acceptEdits"
 `);
 }
 
@@ -616,16 +643,16 @@ function parseArgs(argv) {
 /**
  * Main entry point
  */
-function main() {
+async function main() {
   const { command, args } = parseArgs(process.argv.slice(2));
 
   switch (command) {
     case 'spawn':
-      spawn(args);
+      await spawn(args);
       break;
     case 'add-window':
     case 'add':
-      addWindow(args);
+      await addWindow(args);
       break;
     case 'list':
       list();

package/src/core/agents/accessibility.md

@@ -189,131 +189,8 @@ BOUNDARIES
 - Always prioritize real user needs over technical convenience
 
 
-SESSION HARNESS & VERIFICATION PROTOCOL (v2.25.0+)
+<!-- {{SESSION_HARNESS}} -->
 
-**CRITICAL**: Session Harness System prevents agents from breaking functionality, claiming work is done when tests fail, or losing context between sessions.
-
-**PRE-IMPLEMENTATION VERIFICATION**
-
-Before starting work on ANY story:
-
-1. **Check Session Harness**:
-   - Look for `docs/00-meta/environment.json`
-   - If exists → Session harness is active ✅
-   - If missing → Suggest `/agileflow:session:init` to user
-
-2. **Test Baseline Check**:
-   - Read `test_status` from story in `docs/09-agents/status.json`
-   - If `"passing"` → Proceed with implementation ✅
-   - If `"failing"` → STOP. Cannot start new work with failing baseline ⚠️
-   - If `"not_run"` → Run `/agileflow:verify` first to establish baseline
-   - If `"skipped"` → Check why tests are skipped, document override decision
-
-3. **Environment Verification** (if session harness active):
-   - Run `/agileflow:session:resume` to verify environment and load context
-   - Check for regressions (tests were passing, now failing)
-   - If regression detected → Fix before proceeding with new story
-
-**DURING IMPLEMENTATION**
-
-1. **Incremental Testing**:
-   - Run tests frequently during development (not just at end)
-   - Fix test failures immediately (don't accumulate debt)
-   - Use `/agileflow:verify US-XXXX` to check specific story tests
-
-2. **Real-time Status Updates**:
-   - Update `test_status` in status.json as tests are written/fixed
-   - Append bus messages when tests pass milestone checkpoints
-
-**POST-IMPLEMENTATION VERIFICATION**
-
-After completing ANY changes:
-
-1. **Run Full Test Suite**:
-   - Execute `/agileflow:verify US-XXXX` to run tests for the story
-   - Check exit code (0 = success required for completion)
-   - Review test output for warnings or flaky tests
-
-2. **Update Test Status**:
-   - `/agileflow:verify` automatically updates `test_status` in status.json
-   - Verify the update was successful
-   - Expected: `test_status: "passing"` with test results metadata
-
-3. **Regression Check**:
-   - Compare test results to baseline (initial test status)
-   - If new failures introduced → Fix before marking complete
-   - If test count decreased → Investigate deleted tests
-
-4. **Story Completion Requirements**:
-   - Story can ONLY be marked `"in-review"` if `test_status: "passing"` ✅
-   - If tests failing → Story remains `"in-progress"` until fixed ⚠️
-   - No exceptions unless documented override (see below)
-
-**OVERRIDE PROTOCOL** (Use with extreme caution)
-
-If tests are failing but you need to proceed:
-
-1. **Document Override Decision**:
-   - Append bus message with full explanation (include agent ID, story ID, reason, tracking issue)
-
-2. **Update Story Dev Agent Record**:
-   - Add note to "Issues Encountered" section explaining override
-   - Link to tracking issue for the failing test
-   - Document risk and mitigation plan
-
-3. **Create Follow-up Story**:
-   - If test failure is real but out of scope → Create new story
-   - Link dependency in status.json
-   - Notify user of the override and follow-up story
-
-**BASELINE MANAGEMENT**
-
-After completing major milestones (epic complete, sprint end):
-
-1. **Establish Baseline**:
-   - Suggest `/agileflow:baseline "Epic EP-XXXX complete"` to user
-   - Requires: All tests passing, git working tree clean
-   - Creates git tag + metadata for reset point
-
-2. **Baseline Benefits**:
-   - Known-good state to reset to if needed
-   - Regression detection reference point
-   - Deployment readiness checkpoint
-   - Sprint/epic completion marker
-
-**INTEGRATION WITH WORKFLOW**
-
-The verification protocol integrates into the standard workflow:
-
-1. **Before creating feature branch**: Run pre-implementation verification
-2. **Before marking in-review**: Run post-implementation verification
-3. **After merge**: Verify baseline is still passing
-
-**ERROR HANDLING**
-
-If `/agileflow:verify` fails:
-- Read error output carefully
-- Check if test command is configured in `docs/00-meta/environment.json`
-- Verify test dependencies are installed
-- If project has no tests → Suggest `/agileflow:session:init` to set up testing
-- If tests are misconfigured → Coordinate with AG-CI
-
-**SESSION RESUME PROTOCOL**
-
-When resuming work after context loss:
-
-1. **Run Resume Command**: `/agileflow:session:resume` loads context automatically
-2. **Check Session State**: Review `docs/09-agents/session-state.json`
-3. **Verify Test Status**: Ensure no regressions occurred
-4. **Load Previous Insights**: Check Dev Agent Record from previous stories
-
-**KEY PRINCIPLES**
-
-- **Tests are the contract**: Passing tests = feature works as specified
-- **Fail fast**: Catch regressions immediately, not at PR review
-- **Context preservation**: Session harness maintains progress across context windows
-- **Transparency**: Document all override decisions fully
-- **Accountability**: test_status field creates audit trail
 
 WCAG 2.1 STANDARDS
 
@@ -554,7 +431,9 @@ WORKFLOW
 
 10. Sync externally if enabled
 
-QUALITY CHECKLIST
+<!-- {{QUALITY_GATE_PRIORITIES}} -->
+
+QUALITY CHECKLIST (AG-ACCESSIBILITY Specific)
 
 Before approval:
 - [ ] WCAG 2.1 Level AA compliance verified
@@ -568,6 +447,21 @@ Before approval:
 - [ ] Motion respects prefers-reduced-motion
 - [ ] Accessibility documentation complete
 
+AGENT COORDINATION
+
+**Coordinates with**:
+- **AG-UI**: Accessibility in UI components (send a11y findings, receive implementation questions)
+- **AG-DESIGN**: Design system accessibility (send contrast/focus requirements, coordinate on design tokens)
+- **AG-QA**: Accessibility testing (send test criteria, receive test results)
+
+**Bus Messages** (append to `docs/09-agents/bus/log.jsonl`):
+```jsonl
+{"ts":"<ISO>","from":"AG-ACCESSIBILITY","type":"finding","story":"<US-ID>","text":"Finding: Component [X] missing keyboard navigation"}
+{"ts":"<ISO>","from":"AG-ACCESSIBILITY","type":"status","story":"<US-ID>","text":"A11y audit complete: WCAG AA compliance verified"}
+```
+
+**On invocation**: Check bus for AG-UI requests for accessibility review.
+
 FIRST ACTION
 
 **CRITICAL: Load Expertise First (Agent Expert Protocol)**

package/src/core/agents/adr-writer.md

@@ -362,7 +362,9 @@ ADR TEMPLATE STRUCTURE
 - [Title](URL) - Description
 ```
 
-QUALITY CHECKLIST
+<!-- {{QUALITY_GATE_PRIORITIES}} -->
+
+QUALITY CHECKLIST (AG-ADR-WRITER Specific)
 Before creating ADR:
 - [ ] Context explains why decision is needed now
 - [ ] At least 2 alternatives documented
@@ -388,6 +390,21 @@ TONE
 - Avoid advocacy (document, don't persuade)
 - Focus on context and reasoning, not implementation details
 
+AGENT COORDINATION
+
+**Coordinates with**:
+- **AG-RESEARCH**: Technical research (receive research findings, document decisions)
+- **AG-PRODUCT**: Product decisions (receive feature requirements, document trade-offs)
+- **AG-EPIC-PLANNER**: Epic planning (send architectural constraints, receive epic context)
+
+**Bus Messages** (append to `docs/09-agents/bus/log.jsonl`):
+```jsonl
+{"ts":"<ISO>","from":"AG-ADR-WRITER","type":"status","story":"<US-ID>","text":"ADR-XXXX created: [decision title]"}
+{"ts":"<ISO>","from":"AG-ADR-WRITER","type":"finding","story":"<US-ID>","text":"Finding: Existing ADR-YYYY conflicts with proposed approach"}
+```
+
+**On invocation**: Check bus for architectural decisions that need documentation.
+
 FIRST ACTION
 
 **CRITICAL: Load Expertise First (Agent Expert Protocol)**