TDD Migrate

Orchestrate TDD migrations with agents doing all work. Main context stays clean.

When to Use

• "Port X from Python to TypeScript"

• "Create N adapters following existing pattern"

• "Migrate module to new architecture"

• "TDD implementation of multiple similar items"

Parameters

/tdd-migrate <source_path> <target_path> --pattern <reference> --items "item1,item2,item3"

• source_path : Path to analyze (existing code)

• target_path : Where to create new code

• pattern : Reference file/pattern to follow

• items : Comma-separated list of things to create

Workflow

Phase 0: YAML TODO List │ ▼ Phase 1: TLDR Analysis ─────────────────┐ │ │ ▼ │ Parallel scouts Phase 2: Write Failing Tests ───────────┤ per item │ │ ▼ │ Phase 3: Implement (minimal) ───────────┤ │ │ ▼ │ Phase 4: Build + Pass Tests ────────────┘ │ ▼ Phase 5: QLTY Check ────────────────────┐ │ │ Parallel Phase 6: Review Agent Validates ────────┘ │ ▼ Phase 7: TLDR Diff (new vs reference) │ ▼ Phase 8: Fix Issues (if any) │ ▼ Complete

Key Principles

Main context = orchestration only

• Never read files directly (use scout)

• Never implement directly (use kraken/spark)

• Never run tests directly (use validator)

• Only pipe context and coordinate

Agents do ALL work

Task Agent

Explore/analyze scout

Write tests + implement kraken

Quick fixes spark

Run tests/validate validator

Code review critic

Parallel where independent

• All items can be implemented in parallel if independent

• Review + QLTY run in parallel

• TLDR analysis runs in parallel with planning

Review after each major step

• After implementation: critic reviews

• After fixes: validator re-validates

Instructions

Step 0: Create YAML TODO

Write a YAML plan file to thoughts/shared/plans/<name>-tdd.yaml :

title: <Migration Name> date: <today> type: implementation-plan approach: TDD (test → build → pass → review)

items:

• name: item1 file: <target_path>/item1.ts test: <target_path>/tests/item1.test.ts deps: []
• name: item2

  ...

reference: <pattern_file>

workflow: per_item: 1: Write failing test 2: Implement minimal 3: Build 4: Pass test 5: QLTY check 6: Review final: 7: Integration test 8: TLDR diff

Step 1: Launch Scout Agents (parallel)

Task (scout): Analyze <source_path> with TLDR Task (scout): Analyze <pattern> to understand structure Task (scout): Read migration handoff if exists

Step 2: Launch Kraken Agents (parallel per item)

For each item, launch ONE kraken that does full TDD:

Task (kraken): Implement <item> using TDD workflow

1. Read pattern file
2. Write failing test
3. Implement
4. Run: bun test <test_file>
5. Run: qlty check <impl_file>

Step 3: Review + Validate (parallel)

Task (critic): Review all new files against pattern Task (validator): Run full test suite Task (validator): QLTY check all files

Step 4: Fix Issues

If critic/validator found issues:

Task (spark): Fix <specific issue> Task (validator): Re-validate

Step 5: TLDR Diff

Task (validator): TLDR diff new files vs reference

• tldr structure <new_file> --lang <lang>
• tldr structure <reference> --lang <lang>
• Compare patterns

Step 6: Update Continuity

Update ledger with completed work.

Example: Rigg Adapters

/tdd-migrate /Users/cosimo/Documents/rigg/src/sdk/providers
/Users/cosimo/Documents/rigg/src/sdk/providers
--pattern lmstudio.ts
--items "xai,cerebras,togetherai,deepinfra,perplexity"

Resulted in:

• 5 parallel kraken agents

• 39 tests passing

• All adapters working

• ~15 minutes total

Anti-Patterns (AVOID)

Bad Good

Read files in main context Launch scout agent

Write code in main context Launch kraken/spark agent

Run tests in main context Launch validator agent

Skip review Always launch critic

Sequential items Parallel krakens

Fix in main context Launch spark

Agent Prompts

Scout (analysis)

Explore <path> to understand:

1. Structure/patterns
2. Interfaces/types
3. Dependencies Return actionable summary for implementation.

Kraken (TDD)

Implement <item> using TDD:

1. Read <pattern> for structure
2. Write failing test to <test_path>
3. Implement minimal to <impl_path>
4. Run: <test_command>
5. Run: qlty check <impl_path> Report: status, issues, files created.

Critic (review)

Review <files> against <pattern>:

1. Pattern compliance
2. Type safety
3. Missing registrations
4. Security issues DO NOT edit. Report issues only.

Spark (fix)

Fix <specific issue>:

1. Read <file>
2. Make minimal edit
3. Verify fix

Validator (test)

Validate <files>:

1. Run <test_command>
2. Run qlty check
3. Report pass/fail/issues

Success Criteria

• All tests pass

• QLTY reports no issues

• Critic found no critical issues

• TLDR diff shows pattern compliance

• All items registered/exported properly