Agent-Driven TDD Workflow

Enforce Test-Driven Development for AI agents working with Elixium. This workflow ensures tests are written before implementation, with human checkpoints for review.

🧪 TDD with Human Checkpoints

Traditional TDD is "Red → Green → Refactor". With AI agents, we add human approval gates to ensure quality. Agents can't skip tests—the API enforces it.

📋 The 6-Step Workflow

Prepare — Agent reads story context via prepare_implementation
Start — Agent creates branch via start_story
Write Tests — Agent writes tests and calls propose_test_plan
Human Review — Approve test plan (UI or API)
Implement — Agent writes code to make tests pass
Human Review — Review diff, move to Done

🔄 Workflow Diagram

┌─────────────────────────────────────────────────────────────────┐
│  1. Agent: prepare_implementation(storyId)                      │
│     → Gets acceptance criteria, context, epic                   │
├─────────────────────────────────────────────────────────────────┤
│  2. Agent: start_story(storyId)                                 │
│     → Creates branch, workflow_stage = tdd_start                │
├─────────────────────────────────────────────────────────────────┤
│  3. Agent: Write tests, then call propose_test_plan()           │
│     → workflow_stage = tests_proposed                           │
│     🛑 BLOCKED until human approves                             │
├─────────────────────────────────────────────────────────────────┤
│  4. Human: Approve test plan (UI or API)                        │
│     → workflow_stage = tests_approved                           │
├─────────────────────────────────────────────────────────────────┤
│  5. Agent: Implement code, run tests until green                │
├─────────────────────────────────────────────────────────────────┤
│  6. Agent: submit_for_review(storyId, commitHash)               │
│     → workflow_stage = review, state = finished                 │
├─────────────────────────────────────────────────────────────────┤
│  7. Human: Review diff, run tests, move to Done                 │
└─────────────────────────────────────────────────────────────────┘

🛠️ MCP Tools Reference

start_story

Entry point for TDD workflow. Creates a git branch and sets workflow_stage.

Parameters:

{ storyId: string, branchPrefix?: "feat" | "fix" | "chore" }

Returns:

{
  "branch": "feat/abc123-my-feature",
  "workflow_stage": "tdd_start",
  "acceptance_criteria": "...",
  "workflow_reminder": "Write tests first..."
}

propose_test_plan

Submit test plan for human review. Blocks implementation until approved.

Parameters:

{ storyId: string, testPlan: string, testFilePaths?: string[] }

Returns:

{
  "workflow_stage": "tests_proposed",
  "message": "Test plan submitted. Awaiting human approval."
}

🛑 BLOCKED: Agent cannot call submit_for_review until tests are approved.

submit_for_review

Submit implementation for human review. Only works if tests are approved.

Parameters:

{ storyId: string, commitHash?: string, implementationNotes?: string }

Returns:

{
  "status": "ready_for_review",
  "workflow_stage": "review",
  "state": "finished",
  "next_step": "Human reviews diff and moves to Done"
}

📊 Workflow Stages

Stage	Description	Who Acts
`tdd_start`	Branch created, ready to write tests	Agent
`tests_proposed`	Tests written, awaiting approval	Human
`tests_approved`	Tests approved, implementation unlocked	Agent
`implementing`	Agent is writing code	Agent
`review`	Implementation complete, awaiting review	Human

🛑 Human Checkpoints

1. Test Plan Review

When workflow_stage = tests_proposed, review the test plan:

Are the tests comprehensive enough?
Do they cover the acceptance criteria?
Are edge cases considered?

To approve: Click "Approve Test Plan" in the story card, or call the API:

curl -X POST "https://elixium.ai/api/stories/:id/approve-tests" \ -H "x-api-key: YOUR_API_KEY" \ -H "x-board-slug: main" \ -H "Content-Type: application/json"

2. Implementation Review

When workflow_stage = review, review the implementation:

Review the git diff
Run tests locally
Check code quality and style

To complete: Move the story to the Done lane

💡 Best Practices

Writing Good Test Plans

Be specific: Name the test file paths and describe what each test covers
Reference AC: Map tests to acceptance criteria (Given/When/Then)
Include edge cases: Mention error handling, boundary conditions
Keep it readable: Use markdown formatting for clarity

Example Test Plan

## Test Plan: User Authentication

### Unit Tests (`tests/auth.spec.ts`)
- should hash password before storing
- should validate email format
- should reject weak passwords

### Integration Tests (`tests/auth-api.spec.ts`)
- POST /login should return 200 with valid credentials
- POST /login should return 401 with invalid password
- POST /login should rate-limit after 5 failures

### Edge Cases
- Empty email field
- SQL injection attempt
- Unicode characters in password

📦 Story Fields Reference

Field	Type	Description
`workflow_stage`	enum	Current TDD stage
`branch_name`	string	Git branch created for this story
`test_plan`	string	Markdown test plan proposed by agent
`test_file_paths`	string[]	Paths to created test files
`commit_hashes`	string[]	Commits linked to this story

🔧 Troubleshooting

"Cannot submit for review - tests must be approved first"

The agent tried to call submit_for_review before tests were approved. A human must approve the test plan first by clicking "Approve" in the story card or calling the API endpoint.

"Cannot start completed story"

The story is already in the Done lane. Create a new story or move it back to Current/Backlog first.

Agent keeps implementing without writing tests

The agent instructions may need updating. Add to your system prompt: "Always call start_story first, then write tests and call propose_test_plan before implementing."