# Build Contract: agentkit-cli v0.51.0 — `agentkit migrate`

**Date:** 2026-03-18
**Baseline:** v0.50.0 (2254 tests passing, PyPI live)
**Target version:** 0.51.0
**Repo:** ~/repos/agentkit-cli/
**Contract author:** Mordecai (build-loop)

---

## Objective

Add `agentkit migrate` — convert between AI agent context file formats:
- AGENTS.md ↔ CLAUDE.md ↔ llms.txt / llms-full.txt

Devs using multiple AI tools (Claude Code, Codex, Gemini CLI) each expect different formats. This command eliminates manual reformatting and keeps all formats in sync.

---

## Deliverables

### D1: Core `MigrateEngine` + format detection (≥15 tests)
- `agentkit_cli/migrate.py` with `MigrateEngine` class
- Supported conversions:
  - `agents-md → claude-md`: transform AGENTS.md to CLAUDE.md format
  - `claude-md → agents-md`: transform CLAUDE.md to AGENTS.md format
  - `agents-md → llmstxt`: generate llms.txt from AGENTS.md
  - `claude-md → llmstxt`: generate llms.txt from CLAUDE.md
  - `llmstxt → claude-md`: extract CLAUDE.md from llms.txt
  - `all`: generate all formats from whichever source is present
- Auto-detect source format if not specified
- Preserve all substantive content; only change structure/headers/format
- Add a `<!-- generated by agentkit migrate -->` comment to outputs so staleness checkers can flag drift

### D2: `agentkit migrate` CLI command (≥12 tests)
- `agentkit migrate [--from FORMAT] [--to FORMAT] [--all] [--dry-run] [--diff] [--output PATH] [--force] [PATH]`
- `--from`: source format (agents-md, claude-md, llmstxt, auto). Default: auto-detect
- `--to`: target format (agents-md, claude-md, llmstxt, all). Default: all
- `--all`: equivalent to `--to all`
- `--dry-run`: print what would be written without writing
- `--diff`: show before/after diff of each file
- `--output PATH`: write to specific file instead of default path
- `--force`: overwrite existing files (default: prompt if file exists)
- PATH: project directory (default: `.`)
- Rich output: summary table showing source, targets written, line counts
- Exit 0 on success, exit 1 on format detection failure

### D3: `agentkit sync` command — keep formats in sync (≥10 tests)
- `agentkit sync [--check] [--fix] [PATH]`
- `--check`: report which derived format files are out of sync with the source (exit 1 if stale)
- `--fix`: re-run migrate to bring all derived files in sync
- Staleness detection: compare content hash of source vs derived file's generation comment timestamp
- Integrate into `agentkit doctor` as a new check: "Context formats in sync"

### D4: Integration into existing commands (≥8 tests)
- `agentkit run --migrate`: auto-generate missing format files before analysis
- `agentkit llmstxt --sync-from agents-md|claude-md`: generate llms.txt from existing context file
- `agentkit doctor` check: "context-sync" — warns if multiple format files exist but are out of sync

### D5: Docs, tests, version bump, BUILD-REPORT (≥5 tests)
- Update README.md: add `agentkit migrate` section with format matrix table
- CHANGELOG.md: v0.51.0 entry
- pyproject.toml: version = "0.51.0"
- `agentkit_cli/__init__.py`: version = "0.51.0"
- BUILD-REPORT.md: all deliverables status

---

## Test Targets

- Baseline: 2254 tests
- Target: ≥2304 tests (≥50 new)
- All existing tests must still pass (zero regressions)

---

## Quality Gates

- `python3 -m pytest -q` must pass 100% before committing
- All new code must be type-hinted
- `agentkit migrate --all` must successfully convert agentkit-cli's own CLAUDE.md to all formats
- `agentkit sync --check` must exit 0 on a freshly migrated project

---

## Commit & Tag Instructions

After all tests pass:
1. `git add -A && git commit -m "feat: agentkit migrate — convert between AGENTS.md/CLAUDE.md/llms.txt formats (v0.51.0)"`
2. **DO NOT push to GitHub** — build-loop handles push + tag + PyPI publish
3. Write BUILD-REPORT.md listing each deliverable status

---

## Stop Conditions

- Stop if test count drops below baseline (2254)
- Stop if any deliverable would require browser automation or external API access beyond GitHub
- Do not publish to PyPI (build-loop does this)
- Do not create new GitHub repos or modify any repo other than agentkit-cli
- Max scope: agentkit_cli/ directory + tests/ directory only

---

## Context

- Repo: ~/repos/agentkit-cli/
- CLAUDE.md: already generated and present in repo root
- AGENTS.md: present in repo root
- llms.txt / llms-full.txt: generated by `agentkit llmstxt` (just shipped in v0.50.0)
- The migrate command should read from `agentkit_cli/llmstxt.py` (LlmsTxtGenerator) for the llmstxt generation path — don't reimplement, reuse
- Format differences:
  - AGENTS.md: more operational, uses ## sections for rules/constraints/identity
  - CLAUDE.md: project-focused, ## sections for overview/stack/commands/patterns
  - llms.txt: structured title + summary + URL links per llmstxt.org spec
