tdd-migration-pipeline

• Migrating codebase from one language/framework to another
• Rewriting a system with TDD guarantees
• Large-scale refactoring with behavioral contracts
• When you want zero context growth in the orchestrator

1. ZERO orchestrator execution - only instruct and pipe context
2. All work done by agents - you never read/write/validate
3. Context window stays flat - pass paths, not contents
4. New code in separate directory - never modify source

• Never say "let me read..." or "looking at..."
• Only say "Agent X: do Y with Z"
• Your context should NOT grow during execution
• All agents must use qlty and tldr skills

Phase 1: SPEC

```

Instruct spec-agent (use scout or architect):

• Analyze {source_path} using tldr-skill
• Output: spec.md with behavioral contracts, types, edge cases

```

Agent prompt template:

```

Analyze the codebase at {source_path} using tldr commands (tldr structure, tldr extract, tldr calls).

Create spec.md with:

• All behavioral contracts (what each function/class promises)
• Input/output types
• Edge cases and invariants
• Dependencies between components

Write to: {target_dir}/spec.md

```

Phase 2: FAILING TESTS

```

Instruct test-agent (use arbiter):

• Read spec.md
• Write failing tests in {target_dir}/tests/
• Tests should define expected behavior before implementation

Instruct review-agent (use critic):

• Validate tests cover spec completely
• No gaps in behavioral coverage

```

Phase 3: ADVERSARIAL (x3 iterations)

```

Instruct premortem-agent (use premortem skill):

• Review spec + tests
• Identify failure modes, race conditions, edge cases
• DO NOT ASK - just add mitigations directly to spec
• Run 3 passes with fresh perspective each time

```

Key: Each pass should find NEW issues, not repeat previous ones.

Phase 4: PHASED PLAN

```

Instruct planner-agent (use architect or plan-agent):

• Input: spec.md + tests + mitigations
• Output: phased-plan.yaml
• Requirements:

- Dependency-ordered phases

- Each phase = one testable unit

- Clear inputs/outputs per phase

```

Phase 5: BUILD LOOP (per phase)

```

For each phase in phased-plan.yaml:

Instruct builder-agent (use kraken or spark):

- Write code to pass tests for this phase

- Use qlty for quality checks

- Run tests after each change

Instruct review-agent (use critic or judge):

- Validate implementation matches spec

- Check for regressions in previous phases

- Verify no breaking changes

```

Phase 6: INTEGRATION VALIDATION

```

Instruct integration-agent (use atlas or validator):

• Use tldr to diff against {reference_repo}
• Check for:

- No race conditions

- No hangs or deadlocks

- No breaking changes vs original

- All behavioral contracts preserved

• Output: validation-report.md

```

When invoking this workflow, specify:

```yaml

SOURCE: {path to source code}

TARGET_DIR: {new folder for migrated code}

TARGET_LANG: {typescript|python|go|rust|etc}

REFERENCE_REPO: {url or path for final diff comparison}

SKILLS: [tldr-code, qlty-check, {domain-specific}]

```

| Phase | Agent Type | Subagent |

|-------|-----------|----------|

| Spec | research | scout or architect |

| Tests | validate | arbiter |

| Review | review | critic or judge |

| Premortem | review | premortem skill |

| Plan | plan | architect or plan-agent |

| Build | implement | kraken (large) or spark (small) |

| Integration | validate | atlas or validator |

```

# Phase 1

Task(scout): "Analyze /src/old-system using tldr structure and tldr extract.

Create spec.md at /migration/spec.md with all behavioral contracts."

# Phase 2

Task(arbiter): "Read /migration/spec.md. Write failing tests to /migration/tests/

that define expected behavior."

Task(critic): "Review /migration/spec.md vs /migration/tests/.

Report any behavioral gaps."

# Phase 3 (x3)

Task(premortem): "Review /migration/spec.md and /migration/tests/.

Identify failure modes. Add mitigations directly to spec. Pass 1/3."

[repeat with "Pass 2/3", "Pass 3/3"]

# Phase 4

Task(architect): "From /migration/spec.md and /migration/tests/,

create /migration/phased-plan.yaml with dependency-ordered phases."

# Phase 5 (loop)

Task(kraken): "Implement phase 1 from /migration/phased-plan.yaml.

Code goes in /migration/src/. Run tests after."

Task(critic): "Review /migration/src/ against /migration/spec.md.

Check for spec compliance and regressions."

[repeat for each phase]

# Phase 6

Task(atlas): "Run full integration tests on /migration/src/.

Use tldr to diff against /src/old-system.

Output /migration/validation-report.md."

```

• Reading files into your context ("let me check the code...")
• Writing code directly ("I'll implement this function...")
• Validating anything yourself ("looking at the tests, I see...")
• Modifying the source directory
• Skipping the adversarial phase
• Running build without tests first

• [ ] All tests pass
• [ ] qlty reports clean
• [ ] tldr diff shows no breaking changes
• [ ] No race conditions or hangs
• [ ] validation-report.md confirms behavioral equivalence