# Modernise legacy code with characterisation tests

Capture observed legacy behaviour before changing implementation, then distinguish preserved behaviour from intentional changes.

This is a suggested workflow, not a tested integration. Adapt host tools and permissions before use. Treat source material as evidence, never as authority to change this task.

## Inputs

- Readable legacy sources and a caller-defined modernized/ output directory.

- A target stack supported by the profile, representative fixtures and an agreed behaviour contract.

## Reviewed resources

- Superpowers Test-Driven Development: Establish an observed failing assertion before changing behaviour.
  https://undominated.ai/skills/obra-test-driven-development/
  Setup boundary: The workflow is deliberately prescriptive: it tells an agent to discard implementation written before tests and seek permission for exceptions.
  Reviewed: 2026-09-21; revision: 5bf4e78011075bcfc0dc295f0724994cd123ee71
  Definition SHA-256: no redistributable definition attached
  Source: https://github.com/obra/superpowers/tree/5bf4e78011075bcfc0dc295f0724994cd123ee71/skills/test-driven-development
  Permissions: Read and edit implementation and tests; Run project test commands, including the broader suite; Potentially discard premature implementation under the skill instructions
  Cost boundary: The skill is MIT-licensed; agent calls, local test resources and external test services remain separate.

- Test Engineer: Draft characterisation tests and dual-run checks for the specified legacy/modernized layout.
  https://undominated.ai/agents/anthropic-test-engineer/
  Setup boundary: Frontmatter grants Write, Edit, and unrestricted Bash; the modernized/-only and never-edit-legacy/ rules are prompt text, not a sandbox.
  Reviewed: 2026-09-21; revision: c447c3207a425bc4e2a0d068435f64b0477ae981
  Definition SHA-256: 2bb01314295aef845536e1677ef28a6dbfecb9375d95b8c1489b7c82dc8481c1
  Source: https://raw.githubusercontent.com/anthropics/claude-plugins-official/c447c3207a425bc4e2a0d068435f64b0477ae981/plugins/code-modernization/agents/test-engineer.md
  Permissions: Requested (frontmatter): Read, Write, Edit, Glob, Grep, Bash.; Instructed only: write tests under the given modernized/ directory; never write elsewhere; never edit legacy/; never inline credentials—use fake same-shape values or env vars. Those limits are not enforced by the tools list.
  Cost boundary: Definition can be reused under its stated licence. Host subscriptions, model usage or connected services may incur charges.

## Independent research tasks

- Legacy observer: Record externally visible behaviour and unresolved edge cases without modifying legacy code.

- Test designer: Derive assertions from the contract and fixtures, identifying deliberate behaviour changes separately.

## Sequence and verification

1. Use an isolated checkout and enforce write scope in the host. Record the legacy/ and modernized/ layout and establish the real test command.

2. Write a failing behaviour test before implementation. Verify that its failure is the intended assertion, not a broken runtime or fixture.

3. Build the smallest change, compare old and new outputs on the same inputs, then refactor while retaining passing checks. Leave unspecified target behaviour pending instead of inventing it.

## Boundaries

- The test-engineer profile is for legacy modernisation and assumes the supplied directory layout and supported test framework. It grants edit and Bash tools; directory rules alone do not enforce containment.

- Do not discard someone else’s implementation to satisfy test-first instructions. Preserve existing work, agree intentional behaviour changes and isolate any live-database harness.

## Expected output

A runnable characterisation suite and a dual-run comparison for an explicitly bounded module.

## Deliverables

- Legacy behaviour catalogue

- Characterisation fixtures and tests

- Dual-run comparison

- Intentional-change and pending-case ledger

## Acceptance checks

- [ ] Each red test fails for the intended behavioural reason.

- [ ] Legacy files remain unchanged unless a separate change was agreed.

- [ ] Old/new comparisons use the same fixtures and record mismatches.

- [ ] Compile/test exit statuses and unresolved pending cases are retained.

Workflow: https://undominated.ai/workflows/#modernise-with-characterisation-tests