tdd-migration-pipeline

TDD 迁移流水线

仅限编排的工作流，用于迁移或重写代码库。你不会自行读取文件、编写代码或验证任何内容。你只负责指示 Agent 并传递上下文（路径，而非内容）。

适用场景

• 将代码库从一种语言／框架迁移到另一种语言／框架
• 以 TDD 保证重写系统
• 具有行为契约的大规模重构
• 希望编排器的上下文零增长时

核心原则

1. 编排器零执行——只负责指示和传递上下文
2. 所有工作均由 Agent 完成——你绝不读取／编写／验证
3. 上下文窗口保持不变——传递路径，而非内容
4. 新代码放在单独目录中——绝不修改源代码

你的约束

• 绝不要说“让我读取……”或“我正在查看……”
• 只说“Agent X：使用 Z 执行 Y”
• 执行期间，你的上下文不应增长
• 所有 Agent 都必须使用 qlty 和 tldr 技能

流水线阶段

阶段 1：规格说明

Instruct spec-agent (use scout or architect):
- Analyze {source_path} using tldr-skill
- Output: spec.md with behavioral contracts, types, edge cases

Agent 提示词模板：

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

阶段 2：失败测试

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

阶段 3：对抗性审查（3 次迭代）

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

**要点：**每轮都应发现新的问题，而非重复之前的问题。

阶段 4：分阶段计划

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

阶段 5：构建循环（按阶段执行）

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

阶段 6：集成验证

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

调用

调用此工作流时，请指定：

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}]

Agent 对应关系

阶段	Agent 类型	子 Agent
规格说明	research	scout 或 architect
测试	validate	arbiter
审查	review	critic 或 judge
事前剖析	review	premortem skill
计划	plan	architect 或 plan-agent
构建	implement	kraken（大型）或 spark（小型）
集成	validate	atlas 或 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."

反模式（请勿执行）

• 将文件读入你的上下文（“让我检查一下代码……”）
• 直接编写代码（“我来实现这个函数……”）
• 自行验证任何内容（“我看了测试，发现……”）
• 修改源目录
• 跳过对抗性审查阶段
• 未先编写测试就运行构建

成功标准

• 所有测试均通过
• qlty 报告无问题
• tldr diff 显示没有破坏性变更
• 没有竞态条件或挂起
• validation-report.md 确认行为等效