How to add cckit to an existing repo without disrupting it

FlowConversational

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Beginner5 min readNeedsan existing Git repogh (authenticated)

What you’ll do: bring cckit into a project that already has its own layout — nothing above the kit is restructured. cckit looks at what’s already there, adds its config, and records the kit-shaped files the repo already has, then confirms everything’s wired up.

Steps

1. Ask Claude to adopt the repo.

   Prompt to paste

   Bring cckit into this existing project without disturbing its layout. Look at what's already here,
   add its config, and record the kit-shaped files the repo already has. Then confirm everything's
   wired up.

2. cckit scans, scaffolds, and adopts.

   cckit scan      # detect the repo's stack + current kit state
   cckit init      # scaffold cckit.config.json + .claude/
   cckit adopt     # record kit-shaped files the repo already has
   cckit status    # confirm the board + worktrees + handoff view

3. Confirm nothing else moved. status shows the board, any worktrees, and the handoff view. Your existing files and structure are untouched — only cckit’s own config was added.

How it works

Adoption is deliberately additive. scan reads your stack and current state so cckit knows what it’s joining; init writes only its own cckit.config.json and .claude/; adopt records the kit-shaped files you already have so cckit manages them in place instead of duplicating them. Because everything resolves from the config, cckit adapts to your repo — your repo never adapts to cckit.

Additive, not a rewrite

No company, framework, or repo layout is baked into cckit. Adoption adds a config and records what exists; it never reshapes your project.

Troubleshooting

adopt didn’t pick up a file I expected. It records the kit-shaped files it recognizes. If one was missed, add it to cckit.config.json and re-run status to confirm it’s tracked.

I already ran init elsewhere. init is idempotent — running it on an already-configured repo leaves your existing config in place rather than overwriting it.

The board looks empty. That’s expected on a fresh adoption — there are no issues in flight yet. Start one with the single-issue lifecycle.

Related tutorials

Set up cckit in a repo The from-scratch version for a new repo.

Take a GitHub issue to a merged PR Run your first lifecycle after adopting.

Drive Claude Code headless in CI Wire the adopted repo into a bot.