ai-sdlc 0.1.0-alpha.9 → 0.1.0

package/README.md

@@ -7,14 +7,15 @@ Agent-first SDLC workflow manager using Claude Agent SDK. A Kanban-style board w
 
 ## Features
 
-- 📋 Kanban-style story management (Backlog → Ready → In Progress → Done)
-- 🤖 AI-powered agents for each workflow stage
-- 🚀 **Full SDLC automation** for individual stories with `--auto --story` (refine → research → plan → implement → review)
-- 🔄 **Resume workflows after interruption** with `--continue` flag
-- 🎨 Customizable themes (auto, light, dark, none)
-- 📊 Visual progress tracking with status flags
-- ⚡ Automatic state assessment and action recommendations
-- ♻️ Smart phase skipping (automatically skips completed phases)
+- 📋 **Kanban-style story management** (Backlog → Ready → In Progress → Done)
+- 🤖 **AI-powered agents** for each workflow stage (refine, research, plan, implement, review)
+- 🚀 **Full SDLC automation** with `--auto --story` - takes a story from idea to reviewed code
+- 🔴🟢🔵 **TDD Mode** - Optional Test-Driven Development enforcement with Red-Green-Refactor cycles
+- 🔄 **Resume workflows** after interruption with `--continue` flag
+- 👀 **Daemon mode** - Continuously watch for and process new stories with `--watch`
+- 🎨 **Customizable themes** (auto, light, dark, none)
+- 📊 **Visual progress tracking** with status flags [R][P][I][V]
+- ♻️ **Smart phase skipping** - automatically skips completed phases
 
 ## Installation
 
@@ -26,22 +27,33 @@ npm run build
 ## Quick Start
 
 ```bash
-# Initialize the .ai-sdlc folder
+# 1. Initialize the project
 ai-sdlc init
 
-# Add a new story
+# 2. Add a story to the backlog
 ai-sdlc add "Implement user authentication"
 
-# Run the workflow (process next action)
-ai-sdlc run
-
-# Process all pending actions automatically
-ai-sdlc run --auto
+# 3. View your board
+ai-sdlc status
 
-# Resume workflow after interruption
-ai-sdlc run --continue
+# 4. Run the full SDLC for a story (refine → research → plan → implement → review)
+ai-sdlc run --auto --story implement-user-authentication
 ```
 
+### Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-sdlc status` | View all stories in Kanban board |
+| `ai-sdlc add "title"` | Add a new story to backlog |
+| `ai-sdlc run` | Process next recommended action |
+| `ai-sdlc run --auto` | Process all pending actions |
+| `ai-sdlc run --auto --story <id>` | Full SDLC for one story |
+| `ai-sdlc run --continue` | Resume after interruption |
+| `ai-sdlc run --watch` | Daemon mode - watch for new stories |
+| `ai-sdlc details <id>` | Show story details |
+| `ai-sdlc config` | View/set configuration |
+
 ## CLI Commands
 
 ### `init`
@@ -415,6 +427,118 @@ ai-sdlc run --auto --story my-feature --step research
 - ❌ Running just one specific phase (use `--story --step` instead)
 - ❌ Interactive workflows requiring manual review between phases
 
+## TDD Mode (Test-Driven Development)
+
+TDD mode enforces strict Test-Driven Development practices during implementation, ensuring code is developed using the Red-Green-Refactor cycle. This helps eliminate review failures caused by missing or improperly sequenced tests.
+
+### Enabling TDD Mode
+
+**Per-story** (recommended for gradual adoption):
+
+Add `tdd_enabled: true` to your story's frontmatter:
+
+```yaml
+---
+id: story-abc123
+title: Add user authentication
+status: ready
+tdd_enabled: true
+---
+```
+
+**Globally** (for all stories):
+
+Add to your `.ai-sdlc.json` config:
+
+```json
+{
+  "tdd": {
+    "enabled": true
+  }
+}
+```
+
+### How TDD Mode Works
+
+When TDD is enabled, the implementation agent follows a strict Red-Green-Refactor cycle for each acceptance criterion:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    TDD Cycle (per AC)                           │
+├─────────────────────────────────────────────────────────────────┤
+│  🔴 RED      → Write failing test    → Verify test FAILS        │
+│  🟢 GREEN    → Write minimum code    → Verify test PASSES       │
+│              →                       → Verify NO regressions    │
+│  🔵 REFACTOR → Improve code quality  → Verify ALL tests pass    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Cycle enforcement:**
+1. **RED**: Agent writes a test for the next acceptance criterion, verifies it fails
+2. **GREEN**: Agent writes minimum code to pass, verifies test passes and no regressions
+3. **REFACTOR**: Agent improves code quality, verifies all tests still pass
+4. **Record**: Cycle is recorded to story frontmatter and persisted
+5. **Repeat**: Process continues until all acceptance criteria are covered
+
+### TDD Validation in Review
+
+When TDD is enabled, the review agent validates that:
+- All TDD cycles have complete RED → GREEN → REFACTOR phases
+- All tests remained green after each phase
+- No cycles were skipped or incomplete
+
+Violations generate critical review issues that must be addressed.
+
+### TDD Configuration Options
+
+```json
+{
+  "tdd": {
+    "enabled": false,
+    "strictMode": true,
+    "maxCycles": 50,
+    "requireApprovalPerCycle": false
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Enable TDD mode globally (can be overridden per-story) |
+| `strictMode` | `true` | Reserved for future strict enforcement rules |
+| `maxCycles` | `50` | Maximum TDD cycles before stopping (prevents infinite loops) |
+| `requireApprovalPerCycle` | `false` | Reserved for future approval workflow |
+
+### TDD Cycle History
+
+TDD cycles are recorded in the story frontmatter for audit and debugging:
+
+```yaml
+tdd_test_history:
+  - test_name: "should authenticate valid user"
+    test_file: "src/auth/login.test.ts"
+    red_timestamp: "2024-01-15T10:00:00.000Z"
+    green_timestamp: "2024-01-15T10:05:00.000Z"
+    refactor_timestamp: "2024-01-15T10:08:00.000Z"
+    all_tests_green: true
+    cycle_number: 1
+```
+
+History is trimmed to the last 100 cycles to prevent unbounded growth.
+
+### When to Use TDD Mode
+
+**Ideal for:**
+- ✅ New feature development where test coverage is critical
+- ✅ Teams adopting TDD practices
+- ✅ Stories with clear, testable acceptance criteria
+- ✅ Reducing review failures from missing tests
+
+**Consider standard mode for:**
+- ❌ Quick fixes or hotfixes where speed is critical
+- ❌ Refactoring tasks without new functionality
+- ❌ Stories without clear testable criteria
+
 ## Daemon/Watch Mode (--watch)
 
 The `--watch` flag runs AI-SDLC in daemon mode, continuously monitoring the backlog folder for new stories and automatically processing them through the full workflow pipeline.
@@ -729,12 +853,32 @@ Configuration is stored in `.ai-sdlc.json` at the project root.
     "requireApprovalBeforePR": false,
     "autoMergeOnApproval": false
   },
+  "tdd": {
+    "enabled": false,
+    "strictMode": true,
+    "maxCycles": 50,
+    "requireApprovalPerCycle": false
+  },
   "defaultLabels": [],
   "theme": "auto",
   "settingSources": []
 }
 ```
 
+**Configuration options:**
+
+| Section | Option | Default | Description |
+|---------|--------|---------|-------------|
+| `sdlcFolder` | - | `.ai-sdlc` | Folder for story files |
+| `stageGates` | `requireApprovalBeforeImplementation` | `false` | Pause before implementation |
+| `stageGates` | `requireApprovalBeforePR` | `false` | Pause before PR creation |
+| `stageGates` | `autoMergeOnApproval` | `false` | Auto-merge approved PRs |
+| `tdd` | `enabled` | `false` | Enable TDD mode globally |
+| `tdd` | `strictMode` | `true` | Reserved for future use |
+| `tdd` | `maxCycles` | `50` | Max TDD cycles per story |
+| `tdd` | `requireApprovalPerCycle` | `false` | Reserved for future use |
+| `theme` | - | `auto` | Color theme (auto/light/dark/none) |
+
 ### Project Settings with CLAUDE.md
 
 The Agent SDK can automatically load custom instructions from a `CLAUDE.md` file in your project's `.claude/` directory. This feature allows teams to share consistent AI behavior across all team members without manually specifying custom instructions.

package/dist/agents/implementation.d.ts

@@ -1,7 +1,85 @@
-import { AgentProgressCallback } from '../core/client.js';
-import { AgentResult } from '../types/index.js';
+import { runAgentQuery, AgentProgressCallback } from '../core/client.js';
+import { Story, AgentResult, TDDTestCycle } from '../types/index.js';
 import { AgentOptions } from './research.js';
 export type { AgentProgressCallback };
+/**
+ * Result from a TDD phase execution
+ */
+export interface TDDPhaseResult {
+    testName: string;
+    testFile: string;
+    timestamp: string;
+    output: string;
+    success: boolean;
+}
+/**
+ * Options for TDD phase execution (allows mocking for tests)
+ */
+export interface TDDPhaseOptions {
+    workingDir: string;
+    runAgentQuery?: typeof runAgentQuery;
+    onProgress?: AgentProgressCallback;
+}
+/**
+ * Options for full TDD implementation (allows mocking for tests)
+ */
+export interface TDDImplementationOptions {
+    runAgentQuery?: typeof runAgentQuery;
+    runSingleTest?: typeof runSingleTest;
+    runAllTests?: typeof runAllTests;
+    onProgress?: AgentProgressCallback;
+}
+export declare const TDD_SYSTEM_PROMPT = "You are practicing strict Test-Driven Development.\n\nYour workflow MUST follow this exact cycle:\n\n**RED Phase**:\n1. Write ONE test that expresses the next acceptance criterion\n2. The test MUST fail because the functionality doesn't exist\n3. Run the test and verify it fails\n4. Explain why it fails and what it's testing\n\n**GREEN Phase**:\n1. Write the MINIMUM code to make this ONE test pass\n2. Do NOT add extra features\n3. Run the test to verify it passes\n4. Run ALL tests to ensure nothing broke\n\n**REFACTOR Phase**:\n1. Look for improvements (DRY, clarity, performance)\n2. Make changes ONLY if tests stay green\n3. Run ALL tests after each change\n\nComplete one full cycle before starting the next test.\nNever write code before writing a test.\nNever write multiple tests before making the first one pass.";
+/**
+ * Run a single test file and return pass/fail result
+ */
+export declare function runSingleTest(testFile: string, workingDir: string, testTimeout: number): Promise<{
+    passed: boolean;
+    output: string;
+}>;
+/**
+ * Run all tests and return pass/fail result
+ */
+export declare function runAllTests(workingDir: string, testTimeout: number): Promise<{
+    passed: boolean;
+    output: string;
+}>;
+/**
+ * RED Phase: Write a failing test
+ *
+ * Creates a test that expresses the next acceptance criterion.
+ * The test MUST fail because the functionality doesn't exist yet.
+ */
+export declare function executeRedPhase(story: Story, cycleNumber: number, options: TDDPhaseOptions): Promise<TDDPhaseResult>;
+/**
+ * GREEN Phase: Write minimum code to pass the test
+ *
+ * Implements just enough code to make the failing test pass.
+ * Does NOT add extra features or optimizations.
+ */
+export declare function executeGreenPhase(story: Story, cycleNumber: number, testFile: string, options: TDDPhaseOptions): Promise<TDDPhaseResult>;
+/**
+ * REFACTOR Phase: Improve code while keeping tests green
+ *
+ * Improves code quality without changing behavior.
+ * All tests must remain passing after each change.
+ */
+export declare function executeRefactorPhase(story: Story, cycleNumber: number, testFile: string, options: TDDPhaseOptions): Promise<TDDPhaseResult>;
+/**
+ * Record a completed TDD cycle to the story frontmatter
+ */
+export declare function recordTDDCycle(cycleNumber: number, redResult: TDDPhaseResult, greenResult: TDDPhaseResult, refactorResult: TDDPhaseResult): TDDTestCycle;
+/**
+ * Check if all acceptance criteria have been covered (checked off)
+ */
+export declare function checkACCoverage(story: Story): boolean;
+/**
+ * Run the full TDD implementation loop
+ *
+ * Executes Red-Green-Refactor cycles until all acceptance criteria are covered
+ * or the maximum number of cycles is reached.
+ */
+export declare function runTDDImplementation(story: Story, sdlcRoot: string, options?: TDDImplementationOptions): Promise<AgentResult>;
 /**
  * Implementation Agent
  *

package/dist/agents/implementation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"implementation.d.ts","sourceRoot":"","sources":["../../src/agents/implementation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAS,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAgBtC;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA4GtB"}
+{"version":3,"file":"implementation.d.ts","sourceRoot":"","sources":["../../src/agents/implementation.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,YAAY,EAAa,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAI7C,YAAY,EAAE,qBAAqB,EAAE,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,aAAa,CAAC;IACrC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,aAAa,CAAC,EAAE,OAAO,aAAa,CAAC;IACrC,aAAa,CAAC,EAAE,OAAO,aAAa,CAAC;IACrC,WAAW,CAAC,EAAE,OAAO,WAAW,CAAC;IACjC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CACpC;AAED,eAAO,MAAM,iBAAiB,8zBAuB+B,CAAC;AAgB9D;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAgD9C;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAgD9C;AAmDD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAoCzB;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAwCzB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,cAAc,EACzB,WAAW,EAAE,cAAc,EAC3B,cAAc,EAAE,cAAc,GAC7B,YAAY,CAYd;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAuBrD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,WAAW,CAAC,CA2HtB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAgJtB"}