Skip to main content

/qa-tdd-orchestrate

Orchestrate RED/GREEN/REFACTOR TDD cycle with context-isolated agents for test-first development.

Overview​

Runs a full TDD cycle using three context-isolated AI agents (RED, GREEN, REFACTOR) that communicate only through artifacts -- never through shared reasoning. Supports a double-loop pattern: outer BDD acceptance tests from /qa-test-cases, inner unit TDD cycles per component. Context isolation is the core architectural principle, enforced at three levels.

Claude Code only -- requires Task tool for sub-agent spawning. Not available in Codex runtime.

Usage​

/qa-tdd-orchestrate "implement user login with rate limiting"
/qa-tdd-orchestrate path/to/qa-test-cases-output
ArgumentRequiredDescription
feature sourceNoFeature description, acceptance criteria, or qa-test-cases output path

When run without arguments, launches an interactive wizard.

What It Produces​

Files at $JAAN_OUTPUTS_DIR/qa/tdd-orchestrate/{id}-{slug}/:

FileContent
{id}-{slug}.mdTDD orchestration report with cycle history and results
orchestration-log.jsonFull cycle-by-cycle history with timestamps and phase gates
handoff-red.jsonRED phase manifest (test file path, runner output)
handoff-green.jsonGREEN phase manifest (implementation files, test results)

What It Asks​

QuestionWhenWhy
Test frameworktech.md unavailableDetermines test runner and assertion library
Component decompositionAlwaysApprove how feature is broken into TDD-able units
Cycle limitsCustom neededMax RED-GREEN cycles per component

Context Isolation (Three Levels)​

The core research premise: AI agents writing tests must not see implementation plans, and agents writing implementation must not see test reasoning.

LevelMechanismWhat It Prevents
1. Artifact-only handoffsNo reasoning text between agentsGREEN agent "cheating" by reading RED's intent
2. Prompt exclusion listsEach agent explicitly excludes other phasesCross-contamination of concerns
3. Handoff manifest verificationPhase gate JSON lists only allowed pathsAny non-manifest content = isolation violation

Double-Loop TDD​

Outer Loop (BDD Acceptance)
  AC1 → Inner TDD Cycles → AC1 PASS
  AC2 → Inner TDD Cycles → AC2 PASS

Inner Loop (per component)
  RED → write failing test
  GREEN → minimal code to pass
  REFACTOR → improve without breaking tests

Workflow Chain​

/qa-test-cases --> /qa-tdd-orchestrate --> /qa-test-mutate

Example​

Input:

/qa-tdd-orchestrate "implement user login with rate limiting"

Output:

jaan-to/outputs/qa/tdd-orchestrate/01-user-login/
├── 01-user-login.md             (orchestration report)
├── orchestration-log.json        (full cycle history)
├── handoff-red.json              (RED phase manifest)
└── handoff-green.json            (GREEN phase manifest)

Report summary:

Components:   3 (authenticate, rate-limiter, session-manager)
Total Cycles: 8 RED-GREEN-REFACTOR
Tests Written: 24
Tests Passing: 24/24
Acceptance Criteria: 3/3 satisfied

Tips​

  • Start with acceptance criteria from /qa-test-cases for the outer loop
  • Review the component decomposition before approving -- smaller components = better TDD
  • If a test fails 3 times with the same error, the skill escalates to you
  • Follow up with /qa-test-mutate to validate test effectiveness

Technical Details​

  • Logical Name: qa-tdd-orchestrate
  • Command: /qa-tdd-orchestrate
  • Role: qa
  • Output: $JAAN_OUTPUTS_DIR/qa/tdd-orchestrate/{id}-{slug}/
  • Runtime: Claude Code only (codex-support: false)
  • Reference: docs/extending/qa-tdd-orchestrate-reference.md