# Migration Playbook

This playbook is for adopting the template in an existing repository.

The bootstrap script is greenfield-first. Do not run it directly on top of an established project unless overwriting starter files is acceptable.

## Recommended Path

1. Create a temporary copy from this template.
2. Bootstrap the closest profile.
3. Compare the generated contract against the existing repository.
4. Port the durable parts manually.
5. Replace template verification with project-native checks.
6. Run the existing repository test suite.

Before editing, check the target repository git state. If the repository is dirty or in detached HEAD, preserve the existing changes and create a named branch before committing adoption work.

## Files To Port First

Start with:

- `AGENTS.md`
- `.codex/config.toml`
- `.codex/hooks.json`
- `.codex/hooks/`
- `.codex/agents/`
- `.agents/skills/`

Then decide whether supporting docs and optional adapters are useful.

Review `.codex/hooks/user_prompt_submit_context.py` after copying. The prompt-context hook should describe the target project, not the template repository.

## Existing README

Do not overwrite a mature README blindly.

Instead:

- keep product, install, and user-facing documentation
- add a short agent contract section
- link to `AGENTS.md`
- move template-maintenance language out unless this repository remains a template

## Existing CI

Keep project-native CI as the source of truth.

Use template checks only for the adopted agent contract:

- `.codex/` parses
- skills have valid frontmatter
- forbidden paths and retired surfaces stay absent
- local adapter settings remain ignored

Prefer adding a small project-local verifier, such as `scripts/verify-agent-contract.sh`, instead of reusing `scripts/verify-template.sh` from this repository.

## Existing Generated Artifacts

Separate two concerns:

- add ignore rules that prevent future machine-local artifacts from being committed
- remove already tracked generated artifacts only in a separate, reviewable cleanup change

Common adoption findings include supervisor state, coverage reports, local databases, build outputs, and tool caches.

## Existing Vendor Adapters

Treat each adapter as optional.

If a repository already has Claude, Cursor, or other agent-specific files:

- keep the shared rules in `AGENTS.md`
- make vendor files defer to the shared contract
- avoid duplicating safety rules without a verification path

## Rollout Sequence

For production repositories, adopt in stages:

1. documentation-only contract
2. native Codex config and subagents
3. safety hooks in audit mode where needed
4. blocking hooks for high-confidence policies
5. project-native verification in CI

## Stop Conditions

Pause migration when:

- the current repo has unclear ownership boundaries
- existing CI is red for unrelated reasons
- security policy cannot be safely translated
- bootstrap output would overwrite important project docs