aidokitwiki
User Docs Wiki

Scenario: Migrate from a hand-built kit

Audience-User Status-Shipped v0.5 Spec-Conformance

When to use #

You have a hand-built .claude/, .codex/, or .copilot/ (or a mix of these) that predates aidokit, and you want aidokit-managed structure going forward without losing your local edits.

At a glance #

%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif",
    "fontSize": "14px",
    "primaryColor": "#eff6ff",
    "primaryTextColor": "#0f172a",
    "primaryBorderColor": "#2563eb",
    "lineColor": "#475569",
    "secondaryColor": "#f1f5f9",
    "tertiaryColor": "#ffffff",
    "clusterBkg": "#f8fafc",
    "clusterBorder": "#cbd5e1"
  }
}}%%
flowchart LR
  classDef actor    fill:#ede9fe,stroke:#6d28d9,color:#1e1b4b,stroke-width:1.2px;
  classDef cli      fill:#dbeafe,stroke:#1d4ed8,color:#0c1f4a,stroke-width:1.4px;
  classDef adapter  fill:#cffafe,stroke:#0e7490,color:#083344;
  classDef pack     fill:#dcfce7,stroke:#15803d,color:#052e16;
  classDef core     fill:#fef9c3,stroke:#a16207,color:#422006;
  classDef artifact fill:#f1f5f9,stroke:#475569,color:#0f172a;
  classDef stop     fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d,stroke-dasharray:4 3;
  classDef ok       fill:#ecfdf5,stroke:#047857,color:#064e3b;
  classDef external fill:#fff7ed,stroke:#c2410c,color:#431407;
  you(["you"]):::actor
  back["cp -r .claude .codex .copilot .local-backup"]:::artifact
  mig["aidokit migrate handbuilt-to-"]:::cli
  diff["diff -r .local-backup ..."]:::pack
  doc["aidokit doctor"]:::cli
  commit["git commit"]:::cli
  ok(["migrated cleanly"]):::ok
  you --> back --> mig --> diff --> doc --> commit --> ok

Step-by-step #

1. Back up the existing engine directories #

cp -r .claude .codex .copilot .local-backup 2>/dev/null || true

The 2>/dev/null guard silently skips any directory that does not exist — safe regardless of which adapters you actually had.

Expected: a new .local-backup/ containing whichever of .claude/, .codex/, .copilot/ existed.

2. Run the migration #

aidokit migrate handbuilt-to-<starter|standard|strict> --adapters claude-code,codex,copilot --preserve-overlay

Use --preserve-overlay to diff your local edits and re-apply them as a .local/ overlay; omit it to overwrite with canonical templates.

Expected: a diff confirmation for every changed file; nothing overwritten without acknowledgement.

3. Review the diff against your backup #

diff -r .local-backup .claude .codex .copilot 2>/dev/null | head -80

Expected: a bounded diff summary; eyeball anything you did not expect.

4. Verify conformance #

aidokit doctor

Expected: doctor reports OK at the picked tier for every adapter you migrated.

5. Commit #

git add -A
git commit -m "chore: migrate hand-built kit to aidokit"

Keep the migration in its own commit — easier review and a clean rollback point.

Common mistakes #

See also #