agileflow 3.3.0 → 3.4.1

package/src/core/commands/tdd-next.md

@@ -0,0 +1,238 @@
+---
+description: Advance TDD phase (RED→GREEN→REFACTOR→COMPLETE)
+argument-hint: "[<US-ID>]"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "TDD phase gate: RED→GREEN requires test_status=failing"
+    - "TDD phase gate: GREEN→REFACTOR requires test_status=passing"
+    - "TDD phase gate: REFACTOR→COMPLETE requires test_status=passing"
+    - "Always run /agileflow:verify before attempting phase advance"
+    - "Show clear phase transition banner with new phase instructions"
+  state_fields:
+    - tdd_phase
+    - test_status
+---
+
+# /agileflow:tdd-next - Advance TDD Phase
+
+Advance to the next TDD phase with gate validation.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js tdd-next
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: TDD Phase Gate Controller
+
+**Critical Rules**:
+1. Read current `tdd_phase` and `test_status` from status.json
+2. Validate transition conditions (failing/passing tests)
+3. Block advancement if conditions not met
+4. Update `tdd_phase` in status.json on success
+5. Display new phase instructions
+
+**Transitions**:
+- RED → GREEN: `test_status` must be `"failing"`
+- GREEN → REFACTOR: `test_status` must be `"passing"`
+- REFACTOR → RED (new cycle): `test_status` must be `"passing"`
+- REFACTOR → COMPLETE: `test_status` must be `"passing"`
+
+<!-- COMPACT_SUMMARY_END -->
+
+## Prompt
+
+ROLE: TDD Phase Gate Controller
+
+INPUTS
+STORY=<US-ID>   Optional - defaults to current in_progress story with active tdd_phase
+
+ACTIONS
+1) Load story and current TDD phase from status.json
+2) Determine target phase based on current phase
+3) Validate gate conditions (test_status)
+4) If gate passes: advance phase, show new instructions
+5) If gate fails: show blocking message with remedy
+
+---
+
+## Usage
+
+```
+/agileflow:tdd-next           # Advance current TDD story
+/agileflow:tdd-next US-0042   # Advance specific story
+```
+
+## Workflow
+
+### 1. Find Active TDD Story
+
+Read `docs/09-agents/status.json`. Find the story:
+- If STORY specified, use that
+- Otherwise, find the story with an active `tdd_phase` (not complete/cancelled)
+- If multiple active, ask user to specify
+
+### 2. Determine Target Phase
+
+Based on current phase, determine what to advance to:
+
+| Current | Default Next | Alternative |
+|---------|-------------|-------------|
+| RED | GREEN | cancel |
+| GREEN | REFACTOR | cancel |
+| REFACTOR | COMPLETE | RED (new cycle), cancel |
+
+For REFACTOR, ask the user:
+```json
+[
+  {"label": "Complete TDD (Recommended)", "description": "All tests pass, code is clean - ready for review"},
+  {"label": "Start new RED→GREEN cycle", "description": "More features to add with TDD discipline"},
+  {"label": "Cancel TDD", "description": "Exit TDD workflow, keep changes"}
+]
+```
+
+### 3. Validate Gate Conditions
+
+Check `test_status` in the story against transition requirements:
+
+**RED → GREEN** (needs `test_status: "failing"`):
+```
+Current: 🔴 RED phase
+Target:  🟢 GREEN phase
+Gate:    test_status must be "failing"
+Status:  test_status = "failing" ✅
+
+Advancing to GREEN phase...
+```
+
+**Gate BLOCKED example:**
+```
+Current: 🔴 RED phase
+Target:  🟢 GREEN phase
+Gate:    test_status must be "failing"
+Status:  test_status = "passing" ❌
+
+🚫 Cannot advance: Tests must FAIL before moving to GREEN.
+
+This means either:
+  1. You haven't written tests yet (write failing tests first)
+  2. Your tests pass because they don't test real behavior
+  3. The implementation already exists
+
+Action: Write tests that verify behavior not yet implemented.
+Then run /agileflow:verify to confirm they fail.
+```
+
+**No test_status at all:**
+```
+🚫 Cannot advance: No test results found.
+
+Run /agileflow:verify first to execute tests and record status.
+Then try /agileflow:tdd-next again.
+```
+
+### 4. Advance Phase
+
+On success, update status.json:
+```json
+{
+  "tdd_phase": "green",
+  "tdd_last_transition": "2026-02-25T..."
+}
+```
+
+### 5. Display New Phase Banner
+
+```
+🟢 TDD GREEN PHASE - US-0042: [Story Title]
+══════════════════════════════════════════
+
+RED → GREEN transition complete! ✅
+
+Write MINIMAL code to make tests pass. Rules:
+  • Write the simplest implementation that passes tests
+  • Do NOT refactor yet - ugly code is fine
+  • Do NOT add features beyond what tests require
+  • Do NOT modify test files (except removing .skip())
+  • Run tests frequently
+
+Next steps:
+  1. Implement code to pass the failing tests
+  2. Run /agileflow:verify to confirm tests PASS
+  3. Run /agileflow:tdd-next to advance to REFACTOR
+```
+
+### 6. AskUserQuestion
+
+After showing the transition result:
+
+**Successful advance to GREEN:**
+```json
+[
+  {"label": "Start implementing to pass tests (Recommended)", "description": "Write minimal code - tests define the requirements"},
+  {"label": "Review the failing tests first", "description": "Read test files to understand requirements"},
+  {"label": "Cancel TDD mode", "description": "Exit TDD workflow, keep test files"}
+]
+```
+
+**Successful advance to REFACTOR:**
+```json
+[
+  {"label": "Start refactoring (Recommended)", "description": "Tests pass - clean up the code while keeping them green"},
+  {"label": "Run logic audit on implementation", "description": "Check for edge cases before refactoring"},
+  {"label": "Skip refactor, complete TDD", "description": "Code is clean enough - finish TDD cycle"}
+]
+```
+
+**Successful COMPLETE:**
+```json
+[
+  {"label": "Run code review (Recommended)", "description": "TDD complete - review before committing"},
+  {"label": "Commit changes", "description": "All tests pass, TDD cycle done"},
+  {"label": "Start new TDD cycle", "description": "More features to implement for this story"}
+]
+```
+
+**Gate blocked:**
+```json
+[
+  {"label": "Run /agileflow:verify (Recommended)", "description": "Execute tests to update test_status"},
+  {"label": "Review test files", "description": "Check if tests are correctly written"},
+  {"label": "Cancel TDD mode", "description": "Exit TDD workflow"}
+]
+```
+
+## Error Handling
+
+### No Active TDD Story
+```
+❌ No active TDD workflow found.
+
+Start TDD with: /agileflow:tdd US-0042
+```
+
+### Multiple Active TDD Stories
+```
+⚠️ Multiple active TDD stories found:
+  🔴 US-0042: Add auth middleware (RED phase)
+  🟢 US-0043: User settings API (GREEN phase)
+
+Specify which story: /agileflow:tdd-next US-0042
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:tdd` - Start TDD workflow
+- `/agileflow:verify` - Run tests and update test_status
+- `/agileflow:babysit` - Main implementation workflow

package/src/core/commands/tdd.md

@@ -0,0 +1,211 @@
+---
+description: Start TDD workflow with RED→GREEN→REFACTOR phases
+phase: implementation
+argument-hint: "<US-ID>"
+compact_context:
+  priority: high
+  preserve_rules:
+    - "TDD WORKFLOW ACTIVE: Enforce RED→GREEN→REFACTOR phases"
+    - "RED phase: Write failing tests ONLY - no implementation code"
+    - "GREEN phase: Minimal code to make tests pass - no extras"
+    - "REFACTOR phase: Clean up while keeping tests green"
+    - "Use /agileflow:verify to confirm test status before advancing"
+    - "Use /agileflow:tdd-next to advance to next phase"
+    - "Phase gates are HARD - cannot skip (RED needs failing tests, GREEN needs passing)"
+  state_fields:
+    - tdd_phase
+    - tdd_cycles
+    - test_status
+---
+
+# /agileflow:tdd - Test-Driven Development Workflow
+
+Start a TDD workflow for a story, enforcing RED→GREEN→REFACTOR phase discipline.
+
+---
+
+## STEP 0: Gather Context
+
+```bash
+node .agileflow/scripts/obtain-context.js tdd
+```
+
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: TDD Coach - Enforce test-first development with phase gates
+
+**Critical Rules**:
+1. Start in RED phase - write failing tests first
+2. Cannot advance to GREEN without failing tests (verified by /agileflow:verify)
+3. Cannot advance to REFACTOR without passing tests
+4. Cannot complete without passing tests after refactor
+5. Track phase in status.json story entry (`tdd_phase` field)
+
+**Phase Summary**:
+- 🔴 RED: Write tests that FAIL (test what the code SHOULD do)
+- 🟢 GREEN: Write MINIMAL code to make tests PASS
+- 🔵 REFACTOR: Clean up while keeping tests GREEN
+- ✅ COMPLETE: All tests pass, code is clean
+
+<!-- COMPACT_SUMMARY_END -->
+
+## Prompt
+
+ROLE: TDD Coach
+
+INPUTS
+STORY=<US-ID>   Required - story to start TDD for
+
+ACTIONS
+1) Load story from status.json
+2) Initialize TDD RED phase for the story
+3) Display phase instructions and constraints
+4) Guide user through test-first development
+
+---
+
+## Usage
+
+```
+/agileflow:tdd US-0042
+```
+
+## Workflow
+
+### 1. Initialize
+
+Read `docs/09-agents/status.json` and locate the story. Set:
+```json
+{
+  "tdd_phase": "red",
+  "tdd_started_at": "2026-02-25T...",
+  "tdd_cycles": 1
+}
+```
+
+If the story already has an active `tdd_phase` (not complete/cancelled), resume it instead.
+
+### 2. Display Phase Banner
+
+Show the current phase prominently:
+
+```
+🔴 TDD RED PHASE - US-0042: [Story Title]
+══════════════════════════════════════════
+
+Write FAILING tests first. Rules:
+  • Write test files ONLY - no implementation code yet
+  • Tests should cover the acceptance criteria
+  • Tests MUST fail when run (they test code that doesn't exist)
+  • Focus on the public API - what should the code DO?
+
+Allowed files: **/*.test.*, **/*.spec.*, **/tests/**, **/fixtures/**
+
+Next steps:
+  1. Write your failing tests
+  2. Run /agileflow:verify to confirm tests FAIL
+  3. Run /agileflow:tdd-next to advance to GREEN
+```
+
+### 3. Phase-Specific Guidance
+
+#### 🔴 RED Phase
+- Help user identify WHAT to test based on acceptance criteria
+- Suggest test file names and locations based on project conventions
+- Write test code that exercises the expected API/interface
+- Tests should be meaningful - not just `expect(true).toBe(false)`
+- Use the project's testing framework (detect from package.json, pytest.ini, etc.)
+
+#### 🟢 GREEN Phase (after /agileflow:tdd-next)
+- Write the simplest possible implementation to pass tests
+- Resist the urge to over-engineer or optimize
+- If a test needs a complex solution, the test may be too broad
+- Run tests frequently during implementation
+
+#### 🔵 REFACTOR Phase (after /agileflow:tdd-next)
+- Extract common patterns into helper functions
+- Improve naming and readability
+- Reduce duplication
+- Run tests after every change - any failure means rollback
+
+### 4. AskUserQuestion Integration
+
+After showing the phase banner, present smart options:
+
+**RED phase start:**
+```json
+[
+  {"label": "Show acceptance criteria for test planning (Recommended)", "description": "Review AC to identify what tests to write"},
+  {"label": "Create test file scaffold", "description": "Generate test file structure based on story requirements"},
+  {"label": "Cancel TDD mode", "description": "Exit TDD and use standard implementation workflow"}
+]
+```
+
+**After tests written (RED):**
+```json
+[
+  {"label": "Run /agileflow:verify to check tests fail (Recommended)", "description": "Tests must fail before advancing to GREEN"},
+  {"label": "Write more tests", "description": "Add additional test cases"},
+  {"label": "Cancel TDD mode", "description": "Exit TDD workflow"}
+]
+```
+
+**After verify confirms failing (RED→GREEN):**
+```json
+[
+  {"label": "Advance to GREEN phase (Recommended)", "description": "Tests are failing - ready to write implementation"},
+  {"label": "Write more failing tests first", "description": "Add more test coverage before implementing"},
+  {"label": "Cancel TDD mode", "description": "Exit TDD workflow"}
+]
+```
+
+## Integration Points
+
+### Uses
+- `docs/09-agents/status.json` - Story data and TDD phase tracking
+- `/agileflow:verify` - Test execution and status updates
+- `/agileflow:tdd-next` - Phase advancement
+
+### Used By
+- `/agileflow:babysit` - Can suggest TDD workflow for stories
+- `/agileflow:babysit STRICT=true` - TDD recommended as default approach
+
+## Error Handling
+
+### Story Not Found
+```
+❌ Story US-0099 not found in status.json
+
+Available stories:
+- US-0042: Add user authentication (ready)
+- US-0043: Implement settings page (in_progress)
+```
+
+### Already in TDD
+```
+🔴 Resuming TDD for US-0042 (RED phase, cycle 1)
+
+You're already in TDD mode. Current phase: RED
+Write failing tests, then run /agileflow:tdd-next to advance.
+```
+
+### No Test Framework Detected
+```
+⚠️ No test framework detected for this project.
+
+Run /agileflow:tests first to set up testing infrastructure,
+then restart TDD with /agileflow:tdd US-0042.
+```
+
+---
+
+## Related Commands
+
+- `/agileflow:tdd-next` - Advance TDD phase (RED→GREEN→REFACTOR→COMPLETE)
+- `/agileflow:verify` - Run tests and update test_status
+- `/agileflow:tests` - Set up testing infrastructure
+- `/agileflow:babysit` - Main implementation workflow (can integrate TDD)

package/src/core/commands/team/start.md

@@ -43,12 +43,16 @@ node -e "console.log(JSON.stringify({ agentTeams: !!process.env.CLAUDE_CODE_EXPE
 
 The argument specifies which team template to use. Available templates are in `.agileflow/teams/`:
 
-| Template | Description |
-|----------|-------------|
-| `fullstack` | API + UI + Testing specialists |
-| `code-review` | Code reviewer + Security + Performance |
-| `builder-validator` | Paired builders with validators |
-| `logic-audit` | Multi-perspective logic analysis |
+| Template | Description | Best For |
+|----------|-------------|----------|
+| `fullstack` | API + UI + Testing specialists | Full-stack feature development |
+| `backend` | API + Database + Security specialists | Backend/API work |
+| `frontend` | UI + Accessibility + Testing specialists | Frontend/component work |
+| `solo` | Mentor + Testing (lightweight) | Solo developers, learning |
+| `qa` | QA Strategy + Testing + Browser QA | Test coverage, regression |
+| `code-review` | Code reviewer + Security + Performance | Pre-PR quality gates |
+| `builder-validator` | Paired builders with validators | High-reliability features |
+| `logic-audit` | Multi-perspective logic analysis | Complex business logic |
 
 If no argument given, use AskUserQuestion to let user choose.
 

package/src/core/commands/tests.md

@@ -1,5 +1,6 @@
 ---
 description: Set up automated testing infrastructure
+phase: implementation
 argument-hint: "(no arguments)"
 compact_context:
   priority: high

package/src/core/commands/verify.md

@@ -1,5 +1,6 @@
 ---
 description: Run project tests and update story test status
+phase: implementation
 argument-hint: "[<US-ID>]"
 compact_context:
   priority: critical
@@ -259,7 +260,32 @@ Record test verification in current session:
 }
 ```
 
-### 7. Generate Report
+### 7. AC Coverage Report (Optional)
+
+After tests pass, if the current story has acceptance criteria, run the AC-to-test matcher to show coverage:
+
+```bash
+node -e "
+const { matchACToTests } = require('./.agileflow/scripts/lib/ac-test-matcher');
+const result = matchACToTests('{{STORY_ID}}');
+console.log(JSON.stringify(result, null, 2));
+"
+```
+
+Append AC coverage to the verification report:
+
+```
+AC Coverage: 3/5 (60%)
+  ✅ AC1: "Create audit command" → matched to audit.test.js (high)
+  ✅ AC2: "Accept story ID" → matched to audit.test.js (high)
+  ✅ AC3: "Run tests" → matched to verify.test.js (medium)
+  ⬜ AC4: "Check AC met" → no matching tests
+  ⬜ AC5: "Prompt for learnings" → no matching tests
+```
+
+If no story is specified or story has no AC, skip this section.
+
+### 8. Generate Report
 
 **Success Report**:
 ```

package/src/core/commands/workflow.md

@@ -1,5 +1,6 @@
 ---
 description: Define and run parameterized workflow templates
+phase: implementation
 argument-hint: "<template> [<arguments>]"
 compact_context:
   priority: normal
@@ -228,6 +229,7 @@ docs/08-project/workflows/
 ---
 name: deploy-staging
 description: Deploy to staging environment
+phase: implementation
 arguments:
   - name: version
     required: true

package/src/core/experts/_core-expertise.yaml

@@ -0,0 +1,105 @@
+# Core Expertise - Always-Loaded AgileFlow Knowledge
+# These 3 curated modules contain high-value cross-cutting patterns.
+# Loaded by all agents. Domain-specific files are reference-only (loaded on demand).
+
+version: 1.0
+last_updated: 2026-02-26
+
+# Module 1: CLI Architecture Patterns
+cli_architecture:
+  structure:
+    source: packages/cli/src/core/
+    commands: "src/core/commands/*.md - Slash commands with frontmatter"
+    agents: "src/core/agents/*.md - Spawnable agents with frontmatter"
+    experts: "src/core/experts/*/expertise.yaml - Domain knowledge"
+    skills: "src/core/skills/ - Skill learnings and marketplace (browse via /skill:recommend)"
+
+  content_injection:
+    description: "Source files use placeholders replaced at install time"
+    placeholders:
+      - "<!-- {{AGENT_LIST}} --> - Current agent list"
+      - "<!-- {{COMMAND_LIST}} --> - Current command list"
+      - "<!-- {{SKILL_LIST}} --> - Current skill list"
+    pipeline: "content-injector.js -> content-transformer.js -> IDE installer"
+
+  installers:
+    core: "tools/cli/installers/core/installer.js - Copies agents, commands, scripts"
+    ide_base: "tools/cli/installers/ide/_base-ide.js - Shared IDE setup logic"
+    claude_code: "tools/cli/installers/ide/claude-code.js - Claude Code specific (hooks, agents)"
+
+  key_conventions:
+    - "Commands: frontmatter with description, optional argument-hint"
+    - "Agents: frontmatter with name, description, tools, model (no agileflow- prefix in filename)"
+    - "Scripts in packages/cli/scripts/ are PUBLISHED (copied to user projects)"
+    - "Scripts in root scripts/ are dev-only (NOT published)"
+    - "Dynamic counts: run npm run sync-counts after adding commands/agents"
+
+# Module 2: Testing Conventions
+testing:
+  framework:
+    runner: "Jest (packages/cli/__tests__/)"
+    command: "npm test from packages/cli/"
+    total_tests: "~4373+ tests across 161+ suites"
+
+  patterns:
+    - "Tests mirror source structure: __tests__/lib/ for tools/cli/lib/"
+    - "Use jest.mock() for fs, child_process dependencies"
+    - "Expertise validation: scripts/validate-expertise.sh"
+    - "Story test tracking: status.json test_status field (passing/failing/not_run)"
+
+  quality_gates:
+    - "All tests must pass before commit"
+    - "Session Harness: /agileflow:verify runs tests for current story"
+    - "/agileflow:baseline marks verified state"
+    - "Logic audit: 5 analyzers check edge cases, race conditions, type bugs"
+
+  known_issues:
+    - "api-server port 3456 conflict causes ~10 test failures (pre-existing)"
+    - "--legacy-peer-deps required for TensorFlow.js version conflicts"
+
+# Module 3: Security Guidelines
+security:
+  commit_policy:
+    - "NO AI attribution in commits (forbidden: Co-Authored-By AI, emoji robots)"
+    - "Clean conventional commits only (feat/fix/chore/docs)"
+
+  secrets:
+    gitignored: [".npmrc", "CLAUDE.md"]
+    storage: "NPM_TOKEN in GitHub Secrets, never committed"
+
+  code_patterns:
+    - "Use execFileSync(cmd, [args]) not execSync(`cmd ${var}`) to prevent injection"
+    - "Validate PIDs are numeric, ports are numbers, paths don't traverse"
+    - "Damage control hooks guard Bash/Edit/Write via PreToolUse"
+    - "patterns.yaml defines blocked commands, read-only paths, zero-access paths"
+
+  hooks:
+    exit_codes: "0=allow, 1=error (fail-open), 2=block"
+    files:
+      - "damage-control/bash-tool-damage-control.js"
+      - "damage-control/edit-tool-damage-control.js"
+      - "damage-control/write-tool-damage-control.js"
+      - "lib/damage-control-utils.js - Shared validation logic"
+
+# Data Stores (cross-cutting knowledge)
+data_stores:
+  status_json:
+    path: "docs/09-agents/status.json"
+    schema: "epics (EP-ID keys), stories (US-ID keys)"
+    operations: "Read-modify-write with updated timestamp"
+  session_state:
+    path: "docs/09-agents/session-state.json"
+    purpose: "Active command, loop state, smart-detect results"
+  archive:
+    path: "docs/09-agents/archive/YYYY-MM.json"
+    policy: "Completed stories >7 days auto-archived"
+  metadata:
+    path: "docs/00-meta/agileflow-metadata.json"
+    purpose: "Config schema version, feature toggles, profiles"
+
+# Release Process
+release:
+  command: "./scripts/release.sh <version> <title>"
+  version_files: ["packages/cli/package.json", "package.json"]
+  ci: ".github/workflows/npm-publish.yml triggered by v*.*.* tags"
+  brand_color: "#e8683a"