agileflow 2.82.5 → 2.84.0

package/src/core/commands/babysit.md

@@ -184,6 +184,47 @@ When `VISUAL=true` is specified, the loop adds screenshot verification:
 **Setup requirement:**
 Run `/agileflow:configure` and select "Set up Visual E2E testing" to install Playwright and create e2e tests.
 
+### Visual Mode Auto-Detection (IMPORTANT)
+
+**Check the context output** from `obtain-context.js` for Visual E2E status.
+
+**If "📸 VISUAL E2E TESTING: ENABLED" appears:**
+
+When presenting task options for UI-focused work, **proactively suggest VISUAL mode**:
+
+```
+This epic involves UI work. Visual E2E is configured.
+
+Suggested command:
+/agileflow:babysit EPIC=EP-0042 MODE=loop VISUAL=true
+
+Visual Mode ensures:
+- Screenshots are captured and verified
+- Minimum 2 iterations (prevents premature completion)
+- Both tests AND visual verification must pass
+```
+
+**Detection criteria for suggesting VISUAL=true:**
+| Indicator | Suggest VISUAL? |
+|-----------|-----------------|
+| Epic mentions "UI", "component", "styling" | Yes |
+| Stories have owner: AG-UI | Yes |
+| Files involve src/components/, *.css, *.tsx | Yes |
+| Work is API/backend only | No |
+| Work is CLI/scripts only | No |
+
+**If "VISUAL E2E TESTING: NOT CONFIGURED" appears:**
+
+For UI work, suggest setup:
+```
+This is UI work. Visual E2E not configured.
+
+To enable screenshot verification:
+/agileflow:configure → Visual E2E testing
+
+This helps catch visual issues that tests miss (wrong colors, broken layouts).
+```
+
 ### Loop Control Commands
 
 ```bash
@@ -662,6 +703,7 @@ Based on your project state:
 - Delegate complex work to experts
 - If stuck 2+ times → research prompt
 - Use state narration markers (📍🔀🔄⚠️✅) for visibility
+- **STORY CLAIMING**: Claim stories before working, skip 🔒 claimed stories in suggestions
 
 <!-- COMPACT_SUMMARY_END -->
 
@@ -1096,6 +1138,82 @@ After loading context, analyze and present ranked options:
 
 ---
 
+## STORY CLAIMING (Multi-Session Coordination)
+
+When multiple Claude Code sessions work in the same repo, story claiming prevents conflicts.
+
+### How It Works
+
+1. **Claim on Selection**: When user selects a story to work on, claim it:
+   ```bash
+   node .agileflow/scripts/lib/story-claiming.js claim US-0042
+   ```
+
+2. **Check Before Suggesting**: Filter out claimed stories from suggestions:
+   - Stories with 🔒 badge are claimed by OTHER sessions
+   - Stories with ✓ badge are claimed by THIS session (can continue)
+   - Stories without badge are available
+
+3. **Release on Completion**: When story is marked "done", release claim:
+   ```bash
+   node .agileflow/scripts/lib/story-claiming.js release US-0042
+   ```
+
+### Story Badges in AskUserQuestion
+
+| Badge | Meaning | Action |
+|-------|---------|--------|
+| ⭐ | Ready, available | Can select |
+| 🔒 | Claimed by other session | **DO NOT suggest** (or show as disabled) |
+| ✓ | Claimed by this session | Continue working |
+
+### Claiming Flow
+
+```
+User: "Work on US-0042"
+     ↓
+Check: Is US-0042 claimed?
+     ↓
+┌──────────────┐    ┌──────────────────┐
+│ Not claimed  │    │ Claimed by other │
+└──────────────┘    └──────────────────┘
+     ↓                      ↓
+Claim it, proceed     Show warning:
+                      "US-0042 is being worked on
+                       by Session 2 (../project-auth).
+
+                       Pick a different story to
+                       avoid merge conflicts."
+```
+
+### Commands
+
+```bash
+# Claim a story
+node .agileflow/scripts/lib/story-claiming.js claim US-0042
+
+# Release a story
+node .agileflow/scripts/lib/story-claiming.js release US-0042
+
+# Check if claimed
+node .agileflow/scripts/lib/story-claiming.js check US-0042
+
+# List stories claimed by others
+node .agileflow/scripts/lib/story-claiming.js others
+
+# Clean stale claims (dead PIDs)
+node .agileflow/scripts/lib/story-claiming.js cleanup
+```
+
+### Important Rules
+
+- **Always claim before working**: Prevents conflicts
+- **Stale claims auto-expire**: If session PID dies or 4 hours pass
+- **Force claim available**: `--force` flag overrides (use sparingly)
+- **Release on completion**: Or let auto-expiry handle it
+
+---
+
 ## KNOWLEDGE INDEX
 
 **Context script provides:**

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

@@ -190,7 +190,7 @@ If `hasConflicts: true`:
 ```
 ⚠️ Merge conflicts detected!
 
-This branch has conflicts with {mainBranch} that need to be resolved manually.
+This branch has conflicts with {mainBranch}. Smart merge can attempt automatic resolution.
 ```
 
 Then show conflict options:
@@ -201,6 +201,8 @@ AskUserQuestion:
   header: "Merge conflicts"
   multiSelect: false
   options:
+    - label: "Auto-resolve conflicts (Recommended)"
+      description: "Smart merge will resolve based on file types automatically"
     - label: "Resolve manually"
       description: "Keep session active and resolve conflicts yourself"
     - label: "End session without merging"
@@ -209,6 +211,40 @@ AskUserQuestion:
       description: "Keep session as-is"
 ```
 
+If "Auto-resolve conflicts" selected:
+```bash
+node .agileflow/scripts/session-manager.js smart-merge {session_id} --strategy={squash|merge}
+```
+
+The smart merge will:
+1. Categorize conflicting files by type (docs, tests, schema, config, source)
+2. Apply appropriate resolution strategy per file type
+3. Log all auto-resolutions for audit
+
+Display result:
+```
+✓ Conflicts auto-resolved!
+
+Files resolved:
+  📄 docs/README.md → accept_both (Documentation kept from both)
+  🧪 tests/api.test.ts → accept_both (Tests kept from both)
+  ⚙️ package.json → merge_keys (Config merged)
+  📝 src/api.ts → intelligent_merge (Source merged)
+
+Merge log saved to: .agileflow/sessions/merge-log.json
+```
+
+If auto-resolution fails:
+```
+⚠️ Some conflicts could not be auto-resolved:
+
+  ❌ src/complex.ts → Changes overlap in same code block
+
+Options:
+  • Resolve manually (see instructions below)
+  • End session without merging
+```
+
 If "Resolve manually" selected, show instructions:
 ```
 To resolve conflicts manually:
@@ -409,7 +445,13 @@ node .agileflow/scripts/session-manager.js merge-preview {session_id}
 Display commits and files to be merged.
 
 **Step 3: Check conflicts**
-If `hasConflicts: true` → Show conflict options → EXIT or manual resolution
+If `hasConflicts: true` → Show conflict options (auto-resolve/manual/end/cancel)
+
+**Step 3a: If auto-resolve selected**
+```bash
+node .agileflow/scripts/session-manager.js smart-merge {session_id} --strategy={squash|merge}
+```
+Smart merge auto-resolves by file type: docs→accept_both, tests→accept_both, config→merge_keys, source→theirs
 
 **Step 4: Choose strategy**
 ```xml

package/tools/cli/commands/start.js

@@ -1,178 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * AgileFlow TUI Dashboard
- *
- * BETA - Internal use only, not publicly documented
- *
- * Usage: npx agileflow start
- */
-
-const path = require('path');
-const fs = require('fs');
-const { c: colors } = require('../../../lib/colors');
-
-function showBetaWarning() {
-  console.log('');
-  console.log(
-    `${colors.bgYellow}${colors.bold}  BETA  ${colors.reset} ${colors.yellow}This feature is in beta and not yet stable${colors.reset}`
-  );
-  console.log(`${colors.dim}        Expect bugs and incomplete features${colors.reset}`);
-  console.log('');
-}
-
-function showHeader() {
-  console.log(`${colors.orange}${colors.bold}`);
-  console.log('  ╔═══════════════════════════════════════════╗');
-  console.log('  ║         AgileFlow TUI Dashboard           ║');
-  console.log('  ╚═══════════════════════════════════════════╝');
-  console.log(`${colors.reset}`);
-}
-
-async function loadStatus() {
-  const statusPath = path.join(process.cwd(), 'docs', '09-agents', 'status.json');
-
-  if (!fs.existsSync(statusPath)) {
-    return null;
-  }
-
-  try {
-    const content = fs.readFileSync(statusPath, 'utf8');
-    return JSON.parse(content);
-  } catch (err) {
-    return null;
-  }
-}
-
-function getStatusColor(status) {
-  switch (status) {
-    case 'completed':
-    case 'done':
-      return colors.green;
-    case 'in_progress':
-    case 'in-progress':
-      return colors.yellow;
-    case 'blocked':
-      return colors.red;
-    case 'ready':
-      return colors.cyan;
-    default:
-      return colors.dim;
-  }
-}
-
-function formatStory(story) {
-  const statusColor = getStatusColor(story.status);
-  const id = story.id || story.story_id || 'Unknown';
-  const title = story.title || story.summary || 'Untitled';
-  const status = (story.status || 'unknown').toUpperCase();
-  const owner = story.owner || '-';
-
-  return `  ${colors.bold}${id}${colors.reset} ${title.substring(0, 40)}${title.length > 40 ? '...' : ''}
-           ${statusColor}[${status}]${colors.reset} ${colors.dim}Owner: ${owner}${colors.reset}`;
-}
-
-async function showDashboard() {
-  showBetaWarning();
-  showHeader();
-
-  const status = await loadStatus();
-
-  if (!status) {
-    console.log(
-      `${colors.dim}  No status.json found. Run /agileflow:story to create stories.${colors.reset}`
-    );
-    console.log('');
-    return;
-  }
-
-  // Count stories by status
-  const stories = Object.values(status).filter(
-    s => s && typeof s === 'object' && (s.id || s.story_id)
-  );
-  const counts = {
-    in_progress: stories.filter(s => ['in_progress', 'in-progress'].includes(s.status)).length,
-    blocked: stories.filter(s => s.status === 'blocked').length,
-    ready: stories.filter(s => s.status === 'ready').length,
-    completed: stories.filter(s => ['completed', 'done'].includes(s.status)).length,
-  };
-
-  const total = stories.length;
-  const completionPct = total > 0 ? Math.round((counts.completed / total) * 100) : 0;
-
-  // Summary
-  console.log(`${colors.bold}  Summary${colors.reset}`);
-  console.log(`  ────────────────────────────────────────────`);
-  console.log(
-    `  ${colors.yellow}In Progress:${colors.reset} ${counts.in_progress}   ${colors.red}Blocked:${colors.reset} ${counts.blocked}   ${colors.cyan}Ready:${colors.reset} ${counts.ready}   ${colors.green}Done:${colors.reset} ${counts.completed}`
-  );
-  console.log(`  ${colors.dim}Completion: ${completionPct}%${colors.reset}`);
-  console.log('');
-
-  // In Progress Stories
-  const inProgressStories = stories.filter(s => ['in_progress', 'in-progress'].includes(s.status));
-  if (inProgressStories.length > 0) {
-    console.log(`${colors.bold}  ${colors.yellow}In Progress${colors.reset}`);
-    console.log(`  ────────────────────────────────────────────`);
-    inProgressStories.forEach(story => {
-      console.log(formatStory(story));
-    });
-    console.log('');
-  }
-
-  // Blocked Stories
-  const blockedStories = stories.filter(s => s.status === 'blocked');
-  if (blockedStories.length > 0) {
-    console.log(`${colors.bold}  ${colors.red}Blocked${colors.reset}`);
-    console.log(`  ────────────────────────────────────────────`);
-    blockedStories.forEach(story => {
-      console.log(formatStory(story));
-    });
-    console.log('');
-  }
-
-  // Ready Stories (up to 5)
-  const readyStories = stories.filter(s => s.status === 'ready').slice(0, 5);
-  if (readyStories.length > 0) {
-    console.log(
-      `${colors.bold}  ${colors.cyan}Ready for Work${colors.reset} ${colors.dim}(showing ${readyStories.length} of ${counts.ready})${colors.reset}`
-    );
-    console.log(`  ────────────────────────────────────────────`);
-    readyStories.forEach(story => {
-      console.log(formatStory(story));
-    });
-    console.log('');
-  }
-
-  console.log(`${colors.dim}  Use /agileflow:board for interactive kanban view${colors.reset}`);
-  console.log(`${colors.dim}  Use /agileflow:story:list for full story list${colors.reset}`);
-  console.log('');
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-
-  // Check for help flag
-  if (args.includes('--help') || args.includes('-h')) {
-    showBetaWarning();
-    console.log(`${colors.bold}AgileFlow TUI Dashboard${colors.reset}`);
-    console.log('');
-    console.log(`${colors.bold}Usage:${colors.reset}`);
-    console.log('  npx agileflow start           Show dashboard');
-    console.log('  npx agileflow start --help    Show this help');
-    console.log('');
-    console.log(
-      `${colors.dim}This is a beta feature. For stable commands, use Claude Code slash commands.${colors.reset}`
-    );
-    return;
-  }
-
-  await showDashboard();
-}
-
-main().catch(err => {
-  console.error(`${colors.red}Error:${colors.reset}`, err.message);
-  process.exit(1);
-});
-
-module.exports = { main };

package/tools/cli/tui/Dashboard.js

@@ -1,65 +0,0 @@
-/**
- * Dashboard Component
- *
- * BETA - Main TUI dashboard view
- */
-
-const path = require('path');
-const fs = require('fs');
-
-class Dashboard {
-  constructor(options = {}) {
-    this.statusPath =
-      options.statusPath || path.join(process.cwd(), 'docs', '09-agents', 'status.json');
-    this.data = null;
-  }
-
-  async load() {
-    if (!fs.existsSync(this.statusPath)) {
-      return false;
-    }
-
-    try {
-      const content = fs.readFileSync(this.statusPath, 'utf8');
-      this.data = JSON.parse(content);
-      return true;
-    } catch (err) {
-      return false;
-    }
-  }
-
-  getStories() {
-    if (!this.data) return [];
-    return Object.values(this.data).filter(s => s && typeof s === 'object' && (s.id || s.story_id));
-  }
-
-  getStats() {
-    const stories = this.getStories();
-    return {
-      total: stories.length,
-      in_progress: stories.filter(s => ['in_progress', 'in-progress'].includes(s.status)).length,
-      blocked: stories.filter(s => s.status === 'blocked').length,
-      ready: stories.filter(s => s.status === 'ready').length,
-      completed: stories.filter(s => ['completed', 'done'].includes(s.status)).length,
-    };
-  }
-
-  getCompletionPercentage() {
-    const stats = this.getStats();
-    if (stats.total === 0) return 0;
-    return Math.round((stats.completed / stats.total) * 100);
-  }
-
-  getStoriesByStatus(status) {
-    const stories = this.getStories();
-    if (status === 'in_progress') {
-      return stories.filter(s => ['in_progress', 'in-progress'].includes(s.status));
-    }
-    if (status === 'completed') {
-      return stories.filter(s => ['completed', 'done'].includes(s.status));
-    }
-    return stories.filter(s => s.status === status);
-  }
-}
-
-module.exports = Dashboard;

package/tools/cli/tui/StoryList.js

@@ -1,69 +0,0 @@
-/**
- * StoryList Component
- *
- * BETA - Story list rendering for TUI
- */
-
-class StoryList {
-  constructor(stories = []) {
-    this.stories = stories;
-    this.selectedIndex = 0;
-  }
-
-  setStories(stories) {
-    this.stories = stories;
-    this.selectedIndex = 0;
-  }
-
-  selectNext() {
-    if (this.selectedIndex < this.stories.length - 1) {
-      this.selectedIndex++;
-    }
-    return this.getSelected();
-  }
-
-  selectPrev() {
-    if (this.selectedIndex > 0) {
-      this.selectedIndex--;
-    }
-    return this.getSelected();
-  }
-
-  getSelected() {
-    return this.stories[this.selectedIndex] || null;
-  }
-
-  filter(predicate) {
-    return new StoryList(this.stories.filter(predicate));
-  }
-
-  sortByPriority() {
-    const priorityOrder = {
-      blocked: 0,
-      in_progress: 1,
-      'in-progress': 1,
-      ready: 2,
-      draft: 3,
-      completed: 4,
-      done: 4,
-    };
-
-    return new StoryList(
-      [...this.stories].sort((a, b) => {
-        const aPriority = priorityOrder[a.status] ?? 99;
-        const bPriority = priorityOrder[b.status] ?? 99;
-        return aPriority - bPriority;
-      })
-    );
-  }
-
-  toArray() {
-    return [...this.stories];
-  }
-
-  get length() {
-    return this.stories.length;
-  }
-}
-
-module.exports = StoryList;

package/tools/cli/tui/index.js

@@ -1,16 +0,0 @@
-/**
- * AgileFlow TUI Components
- *
- * BETA - Internal use only, not publicly documented
- *
- * This module contains TUI components for the AgileFlow dashboard.
- * Currently in early development.
- */
-
-const Dashboard = require('./Dashboard');
-const StoryList = require('./StoryList');
-
-module.exports = {
-  Dashboard,
-  StoryList,
-};