agileflow 2.90.7 → 2.92.0

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

@@ -0,0 +1,125 @@
+---
+plan_id: {{PLAN_ID}}
+epic: {{EPIC_ID}}
+title: {{TITLE}}
+created: {{CREATED}}
+---
+
+# {{TITLE}}
+
+## Overview
+
+{{GOAL}}
+
+---
+
+## Phase 1: Foundation (Sequential)
+
+<!-- Stories that must complete before parallel work can begin -->
+<!-- These have no dependencies or are prerequisites for everything else -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+
+---
+
+## Phase 2: Features (Parallel-eligible)
+
+<!-- Stories that can run in parallel sessions -->
+<!-- All depend only on Phase 1 completion -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session A)
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session B)
+- [ ] {{STORY_ID}}: {{STORY_TITLE}} (Session C)
+
+---
+
+## Phase 3: Integration (Sequential)
+
+<!-- Stories that depend on Phase 2 completion -->
+<!-- Must wait for parallel work to merge -->
+
+- [ ] {{STORY_ID}}: {{STORY_TITLE}}
+
+---
+
+## Deviations Log
+
+<!-- Track decisions that differ from original plan -->
+<!-- Important: Keep this updated so next sessions have context -->
+
+| Date | Phase | Original | Changed To | Reason |
+|------|-------|----------|------------|--------|
+| | | | | |
+
+---
+
+## Session Prompts
+
+<!-- Copy-paste prompts for new parallel sessions -->
+<!-- Customize based on specific stories in Phase 2 -->
+
+### Session A prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task A: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+### Session B prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task B: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+### Session C prompt:
+```
+Read plan.md in the project root.
+Execute Phase 2 Task C: [TASK DESCRIPTION].
+Phase 1 is complete - foundation is in place.
+Check off tasks in plan.md when done.
+Log any deviations to the Deviations Log section.
+Run tests before marking complete.
+```
+
+---
+
+## Verification Session
+
+<!-- Keep one terminal dedicated to plan verification -->
+<!-- After each phase, run these checks -->
+
+### Phase completion checks:
+```
+After Phase 1:
+- [ ] All Phase 1 checkboxes checked
+- [ ] Tests passing
+- [ ] No uncommitted changes
+- [ ] Ready to spawn parallel sessions
+
+After Phase 2:
+- [ ] All Phase 2 checkboxes checked
+- [ ] All parallel branches merged
+- [ ] No merge conflicts
+- [ ] Integration tests passing
+
+After Phase 3:
+- [ ] All Phase 3 checkboxes checked
+- [ ] Final tests passing
+- [ ] Ready for review/deploy
+```
+
+---
+
+## Notes
+
+<!-- Additional context, risks, or decisions -->
+<!-- Reference ADRs if architectural decisions were made -->
+

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('');
+  }
+};