agent-revamp-skills

Structured, agent-driven skills for incremental, production-safe codebase migrations.

A library of Claude Code slash commands, sub-agent definitions, and reference patterns for teams running large-scale migrations — monolith splits, framework swaps, language ports, or infrastructure overhauls — using the strangler-fig approach.

---

Philosophy

Migrations fail not from bad code but from missing contracts, untested assumptions, and switches that happen all at once. The code you are migrating works — that is the uncomfortable truth. It is tangled and undocumented and nobody fully understands it, but it handles the edge cases that production traffic has hammered into it over years. When a migration fails, it is almost never because the new technology was wrong; it is because the team did not know what the old system was actually doing, did not have tests that would have caught the difference, and tried to switch everything at the same moment the new system first met real users. This library is built on three convictions that follow from that: you cannot migrate what you have not inventoried, you cannot validate what you have not baselined, and you cannot safely cut over what you have not run in parallel. Every skill enforces one of those three convictions as a non-negotiable gate. The goal is not to make migrations fast — it is to make them boring.

---

Phase Table

#	Phase	Directory	What Happens
0	Meta	skills/00-meta/	Skill authoring, repo hygiene, template maintenance
1	Audit	skills/01-audit/	Inventory the current system, map dependencies, score risk
2	Strategize	skills/02-strategize/	Choose migration approach, define sequence, write the spec
3	Prepare	skills/03-prepare/	Scaffolding, CI gates, feature flags, dual-write infra
4	Migrate	skills/04-migrate/	Execute migration by layer (frontend / backend / DB / infra / auth)
5	Validate	skills/05-validate/	Behavioral equivalence, load tests, diff checks
6	Cut-over	skills/06-cut-over/	Traffic shifting, DNS, kill-switch
7	Stabilize	skills/07-stabilize/	Post-cut-over hardening, dead-code cleanup, retro

---

Skills Reference

Skill	Phase	Source Stack	Target Stack	Effort	Status
skill-linter	0	Any	Any	XS	📋 Planned
codebase-audit	1	Any	Any	M	✅ Complete
migration-strategy	2	Any	Any	M	✅ Complete
risk-assessment	2	Any	Any	M	✅ Complete
feature-flag-setup	3	Any	Any	S	📋 Planned
dual-write-infra	3	Any DB	Any DB	M	📋 Planned
test-coverage-baseline	3	Any	Any	M	✅ Complete
cra-to-vite	4	CRA · Webpack 5	Vite 5 · Vitest	L	✅ Complete
js-to-typescript	4	JavaScript ES2020+	TypeScript 5.x strict	M	✅ Complete
react-18-upgrade	4	React 17	React 18	M	📋 Planned
express-to-fastify	4	Express 4.x	Fastify 4.x	L	✅ Complete
orm-migration	4	Sequelize · TypeORM	Prisma	L	📋 Planned
schema-expand-contract	4	Any SQL DB	Any SQL DB	L	📋 Planned
session-to-jwt	4	Session-based auth	JWT	L	📋 Planned
behavioral-equivalence	5	Any	Any	L	✅ Complete
traffic-cutover	6	Any	Any	M	📋 Planned
dead-code-cleanup	7	Any	Any	S	📋 Planned

---

Quick Start

Prerequisites

• Claude Code CLI installed and authenticated
• This repo cloned locally and set as the working directory

Setup

git clone https://github.com/your-org/agent-revamp-skills.git
cd agent-revamp-skills
# Claude Code will auto-load CLAUDE.md on first run
claude

Running a skill

The skills in this library run against your target codebase, not this repo. Point Claude Code at your project, then invoke commands from here.

# Option A — run from your project with this library's commands symlinked
cd /path/to/your-project
ln -s /path/to/agent-revamp-skills/.claude .claude
claude

# Option B — run from this repo and pass your project's path as --target
cd /path/to/agent-revamp-skills
claude
/audit --target /path/to/your-project

End-to-end example: auditing and migrating a CRA app to Vite

This is what a complete session looks like. Steps 1–3 are mandatory before anything else.

Step 1 — Audit the codebase (Phase 1)

/audit --target /path/to/my-cra-app --stakeholders "@alice, @bob"

Claude reads the codebase, runs dependency/CVE/dead-code/coupling tools, and writes AUDIT.md to the repo root. Review the risk register in §8 and get sign-off before proceeding.

Step 2 — Establish test coverage baselines (Phase 3)

For any module below 70% line coverage flagged in AUDIT.md §4.2:

/migrate --unit src/utils --layer frontend/js-to-typescript

Wait — this command will detect the coverage gap and invoke test-coverage-baseline automatically before proceeding. Or run it explicitly:

"Run skills/03-prepare/test-coverage-baseline/SKILL.md for src/services/auth"

Step 3 — Migrate one unit (Phase 4)

/migrate --unit src/App --layer frontend/cra-to-vite --env dev

Claude reads skills/04-migrate/frontend/cra-to-vite/SKILL.md, runs the pre-migrate hook, installs Vite alongside CRA (strangler-fig — both build tools coexist), renames env vars, ports the test suite to Vitest, and writes a migration log.

Step 4 — Validate equivalence (Phase 5)

/validate --unit src/App --env staging

Claude reads skills/05-validate/behavioral-equivalence/SKILL.md, selects the applicable techniques (contract snapshots + Lighthouse for a frontend unit), runs them, and writes VALIDATION-REPORT.md. The verdict must be PASS before cut-over.

What you get at the end of each step:

Step	Output file	What it proves
/audit	AUDIT.md	Ground truth before any change
coverage baseline	coverage/baseline-*.json	Regression detection is possible
/migrate	output/migrate-*.md	What changed and why
/validate	VALIDATION-REPORT.md	New stack matches old stack behavior

See docs/claude-code-setup.md for full setup instructions. See docs/how-to-pick-a-skill.md to choose the right skill for your situation.

---

Repository Layout

agent-revamp-skills/
├── CLAUDE.md                    # Auto-loaded by Claude Code — constraints and rules
├── CONTRIBUTING.md              # How to add a new skill
├── skills/
│   ├── _template/SKILL.md       # Blank skill template (9 required sections)
│   ├── 00-meta/
│   ├── 01-audit/
│   ├── 02-strategize/
│   ├── 03-prepare/
│   ├── 04-migrate/
│   │   ├── frontend/
│   │   ├── backend/
│   │   ├── database/
│   │   ├── infra/
│   │   └── auth/
│   ├── 05-validate/
│   ├── 06-cut-over/
│   └── 07-stabilize/
├── agents/                      # Sub-agent definitions
│   ├── migration-planner.md
│   ├── code-archaeologist.md
│   └── equivalence-validator.md
├── .claude/commands/            # Slash command entry points
│   ├── audit.md
│   ├── revamp-spec.md
│   ├── migrate.md
│   └── validate.md
├── hooks/                       # Pre/post execution hooks
│   ├── pre-migrate.sh
│   └── post-migrate.sh
├── references/                  # Background reading and decision frameworks
│   ├── strangler-fig-pattern.md
│   ├── migration-anti-patterns.md
│   └── stack-compatibility-matrix.md
└── docs/
    ├── skill-anatomy.md
    ├── how-to-pick-a-skill.md
    └── claude-code-setup.md

---

License

MIT — see LICENSE.