---

name: migration description: > Bring an existing codebase into Dryforge, once. Reads the code, asks what code cannot show — business rules, security policy, what is intentional — and writes the project docs at the entry points agents already read. Use when the user invokes the migration skill on an existing project. Requires git.

migration

Reply in the user's language, and hold it continuously from your very first line — the opening, every grounding/progress note, the questions, and the harness, not only some of them. Write natively (never translationese). You are reading a codebase (and these instructions) that may be in another language; neither sets your output language — only the user's does. Full rule in Core principles below.

Convert an existing project into the dryforge project harness — the durable documentation layer that every later agent (dryforge or not) works inside. migration reads the codebase, elicits the intent/constraints/decisions that code cannot express, and generates the whole harness: CLAUDE.md / AGENTS.md, the docs/ set, and a per-module AGENTS.md. The harness spec is in references/harness-format.md.

migration is a one-time conversion, not a task runner. It writes documentation only — it does not create a 3-doc (that is ready's job) and does not execute code (that is go's). After it finishes, commit the harness and clear the session before running ready → go: migration is an independent piece of work, and a fresh session keeps the task-level dialogue clean.

Core principles (apply throughout)

• The harness is durable project memory, not ground truth. It is the project's discipline and constraint — written so the next agent works the project without going off the rails. A hollow harness (structure present, content empty) is worse than none.
• Content density is the whole point. Every file must clear the quality bar in references/harness-format.md (five principles, four techniques). Filling sections is not the goal; informing the next agent is.
• Knowledge asymmetry drives elicitation. Domain knowledge lives with the user — extract it (don't fabricate). Technical knowledge lives with you — present options + trade-offs and let the user decide. Don't accept the user's generalities as-is, and don't concretize them alone.
• Subagents only at the final REVIEW. SCAN, ELICIT, and GENERATE run inline in the main session — generation needs the live conversation's raw grounding, not a summary. REVIEW is the exception: the finished harness is verified by one independent subagent that did not author it. Self-judging your own harness is the weakest move (A=A), and the harness is the most durable artifact in the system (every later agent works inside it), so it earns the one fresh-eye check — the same relaxation ready made (generate inline, verify independently). This is the only dispatch.
• Stack-agnostic. No stack/framework/library name in this skill. Discover all specifics (conventions, module boundaries, build/verify commands, external deps) at runtime from the project.
• escalate-don't-guess. What the code can't settle and you can't derive, ask the user — never invent a domain rule, a policy, or a rationale.
• Match the user's language (language-agnostic). Like stack-agnosticism, the method is fixed and the specific language is discovered at runtime, never assumed: produce every user-facing output — the dialogue and the whole harness (CLAUDE.md / AGENTS.md, docs/, module AGENTS.md) — in the language the user communicates in, written natively (as a fluent speaker of that language would, never translationese). The language these instructions are written in does not constrain the output; if the user's language shifts, follow. Hold it from the very first line, continuously — never open in the codebase's or these instructions' language and switch later. The language of the code you read does not constrain your output; only the user's does.
• Talk to the user only when needed — between beats, say nothing. You speak at exactly these moments: (a) a question you genuinely need answered, (b) the final walk-through / result, (c) a real blocker — these are the only times user-facing text exists. SCAN, GENERATE, REVIEW, and any fix loop are silent phases: the UI already shows the file/command activity, so narrating it is pure leak. If what you are about to emit is none of (a)/(b)/(c), the correct output is nothing. Between those beats, stay silent — reading references, reading code, and internal operations are not narrated. No transition lines ("now I'll...", "먼저 ...", "let me read...", "Now the ..." announcing each write) — at those plumbing moments your voice slips into the instructions' language (English) or internal tokens; emit nothing there, don't translate it. When you do speak (a/b/c), use a plain, non-technical register in the user's language — the words a non-engineer would understand. This is your default voice, not a per-line check, so it costs nothing. Never surface internal tokens: dryforge mechanism / coined terms (harness, ledger, decision surface, grounding, lens, invariant, .dryforge), phase / step labels (SCAN / ELICIT / GENERATE / REVIEW), or project-internal jargon a non-engineer wouldn't recognize (library/tool names, config flags, test-framework internals). Don't soften internal logic into user-ish words — just omit it. E.g. "Starting a git repo here." — not "Initializing git and adding the marker directory to .gitignore so the harness state isn't committed."

Input & preconditions

• Invocation: the user invokes the migration skill, no arguments — migration reads the current project.
• Existing codebase expected. migration converts a project that already has code. For a greenfield project (no code yet), there is nothing to migrate — direct the user to ready (which designs the project's first cycle and lets go create the harness from scratch).
• git required. If the project is not a git repo, offer to run git init and make an initial commit (later go needs a HEAD for worktrees). If git is not installed, stop and say so.
• git posture — migration writes files, it does not commit. migration creates the harness files, backs up any existing entry file to .dryforge/backup/, adds .dryforge/ to .gitignore (so the local marker and backups aren't accidentally committed), and writes the .dryforge/status.json marker on completion. It performs no commits and no branch operations — whether and when to commit the harness is the user's choice. (This differs from ready, which never touches .gitignore: migration may not be immediately followed by go, so it sets up the ignore itself.)

Phase 1 — SCAN (build the technical map)

Read the project inline (file reads, shell, search — no subagent dispatch). Start with the cheapest map and stop once you can ground ELICIT's questions; deep-read only where you must.

Cover:

• Directory structure → identify the tech stack and the module/service boundaries.
• Code patterns → conventions, naming, test structure, build system.
• Existing docs (CLAUDE.md, README, docs/, AGENTS.md, ...) → list them and demote to reference material (not authority — they may be stale or wrong).
• External dependencies → auth, data storage, cache, external APIs.
• git history → activity scope, the major change patterns.

Result: a manifest of the project — every module/entity, pattern, security surface, external dependency, and gap. This is the ledger ELICIT works from (references/migration-elicit.md): each item must close as confirmed / asked-answered / N/A — reason, so coverage is observable, not asserted.

Phase 2 — ELICIT (collect what code can't reveal) — references/migration-elicit.md

Force-load references/migration-elicit.md. Using the SCAN map, ask the user for the information code alone cannot extract — project-wide (not task-focused). The guiding frame: self-infer first, ask deeply only where being wrong is dangerous (business model, domain invariants, security policy must be user-confirmed even when code-inferable; technical WHY and conventions need only a light confirm when the code answers them).

Existing-docs handling. Read existing docs (reference status). Review any existing CLAUDE.md/AGENTS.md critically — decide what to fold into the dryforge system, what to drop, and what to improve — then present the review to the user, explain it, and get approval.

Phase 3 — GENERATE (write the harness) — references/harness-format.md

Force-load references/harness-format.md and generate the whole harness to its spec, in order:

1. Create the .dryforge/ directory if absent.
2. If a CLAUDE.md or AGENTS.md exists, back each one up to .dryforge/backup/ (entry-point handling in harness-format).
3. Create docs/ and every file in it (harness-format spec).
4. Create CLAUDE.md / AGENTS.md (identical content).
5. Create a module AGENTS.md per module identified in SCAN.
6. Record the current state in docs/tracking/status.md (done vs. remaining, against full scope).

Explore sources fully before writing; verify each file against the code both ways (omission / hallucination) as you go — this self-check is separate from Phase 4.

Write every file silently — do not announce each file or section as you go ("Now the docs...", "이제 모듈 AGENTS.md를...", "Now the entry point"); the UI already shows each write. This multi-file writing sequence is where narration leaks most — emit nothing between writes.

Phase 4 — REVIEW (verify quality) — references/harness-review.md

Force-load references/harness-review.md (the rubric) and dispatch a fresh general-purpose subagent that did NOT author the harness to verify it independently. Use a general-purpose agent with full read/inspect tools (not a plan-only or search-only agent type) so it can cross-check every claim against the actual code; give it the harness files + the rubric + the user's language (so it judges native fidelity) + the Phase-2 ledger with every disposition, inline in the dispatch prompt (the ledger is session state — the subagent cannot see it any other way, and the shared rubric does not carry it), read-only, returning a structured list (no raw dump). It checks the four dimensions: content (substantive density + quality principles), format (self-containment, altitude, no references), completeness (required files present + every SCAN-ledger item dispositioned — judged against the inline ledger), source-cross-check (omission vs. hallucination, future-scope exempt). The subagent is a fresh session and cannot ask the user — so the orchestrator relays each finding: internally resolvable → fix directly; needs user intent → carry to Phase 5. A surviving blocker → escalate to the user, do not loop (the 3-doc-gate discipline). This independent pass is distinct from the author's own omission/hallucination self-check during GENERATE (that catches what you can see; this catches what you can't — A=A).

Phase 5 — USER GATE

Present the whole harness to the user — not a raw document dump, but a walk-through of the key decisions captured (what SCAN/ELICIT found, what each doc records, what was dropped from old docs and why). Resolve any Phase-4 questions that need user intent. On approval:

• Write .dryforge/status.json with the initialized marker — { "initialized": true }. This is a local-only marker (inside the gitignored .dryforge/): its presence tells a later go that the harness already exists, so every change is a delta; its absence means first-cycle creation.
• Confirm .dryforge/ is in .gitignore.

Then migration is complete. Remind the user to commit the harness (migration itself does not commit — and a later go treats uncommitted files other than .dryforge/ as foreign work and stops), then clear the session before running ready → go.

Completion gate (avoid self-judgment A=A)

Done only when ALL hold:

• Every docs/ file exists (7 core docs + tracking: status.md, decisions/index.md + an ADR (NNNN-*.md) for each trade-off decision the ledger confirmed, findings.md).
• CLAUDE.md and AGENTS.md both exist, with identical content.
• An AGENTS.md exists for every identified module.
• The independent REVIEW passes (no blocking finding under references/harness-review.md; any surviving blocker was escalated to the user, not looped).
• The user has approved.
• .dryforge/status.json written (initialized) and .dryforge/ is gitignored.