agileflow 3.4.3 → 4.0.0-alpha.10

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

@@ -1,241 +0,0 @@
-/**
- * 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/src/core/templates/worktrees-guide.md

@@ -1,231 +0,0 @@
-# Git Worktrees with AgileFlow
-
-Git worktrees allow you to work on multiple branches simultaneously in separate directories. This is perfect for isolating experimental work, handling urgent hotfixes during feature development, or comparing different architectural approaches—all without losing your AI context with Claude Code.
-
-## What Are Git Worktrees?
-
-Git worktrees let you check out multiple branches into separate physical directories, all linked to the same repository. Think of it as having multiple "copies" of your project, each on a different branch, without the overhead of multiple clones.
-
-**Key Benefits:**
-- **Context Preservation**: Each directory maintains its own `/babysit` session with full AI context
-- **Zero Context Switching**: No need to `git stash` and re-explain your work to Claude
-- **Safe Isolation**: Experiment with risky changes without affecting your main work
-- **Instant Availability**: Your main work stays exactly as you left it
-
-## ✅ GOOD Use Cases
-
-### 1. Critical Hotfix During Feature Development
-
-**Scenario:** You're deep in feature work when a production bug needs immediate attention.
-
-```bash
-# You're 2 hours into building a dashboard, Claude has full context
-~/myapp/
-/agileflow:babysit "Build analytics dashboard with charts and filters"
-
-# URGENT: Production authentication is broken!
-# Create hotfix worktree in 10 seconds
-git worktree add ../myapp-hotfix hotfix/auth-bug
-code ../myapp-hotfix    # Opens in NEW window
-
-# In hotfix window - fresh babysit session
-cd ../myapp-hotfix
-/agileflow:babysit "Fix authentication 500 error in src/auth/login.ts"
-
-# Babysit reads CLAUDE.md, understands architecture, fixes bug
-# Creates PR, merges to main
-
-# Close hotfix window, remove worktree
-cd ~/myapp
-git worktree remove ../myapp-hotfix
-
-# Back to ORIGINAL window - Claude still remembers everything!
-"Continue building the dashboard" → Claude picks up exactly where you left off
-```
-
-**Time Saved:** 25+ minutes of context switching
-
-### 2. Comparing Architectural Approaches
-
-**Scenario:** You need to evaluate GraphQL vs REST before committing to one.
-
-```bash
-# Test GraphQL implementation
-git worktree add ../myapp-graphql experiment/graphql-api
-cd ../myapp-graphql
-/agileflow:babysit "Implement user API using GraphQL with Apollo Server"
-
-# Test REST implementation
-git worktree add ../myapp-rest experiment/rest-api
-cd ../myapp-rest
-/agileflow:babysit "Implement user API using Express REST endpoints"
-
-# Compare: Performance, DX, bundle size, complexity
-# Merge the winner, delete the loser
-
-cd ~/myapp
-git merge experiment/graphql-api  # Or experiment/rest-api
-git worktree remove ../myapp-graphql ../myapp-rest
-```
-
-### 3. Safe Testing of Risky Refactors
-
-```bash
-# Keep main work safe
-~/myapp/ → /agileflow:babysit "Continue building features on stable codebase"
-
-# Test risky migration in isolation
-git worktree add ../myapp-ts-migration experiment/typescript
-cd ../myapp-ts-migration
-/agileflow:babysit "Migrate entire codebase from JavaScript to TypeScript"
-
-# If migration succeeds → merge
-# If it fails catastrophically → delete worktree (no git history pollution)
-git worktree remove ../myapp-ts-migration
-```
-
-## ⚠️ CRITICAL LIMITATIONS
-
-### DO NOT Run Multiple Babysits on the Same Epic
-
-AgileFlow's status.json and bus/log.jsonl are **file-based** (docs-as-code philosophy). Multiple processes writing the same file simultaneously can cause:
-- **Lost status updates** (read-modify-write race condition)
-- **Corrupted JSON** (incomplete writes)
-- **Inconsistent agent coordination** (message bus conflicts)
-
-**❌ WRONG - Concurrent Edits:**
-```bash
-# Worktree 1
-cd ~/myapp-feature-a
-/agileflow:babysit "Work on EP-001: User Authentication"
-# Updates status.json: US-001 → in-progress
-
-# Worktree 2 (SIMULTANEOUSLY)
-cd ~/myapp-feature-b
-/agileflow:babysit "Work on EP-001: User Authentication"
-# Updates status.json: US-002 → in-progress
-
-# RESULT: Race condition! One update may be lost! ❌
-```
-
-**✅ CORRECT - Isolated Epics:**
-```bash
-# Worktree 1: Epic isolation
-cd ~/myapp-auth
-/agileflow:babysit "Work on EP-001: User Authentication"
-
-# Worktree 2: DIFFERENT epic
-cd ~/myapp-payment
-/agileflow:babysit "Work on EP-002: Payment System"
-
-# Different epics → different story files → no conflicts ✅
-```
-
-### The Golden Rule
-
-**Use worktrees for ISOLATION, not PARALLEL EXECUTION.**
-
-## Quick Start Guide
-
-### Using the Helper Script
-
-```bash
-# Easier method (handles naming, branch creation, guidance)
-./scripts/worktree-create.sh new-feature
-
-# Opens automatically with instructions
-```
-
-### Manual Method
-
-```bash
-# Create worktree for new feature
-git worktree add ../myapp-new-feature -b feature/new-feature main
-
-# Open in new editor window
-code ../myapp-new-feature
-
-# Start babysit
-cd ../myapp-new-feature
-/agileflow:babysit
-```
-
-### Cleaning Up a Worktree
-
-```bash
-# After merging your feature
-cd ~/myapp
-git merge feature/new-feature
-
-# Remove the worktree
-git worktree remove ../myapp-new-feature
-
-# Delete the branch (optional)
-git branch -d feature/new-feature
-```
-
-## Best Practices
-
-1. **Use Descriptive Names** - `myapp-auth-refactor` not `myapp-1`
-2. **One Epic Per Worktree** - Keep work streams completely separate
-3. **Clean Up Merged Worktrees** - Run `git worktree remove` regularly
-4. **Don't Share Dependencies** - Each worktree should have its own `node_modules/`, `.venv/`, etc.
-5. **Keep Main Worktree Stable** - Use main for stable work, worktrees for experiments
-
-## Integration with AgileFlow
-
-### Message Bus Coordination
-
-AgileFlow's message bus (`docs/09-agents/bus/log.jsonl`) is shared across all worktrees. The bus is append-only (JSONL), so concurrent appends are generally safe. However, **status.json** uses read-modify-write, so avoid concurrent edits to the same stories.
-
-## Troubleshooting
-
-### "fatal: 'branch' is already checked out"
-
-```bash
-# Find where branch is checked out
-git worktree list
-
-# Remove the conflicting worktree
-git worktree remove /path/to/conflicting/worktree
-```
-
-### Disk space issues
-
-```bash
-# Use pnpm for automatic dependency deduplication
-pnpm install  # Shares packages across worktrees
-
-# Or use shared conda environment (Python)
-conda create -n myapp-shared python=3.11
-conda activate myapp-shared  # Use in all worktrees
-```
-
-### Forgotten worktrees
-
-```bash
-# List all worktrees
-git worktree list
-
-# Remove unused worktrees
-git worktree remove ../myapp-old-experiment
-
-# Auto-prune deleted worktrees
-git worktree prune
-```
-
-## Summary
-
-**Git worktrees with AgileFlow provide:**
-- ✅ Zero context switching - preserve AI understanding
-- ✅ Safe isolation - experiment without risk
-- ✅ Fast hotfixes - handle urgent work without losing flow
-- ✅ Side-by-side comparison - test alternatives in parallel
-
-**Remember:**
-- Use worktrees for **ISOLATION**, not **PARALLEL EXECUTION**
-- Avoid concurrent edits to the same epic/stories
-- Clean up merged worktrees regularly
-- Each worktree should work on different features/epics
-
-**Happy coding with preserved context!** 🚀

package/tools/agileflow-npx.js

@@ -1,52 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * AgileFlow CLI - NPX Entry Point
- *
- * This file ensures proper execution when run via npx from npm registry.
- * It preserves the user's working directory when spawning the CLI.
- */
-
-const { spawnSync } = require('node:child_process');
-const path = require('node:path');
-const fs = require('node:fs');
-
-// Check if we're running in an npx temporary directory
-const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
-
-if (isNpxExecution) {
-  // Running via npx - spawn child process to preserve user's working directory
-  const args = process.argv.slice(2);
-  const cliPath = path.join(__dirname, 'cli', 'agileflow-cli.js');
-
-  if (!fs.existsSync(cliPath)) {
-    console.error('Error: Could not find agileflow-cli.js at', cliPath);
-    console.error('Current directory:', __dirname);
-    process.exit(1);
-  }
-
-  // Execute CLI from user's working directory (process.cwd()), not npm cache
-  const result = spawnSync(process.execPath, [cliPath, ...args], {
-    stdio: 'inherit',
-    cwd: process.cwd(),
-  });
-
-  if (result.error) {
-    console.error('Error: Failed to run AgileFlow CLI:', result.error.message);
-    process.exit(1);
-  }
-
-  if (result.signal) {
-    try {
-      process.kill(process.pid, result.signal);
-    } catch {
-      process.exit(1);
-    }
-    process.exit(1);
-  }
-
-  process.exit(result.status ?? 0);
-} else {
-  // Local execution - use require
-  require('./cli/agileflow-cli.js');
-}

package/tools/cli/agileflow-cli.js

@@ -1,72 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * AgileFlow CLI - Command Router
- *
- * Routes commands to their respective handlers using Commander.js
- */
-
-const { program } = require('commander');
-const path = require('node:path');
-const fs = require('node:fs');
-
-// Load package.json for version info
-const packageJsonPath = path.join(__dirname, '..', '..', 'package.json');
-const packageJson = require(packageJsonPath);
-
-// Dynamically load all command modules
-const commandsPath = path.join(__dirname, 'commands');
-const commands = {};
-
-if (fs.existsSync(commandsPath)) {
-  const commandFiles = fs.readdirSync(commandsPath).filter(file => file.endsWith('.js'));
-
-  for (const file of commandFiles) {
-    try {
-      const command = require(path.join(commandsPath, file));
-      if (command.name) {
-        commands[command.name] = command;
-      }
-    } catch (error) {
-      console.error(`Warning: Failed to load command ${file}:`, error.message);
-    }
-  }
-}
-
-// Set up main program
-program
-  .name('agileflow')
-  .version(packageJson.version)
-  .description(
-    'AgileFlow - AI-driven agile development for Claude Code, Cursor, Windsurf, and more'
-  );
-
-// Register all commands
-for (const [name, cmd] of Object.entries(commands)) {
-  const command = program.command(name).description(cmd.description);
-
-  // Add options if defined
-  if (cmd.options) {
-    for (const option of cmd.options) {
-      command.option(...option);
-    }
-  }
-
-  // Add arguments if defined
-  if (cmd.arguments) {
-    for (const arg of cmd.arguments) {
-      command.argument(...arg);
-    }
-  }
-
-  // Set action
-  command.action(cmd.action);
-}
-
-// Parse arguments
-program.parse(process.argv);
-
-// Show help if no command provided
-if (process.argv.slice(2).length === 0) {
-  program.outputHelp();
-}