agileflow 2.91.0 → 2.92.0

package/src/core/templates/story-lifecycle.md

@@ -0,0 +1,213 @@
+# Story Lifecycle
+
+This document describes how stories transition through different states in AgileFlow.
+
+---
+
+## State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> draft: create
+
+    draft --> ready: validate (DoR met)
+    draft --> draft: edit
+
+    ready --> in_progress: start work
+    ready --> blocked: dependency issue
+
+    in_progress --> in_review: submit PR
+    in_progress --> blocked: blocker found
+    in_progress --> ready: pause work
+
+    blocked --> ready: unblocked
+    blocked --> in_progress: unblocked (continue)
+
+    in_review --> done: PR merged
+    in_review --> in_progress: changes requested
+
+    done --> [*]
+```
+
+---
+
+## Story States
+
+| State | Description | Next Actions |
+|-------|-------------|--------------|
+| **draft** | Story created but not ready for work | Validate, add AC, set estimate |
+| **ready** | Definition of Ready (DoR) met | Start work, assign owner |
+| **in-progress** | Actively being worked on | Complete, submit PR, or pause |
+| **blocked** | Waiting on external dependency | Resolve blocker, escalate |
+| **in-review** | Pull request submitted | Review, approve, merge |
+| **done** | Work complete and merged | Archive, celebrate |
+
+---
+
+## State Transitions
+
+### draft → ready
+
+**Trigger**: Story passes Definition of Ready (DoR)
+
+**DoR Checklist**:
+- [ ] Clear acceptance criteria (Given/When/Then)
+- [ ] Estimate provided
+- [ ] Dependencies identified
+- [ ] Owner assigned
+- [ ] Epic linked
+
+**Command**: `/agileflow:story-validate STORY=US-XXXX`
+
+---
+
+### ready → in-progress
+
+**Trigger**: Developer starts work
+
+**Actions**:
+1. Update status.json: `status: "in-progress"`
+2. Set phase to `execute`
+3. Log to bus/log.jsonl
+
+**Command**: `/agileflow:status STORY=US-XXXX STATUS=in-progress`
+
+---
+
+### in-progress → in-review
+
+**Trigger**: Pull request created
+
+**Actions**:
+1. Update status.json: `status: "in-review"`
+2. Set phase to `audit`
+3. Add PR link
+4. Log to bus/log.jsonl
+
+**Command**: `/agileflow:status STORY=US-XXXX STATUS=in-review PR=<url>`
+
+---
+
+### in-review → done
+
+**Trigger**: PR merged to main
+
+**Actions**:
+1. Update status.json: `status: "done"`
+2. Set phase to `complete`
+3. Log completion to bus/log.jsonl
+4. Auto-archive after 7 days
+
+**Command**: `/agileflow:status STORY=US-XXXX STATUS=done`
+
+---
+
+### → blocked
+
+**Trigger**: External dependency or blocker found
+
+**Actions**:
+1. Update status.json: `status: "blocked"`
+2. Add blocker reason
+3. Log to bus/log.jsonl
+4. Notify dependent teams
+
+**Command**: `/agileflow:status STORY=US-XXXX STATUS=blocked SUMMARY="Waiting on API keys"`
+
+---
+
+## Phase Mapping
+
+Stories have both a **status** and a **phase**. Phases group statuses for high-level tracking:
+
+| Status | Phase | Description |
+|--------|-------|-------------|
+| draft | plan | Planning and scoping |
+| ready | plan | Ready for planning/assignment |
+| in-progress | execute | Active development |
+| blocked | execute | Blocked but in execute phase |
+| in-review | audit | Quality review |
+| done | complete | Work finished |
+
+---
+
+## WIP Limits
+
+AgileFlow enforces Work-In-Progress (WIP) limits to prevent overload:
+
+- **Per Agent**: Max 2 stories in `in-progress` + `in-review`
+- **Per Epic**: Configurable, typically 5-10 concurrent stories
+
+**Violation handling**:
+```
+⚠️ WIP Limit Exceeded
+
+AG-UI has 3 stories in progress (limit: 2):
+  - US-0042: Login Form
+  - US-0043: Profile Page
+  - US-0044: Dashboard
+
+Complete or pause a story before starting new work.
+```
+
+---
+
+## Lifecycle in status.json
+
+```json
+{
+  "stories": {
+    "US-0042": {
+      "id": "US-0042",
+      "title": "Login Form with Validation",
+      "epic": "EP-0010",
+      "owner": "AG-UI",
+      "status": "in-progress",
+      "phase": "execute",
+      "estimate": "2h",
+      "deps": ["US-0041"],
+      "created": "2026-01-20T10:00:00Z",
+      "updated": "2026-01-21T14:30:00Z",
+      "history": [
+        {"status": "draft", "ts": "2026-01-20T10:00:00Z"},
+        {"status": "ready", "ts": "2026-01-20T11:00:00Z"},
+        {"status": "in-progress", "ts": "2026-01-21T09:00:00Z"}
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Bus Messages
+
+State transitions are logged to `docs/09-agents/bus/log.jsonl`:
+
+```jsonl
+{"ts":"2026-01-21T09:00:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"in-progress","text":"Started work on login form"}
+{"ts":"2026-01-21T14:30:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"in-review","pr":"https://github.com/.../pull/42"}
+{"ts":"2026-01-21T16:00:00Z","type":"status","from":"AG-UI","to":"ALL","story":"US-0042","status":"done","text":"PR merged"}
+```
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/agileflow:story` | Create new story |
+| `/agileflow:status` | Update story status |
+| `/agileflow:board` | View kanban board |
+| `/agileflow:blockers` | View blocked stories |
+| `/agileflow:story-validate` | Validate DoR |
+
+---
+
+## Best Practices
+
+1. **Keep stories small**: 1-3 days of work maximum
+2. **Update status promptly**: Reflect actual work state
+3. **Document blockers**: Include reason and expected resolution
+4. **Respect WIP limits**: Complete before starting new
+5. **Use phase handoffs**: Capture context at transitions

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

@@ -8,6 +8,8 @@ estimate: {{ESTIMATE}}
 created: {{CREATED}}
 updated: {{UPDATED}}
 dependencies: {{DEPENDENCIES}}
+tdd_mode: {{TDD_MODE}}
+test_file: {{TEST_FILE}}
 ---
 
 # {{STORY_ID}}: {{TITLE}}
@@ -15,6 +17,7 @@ dependencies: {{DEPENDENCIES}}
 **Epic**: {{EPIC_ID}}
 **Owner**: {{OWNER}}
 **Estimate**: {{ESTIMATE}}
+{{TDD_BADGE}}
 
 ## Description
 {{DESCRIPTION}}
@@ -50,6 +53,7 @@ dependencies: {{DEPENDENCIES}}
 
 ## Testing Strategy
 See: `docs/07-testing/test-cases/{{STORY_ID}}.md`
+{{TDD_TEST_FILE_REF}}
 
 ## Dependencies
 {{DEPENDENCIES}}

package/src/core/templates/tdd-test-template.js

@@ -0,0 +1,241 @@
+/**
+ * TDD Test Template for AgileFlow Story Creation
+ *
+ * This template generates framework-specific test stubs from acceptance criteria.
+ * Used by /agileflow:story when TDD=true flag is set.
+ *
+ * Placeholders:
+ * - {{STORY_ID}} - Story identifier (e.g., US-0042)
+ * - {{TITLE}} - Story title
+ * - {{EPIC}} - Epic identifier (e.g., EP-0010)
+ * - {{AC_TESTS}} - Generated test cases from acceptance criteria
+ * - {{CREATED}} - ISO timestamp
+ */
+
+// Template for Jest/Vitest (JavaScript/TypeScript)
+const jestTemplate = `/**
+ * TDD Tests for {{STORY_ID}}: {{TITLE}}
+ *
+ * Story: docs/06-stories/{{EPIC}}/{{STORY_ID}}-*.md
+ * Created: {{CREATED}}
+ *
+ * These tests are generated from acceptance criteria.
+ * Implementation goal: Make all tests pass.
+ *
+ * Workflow:
+ * 1. Review each test case (currently skipped)
+ * 2. Implement the feature code
+ * 3. Remove .skip from tests one at a time
+ * 4. Run tests until all pass
+ */
+
+describe('{{STORY_ID}}: {{TITLE}}', () => {
+{{AC_TESTS}}
+});
+`;
+
+// Template for individual AC test block (Jest)
+const jestAcTemplate = `
+  // {{AC_LABEL}}: {{AC_SUMMARY}}
+  describe('{{AC_SUMMARY}}', () => {
+    it.skip('should {{THEN_CLAUSE}}', () => {
+      // Given: {{GIVEN_CLAUSE}}
+      // TODO: Set up test preconditions
+
+      // When: {{WHEN_CLAUSE}}
+      // TODO: Execute the action
+
+      // Then: {{THEN_CLAUSE}}
+      // TODO: Add assertions
+      expect(true).toBe(true);
+    });
+  });
+`;
+
+// Template for pytest (Python)
+const pytestTemplate = `"""
+TDD Tests for {{STORY_ID}}: {{TITLE}}
+
+Story: docs/06-stories/{{EPIC}}/{{STORY_ID}}-*.md
+Created: {{CREATED}}
+
+These tests are generated from acceptance criteria.
+Implementation goal: Make all tests pass.
+
+Workflow:
+1. Review each test case (currently skipped)
+2. Implement the feature code
+3. Remove @pytest.mark.skip from tests one at a time
+4. Run tests until all pass
+"""
+
+import pytest
+
+{{AC_TESTS}}
+`;
+
+// Template for individual AC test block (pytest)
+const pytestAcTemplate = `
+# {{AC_LABEL}}: {{AC_SUMMARY}}
+class Test{{AC_CLASS_NAME}}:
+    @pytest.mark.skip(reason="TDD: Implement feature first")
+    def test_{{TEST_NAME}}(self):
+        """
+        Given: {{GIVEN_CLAUSE}}
+        When: {{WHEN_CLAUSE}}
+        Then: {{THEN_CLAUSE}}
+        """
+        # TODO: Set up test preconditions (Given)
+
+        # TODO: Execute the action (When)
+
+        # TODO: Add assertions (Then)
+        assert True
+`;
+
+// Template for Go tests
+const goTestTemplate = `package {{PACKAGE_NAME}}_test
+
+/*
+TDD Tests for {{STORY_ID}}: {{TITLE}}
+
+Story: docs/06-stories/{{EPIC}}/{{STORY_ID}}-*.md
+Created: {{CREATED}}
+
+These tests are generated from acceptance criteria.
+Implementation goal: Make all tests pass.
+*/
+
+import (
+	"testing"
+)
+
+{{AC_TESTS}}
+`;
+
+// Template for individual AC test block (Go)
+const goAcTemplate = `
+// {{AC_LABEL}}: {{AC_SUMMARY}}
+func Test{{AC_FUNC_NAME}}(t *testing.T) {
+	t.Skip("TDD: Implement feature first")
+
+	// Given: {{GIVEN_CLAUSE}}
+	// TODO: Set up test preconditions
+
+	// When: {{WHEN_CLAUSE}}
+	// TODO: Execute the action
+
+	// Then: {{THEN_CLAUSE}}
+	// TODO: Add assertions
+}
+`;
+
+// Export templates for use by story.md command
+module.exports = {
+  jest: {
+    file: jestTemplate,
+    ac: jestAcTemplate,
+    extension: '.test.ts',
+    directory: '__tests__'
+  },
+  vitest: {
+    file: jestTemplate, // Same format as Jest
+    ac: jestAcTemplate,
+    extension: '.test.ts',
+    directory: '__tests__'
+  },
+  pytest: {
+    file: pytestTemplate,
+    ac: pytestAcTemplate,
+    extension: '_test.py',
+    directory: 'tests'
+  },
+  go: {
+    file: goTestTemplate,
+    ac: goAcTemplate,
+    extension: '_test.go',
+    directory: ''
+  },
+
+  /**
+   * Parse acceptance criteria into structured format
+   * @param {string} acText - Raw AC text with Given/When/Then
+   * @returns {Array} Parsed AC objects
+   */
+  parseAcceptanceCriteria(acText) {
+    const criteria = [];
+    const acBlocks = acText.split(/(?=(?:AC\d+|###?\s*AC))/i);
+
+    for (const block of acBlocks) {
+      if (!block.trim()) continue;
+
+      // Extract label (AC1, AC2, etc.)
+      const labelMatch = block.match(/(?:AC\s*)?(\d+)/i);
+      const label = labelMatch ? `AC${labelMatch[1]}` : `AC${criteria.length + 1}`;
+
+      // Extract Given/When/Then
+      const givenMatch = block.match(/\*?\*?Given\*?\*?[:\s]+(.+?)(?=\*?\*?When|$)/is);
+      const whenMatch = block.match(/\*?\*?When\*?\*?[:\s]+(.+?)(?=\*?\*?Then|$)/is);
+      const thenMatch = block.match(/\*?\*?Then\*?\*?[:\s]+(.+?)(?=\*?\*?(?:Given|AC|###)|$)/is);
+
+      if (givenMatch || whenMatch || thenMatch) {
+        criteria.push({
+          label,
+          given: givenMatch ? givenMatch[1].trim() : 'preconditions are met',
+          when: whenMatch ? whenMatch[1].trim() : 'action is performed',
+          then: thenMatch ? thenMatch[1].trim() : 'expected result occurs',
+          summary: this.generateSummary(givenMatch, whenMatch, thenMatch)
+        });
+      }
+    }
+
+    // If no structured AC found, create one from the whole text
+    if (criteria.length === 0 && acText.trim()) {
+      criteria.push({
+        label: 'AC1',
+        given: 'the feature is implemented',
+        when: 'user interacts with it',
+        then: 'expected behavior occurs',
+        summary: acText.substring(0, 50).trim()
+      });
+    }
+
+    return criteria;
+  },
+
+  /**
+   * Generate a short summary from Given/When/Then
+   */
+  generateSummary(givenMatch, whenMatch, thenMatch) {
+    if (thenMatch) {
+      // Use Then clause, truncated
+      return thenMatch[1].trim().substring(0, 50).replace(/[^\w\s]/g, '');
+    }
+    if (whenMatch) {
+      return whenMatch[1].trim().substring(0, 50).replace(/[^\w\s]/g, '');
+    }
+    return 'acceptance criteria';
+  },
+
+  /**
+   * Convert string to valid function/class name
+   */
+  toIdentifier(str) {
+    return str
+      .replace(/[^\w\s]/g, '')
+      .split(/\s+/)
+      .map((word, i) => i === 0 ? word.toLowerCase() : word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+  },
+
+  /**
+   * Convert string to PascalCase for class names
+   */
+  toPascalCase(str) {
+    return str
+      .replace(/[^\w\s]/g, '')
+      .split(/\s+/)
+      .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+      .join('');
+  }
+};

package/tools/cli/commands/setup.js

@@ -7,6 +7,7 @@
 
 const chalk = require('chalk');
 const path = require('node:path');
+const fs = require('node:fs');
 const { spawnSync } = require('node:child_process');
 const semver = require('semver');
 const { Installer } = require('../installers/core/installer');
@@ -90,6 +91,7 @@ module.exports = {
           agileflowFolder: '.agileflow',
           docsFolder: 'docs',
           updateGitignore: true,
+          claudeMdReinforcement: true,
         };
       } else {
         // Interactive prompts
@@ -110,6 +112,16 @@ module.exports = {
       success(`Installed ${coreResult.counts.commands} commands`);
       success(`Installed ${coreResult.counts.skills} skills`);
 
+      // Report shell alias setup
+      if (coreResult.shellAliases) {
+        if (coreResult.shellAliases.configured.length > 0) {
+          success(`Added 'af' alias to: ${coreResult.shellAliases.configured.join(', ')}`);
+        }
+        if (coreResult.shellAliases.skipped.length > 0) {
+          info(`Shell aliases skipped: ${coreResult.shellAliases.skipped.join(', ')}`);
+        }
+      }
+
       // Setup IDE configurations
       displaySection('Configuring IDEs');
 
@@ -133,6 +145,73 @@ module.exports = {
         }
       }
 
+      // CLAUDE.md reinforcement for /babysit AskUserQuestion rules
+      if (config.claudeMdReinforcement) {
+        const claudeMdPath = path.join(config.directory, 'CLAUDE.md');
+        const claudeMdMarker = '<!-- AGILEFLOW_BABYSIT_RULES -->';
+        const claudeMdContent = `
+
+${claudeMdMarker}
+## AgileFlow /babysit Context Preservation Rules
+
+When \`/agileflow:babysit\` is active (check session-state.json), these rules are MANDATORY:
+
+1. **ALWAYS end responses with the AskUserQuestion tool** - Not text like "What next?" but the ACTUAL TOOL CALL
+2. **Use Plan Mode for non-trivial tasks** - Call \`EnterPlanMode\` before complex implementations
+3. **Delegate complex work to domain experts** - Use \`Task\` tool with appropriate \`subagent_type\`
+4. **Track progress with TodoWrite** - For any task with 3+ steps
+
+These rules persist across conversation compaction. Check \`docs/09-agents/session-state.json\` for active commands.
+${claudeMdMarker}
+`;
+
+        try {
+          let existingContent = '';
+          if (fs.existsSync(claudeMdPath)) {
+            existingContent = fs.readFileSync(claudeMdPath, 'utf8');
+          }
+
+          // Only append if marker doesn't exist
+          if (!existingContent.includes(claudeMdMarker)) {
+            fs.appendFileSync(claudeMdPath, claudeMdContent);
+            success('Added /babysit rules to CLAUDE.md');
+          } else {
+            info('CLAUDE.md already has /babysit rules');
+          }
+        } catch (err) {
+          warning(`Could not update CLAUDE.md: ${err.message}`);
+        }
+      }
+
+      // Update metadata with config tracking
+      try {
+        const metadataPath = path.join(config.directory, config.docsFolder, '00-meta', 'agileflow-metadata.json');
+        if (fs.existsSync(metadataPath)) {
+          const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+          const packageJson = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+
+          // Track config schema version and profile
+          metadata.config_schema_version = packageJson.version;
+          metadata.active_profile = options.yes ? 'default' : null; // null = custom
+
+          // Track config options that were configured
+          if (!metadata.agileflow) metadata.agileflow = {};
+          if (!metadata.agileflow.config_options) metadata.agileflow.config_options = {};
+
+          metadata.agileflow.config_options.claudeMdReinforcement = {
+            available_since: '2.92.0',
+            configured: true,
+            enabled: config.claudeMdReinforcement,
+            configured_at: new Date().toISOString(),
+            description: 'Add /babysit AskUserQuestion rules to CLAUDE.md',
+          };
+
+          fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n');
+        }
+      } catch (err) {
+        // Silently fail - metadata tracking is non-critical
+      }
+
       // Final summary
       console.log(chalk.green('\n✨ Setup complete!\n'));
 
@@ -141,6 +220,13 @@ module.exports = {
       info(`Run 'npx agileflow status' to check setup`);
       info(`Run 'npx agileflow update' to get updates`);
 
+      // Shell alias reload reminder
+      if (coreResult.shellAliases?.configured?.length > 0) {
+        console.log(chalk.bold('\nShell aliases:'));
+        info(`Reload shell to use: ${chalk.cyan('source ~/.bashrc')} or ${chalk.cyan('source ~/.zshrc')}`);
+        info(`Then run ${chalk.cyan('af')} to start Claude in tmux (or ${chalk.cyan('claude')} for normal)`);
+      }
+
       console.log(chalk.dim(`\nInstalled to: ${coreResult.path}\n`));
 
       process.exit(0);

package/tools/cli/installers/core/installer.js

@@ -164,6 +164,10 @@ class Installer {
       spinner.text = 'Installing changelog...';
       await this.installChangelog(agileflowDir, { force: effectiveForce });
 
+      // Set up shell aliases for claude command
+      spinner.text = 'Setting up shell aliases...';
+      const aliasResult = await this.setupShellAliases(directory, { force: effectiveForce });
+
       // Create config.yaml
       spinner.text = 'Creating configuration...';
       await this.createConfig(agileflowDir, userName, agileflowFolder, { force: effectiveForce });
@@ -191,6 +195,7 @@ class Installer {
         projectDir: directory,
         counts,
         fileOps,
+        shellAliases: aliasResult,
       };
     } catch (error) {
       spinner.fail('Installation failed');
@@ -813,6 +818,95 @@ class Installer {
     }
   }
 
+  /**
+   * Set up shell aliases for the claude command
+   * Adds aliases to ~/.bashrc and/or ~/.zshrc so 'claude' auto-spawns tmux
+   * @param {string} directory - Project directory (used for relative path in alias)
+   * @param {Object} options - Setup options
+   * @param {boolean} options.force - Overwrite existing aliases
+   * @returns {Promise<Object>} Result with shells configured
+   */
+  async setupShellAliases(directory, options = {}) {
+    const os = require('os');
+    const result = {
+      configured: [],
+      skipped: [],
+      error: null,
+    };
+
+    // Only set up aliases on Unix-like systems
+    if (process.platform === 'win32') {
+      result.skipped.push('Windows (not supported)');
+      return result;
+    }
+
+    const homeDir = os.homedir();
+    const aliasBlock = `
+# AgileFlow tmux wrapper
+# Use 'af' or 'agileflow' for tmux, 'claude' stays normal
+alias af="bash .agileflow/scripts/af"
+alias agileflow="bash .agileflow/scripts/af"
+`;
+
+    const marker = '# AgileFlow tmux wrapper';
+    const rcFiles = [
+      { name: 'bash', path: path.join(homeDir, '.bashrc') },
+      { name: 'zsh', path: path.join(homeDir, '.zshrc') },
+    ];
+
+    for (const rc of rcFiles) {
+      try {
+        // Check if RC file exists
+        if (!(await fs.pathExists(rc.path))) {
+          result.skipped.push(`${rc.name} (no ${path.basename(rc.path)})`);
+          continue;
+        }
+
+        const content = await fs.readFile(rc.path, 'utf8');
+
+        // Check if aliases already exist
+        if (content.includes(marker)) {
+          if (options.force) {
+            // Remove existing block and re-add
+            const lines = content.split('\n');
+            const filteredLines = [];
+            let inBlock = false;
+
+            for (const line of lines) {
+              if (line.includes(marker)) {
+                inBlock = true;
+                continue;
+              }
+              if (inBlock && line.startsWith('alias ')) {
+                continue;
+              }
+              if (inBlock && line.trim() === '') {
+                inBlock = false;
+                continue;
+              }
+              inBlock = false;
+              filteredLines.push(line);
+            }
+
+            await fs.writeFile(rc.path, filteredLines.join('\n') + aliasBlock, 'utf8');
+            result.configured.push(rc.name);
+          } else {
+            result.skipped.push(`${rc.name} (already configured)`);
+          }
+          continue;
+        }
+
+        // Append aliases to RC file
+        await fs.appendFile(rc.path, aliasBlock);
+        result.configured.push(rc.name);
+      } catch (err) {
+        result.skipped.push(`${rc.name} (error: ${err.message})`);
+      }
+    }
+
+    return result;
+  }
+
   /**
    * Get installation status
    * @param {string} directory - Project directory