Adopting cckit

FlowCommand

Bring cckit to any repo, one issue at a time, without restructuring what’s already there.

Adoption is issue-driven and incremental: file an issue for it, then walk the steps below. Every step is a single cckit verb, so an agent can perform the whole adoption unattended and report back.

The flow

Run these in order from inside the repo.

cckit scan      # 1. detect the repo's stack + kit state
cckit init      # 2. scaffold cckit.config.json + .claude/  (greenfield only)
cckit adopt     # 3. record kit-shaped files the repo ALREADY has
cckit migrate   # 4. reshuffle any old kit layout to the current one
cckit update    # 5. report whether the project is behind the installed cckit
cckit doctor    # 6. preflight: deps + gh auth are in place

What each step does

1. scan — where you stand. It reports the kit state: configured (cckit already runs here), partial or claude-only (some kit-shaped files exist but aren’t owned), or none (greenfield).

2. init — greenfield only. For a none repo, it writes the config and a .claude/ folder from a profile. Skip it if scan says configured.

3. adopt — take ownership of files already there. This is the bridge for a repo that imported the kit by hand (copied a .claude/, ran an old init, a teammate pasted skills). The files are present but the manifest — cckit’s record of which files it owns — doesn’t know them, so update and remove won’t touch them. adopt records each at its current hash. It writes no content; it only takes ownership. Dry-run first; it never claims your knowledge/, plans, or app code.

4. migrate — fix layout drift. It reshuffles an old kit layout to the current one, and survives repeated runs unchanged.

5. update — check your version. It reports whether the project trails the installed cckit version.

6. doctor — confirm the basics. It checks deps and gh auth are in place.

What is the manifest?

The manifest is cckit’s list of which files in your repo it owns and manages. Files outside it — your app code, your knowledge/, your plans — are never touched by update or remove. adopt is how you add already-present kit files to that list.

Why issue-driven

Every change starts as an issue — because that’s how real software is built. The issue says what and why before any code exists; the branch, the PR, and the review all hang off it, so the work is traceable, reviewable, and reversible. (Adoption itself follows this path: one issue → one branch → one PR via cckit start / cckit pr, with the issue recording which steps applied to this repo.)

You don’t have to know that theory to get it. cckit makes the issue-first path the path of least resistance, so you pick up the discipline of professional software delivery just by using the kit — no process to study, no habits to force. The good practice is simply the default.

Idempotent and safe

Every step is a no-op when there is nothing to do. The file-touching ones (init, adopt, migrate) are dry-run-previewable and never overwrite content they don’t own. Re-running the whole flow is safe.