CLAUDE.md — agent-revamp-skills

This file is loaded automatically by Claude Code at the start of every session in this repo. It defines the project's purpose, operating rules, and constraints that all agents and skills must follow.

Project Context

agent-revamp-skills is a library of Claude Code skills (prompt-driven slash commands) and sub-agent definitions for driving large-scale, incremental codebase migrations — the kind that take weeks or months, cross team boundaries, and carry real production risk.

The skills are organized into eight ordered phases that mirror a typical strangler-fig migration:

Skill Anatomy Rules

Every skill in skills/ must contain all nine required sections in order. See skills/_template/SKILL.md for the canonical template.

Required sections (in order):

1. # Metadata — name, phase, version, owner
2. # Purpose — one-paragraph plain-English summary
3. # Trigger Conditions — when to use this skill (and when NOT to)
4. # Inputs — required and optional context the skill needs
5. # Steps — numbered, ordered, imperative instructions to Claude
6. # Agent Handoffs — which sub-agents to spawn, and with what prompts
7. # Outputs — artifacts produced (files, reports, PRs, etc.)
8. # Validation Gates — criteria that must pass before declaring the skill done
9. # References — links to patterns, anti-patterns, or related skills

Rules:

• A skill must be self-contained enough that a cold Claude session can execute it.
• Steps must be imperative ("Read X", "Search for Y") — not descriptive ("X should be read").
• Agent Handoffs must name the agent file in agents/ and pass a complete prompt template.
• Validation Gates are non-negotiable checklists — do not mark a skill complete unless every gate passes.

Core Constraints

These constraints apply to all sessions, agents, and skills in this repo:

Safety

• Never run a migration step against a production system without an explicit --env prod flag confirmed by the user in the current session.
• Never delete source code that is still referenced. Run equivalence validation first.
• All destructive operations (schema drops, service deletions, traffic cuts) require a dry-run output reviewed by the user before execution.

Scope

• Skills must focus on their declared phase. Cross-phase work belongs in a new skill.
• Do not add features, documentation, or refactors that weren't asked for.
• Do not create files outside the repo structure without asking.

Agent Behavior

• Sub-agents operate in read-only mode by default unless the parent skill explicitly grants write access.
• Agents must cite the file path and line number for every claim about existing code.
• If an agent cannot find evidence for an assumption, it must say so rather than guess.

Output Quality

• All generated artifacts (specs, plans, diffs) must be written to a file, not only printed to stdout.
• Reports must include a confidence level (High / Medium / Low) and a list of assumptions made.

Session Startup

At the start of every session in this repo, before taking any action or responding to any request, Claude Code must:

1. Check for AUDIT.md at the repo root. If it exists, read it fully before proceeding. AUDIT.md is the ground truth about the codebase being migrated. Any recommendation made without reading it may contradict findings already established. If AUDIT.md is present but its Sign-off status is PENDING, note this to the user before running any Phase 2 or later skill — Phase 2 requires sign-off.
2. Check for MIGRATION-PLAN.md at the repo root. If it exists, read it fully before proceeding. MIGRATION-PLAN.md defines the agreed sequencing, blocked units, and phase-gate criteria for this project. Any Phase 4 action that contradicts the plan's dependency ordering or skips a phase gate must be flagged to the user before executing.
3. Check for stale artifacts. If AUDIT.md exists and its audit date (the Audit date field in the header table) is more than 90 days before today's date, warn the user: "AUDIT.md is N days old. Dependency health, CVE status, and coverage data may have changed. Consider re-running codebase-audit before continuing."
4. Do not re-read these files on every tool call — read them once at session start and hold the findings in context. If the user explicitly updates AUDIT.md or MIGRATION-PLAN.md during the session, re-read the updated file before continuing.

If neither file exists: proceed normally. Their absence means the project is in Phase 0–1 and no prior audit or plan has been committed yet.

Quick Reference

# Run a skill as a slash command
/audit                  # Phase 1 — inventory and risk map
/revamp-spec            # Phase 2 — migration strategy doc
/migrate                # Phase 4 — execute a migration unit
/validate               # Phase 5 — equivalence check

See docs/claude-code-setup.md for first-time setup instructions. See docs/how-to-pick-a-skill.md to choose the right skill for your task. See CONTRIBUTING.md to add a new skill to the library.