Kira — a cross-repo bridge engineer for service-split migrations

Kira is a Claude Code setup for one specific, dangerous job: splitting a service out of a live monolith. She sits above both repos at once, holds both codebases in her head, and guards the class of bug single-repo tooling can't see — the change that is correct in the repo you edited and breaks production through the repo you didn't.

She was extracted from a real production migration, where this workflow caught — before push — a rewritten notification sender that silently dropped international dial-code handling, workers that would double-message customers on a shared Redis, and an "improvement" that ran live DDL on a shared analytics table.

⚠️ For serious multi-repo migrations only. Kira earns her keep when two-or-more repos share databases/queues, run background jobs, and one of them is live in production. Single repo? Use the base Acharya kit. Small project? Plain Claude Code.

Quick start

Kira is an overlay on the Acharya base kit — she reuses its agents, contract, and hooks, and adds the cross-repo layer on top.

cd your-workspace     # the PARENT folder that contains your repos — NOT inside one repo
npx acharya init                  # 1. the base kit
npx kira-multi-repo-bridge init   # 2. the Kira overlay on top

Then:

1. Edit .claude/acharya.config.json → the repos block: each repo's folder, role (which one is live? which is the target?), branch, and which datastores they share.
2. Open Claude Code in the workspace and ask Kira to run /cross-check all — she inventories both repos and drafts the cross-repo map (BRIDGE.md) for you.
3. Migrate feature by feature with /migrate-feature <area>.

How the npm install works: both packages are only installers — they copy .claude/ out of the package into your workspace folder as plain files you own and commit. Nothing stays in node_modules, nothing touches your package.json, and Claude Code never reads from node_modules. The overlay is also state-safe: re-running it never overwrites a BRIDGE.md you've filled in or a config that already has your repos.

Other commands: init --dry-run (preview) · npx kira-multi-repo-bridge doctor (checks: base kit present, overlay intact, BRIDGE.md filled, declared repos actually exist).

Requirements: Claude Code · Node ≥ 18 · any git host (plain git only) · the Acharya base kit first. Child repos work best with their own skills (run /acharya-init inside each).

The vocabulary, in 30 seconds

New to this kit family? Read the base kit's glossary first (agent, hook, skill, slash command). Kira adds these:

| Term | What it actually is | |---|---| | Workspace | The parent folder holding your sibling repos side by side. Kira's .claude/ lives HERE, not inside a repo. | | Source repo | The live monolith — production truth today. | | Target repo | The new service being split out — usually a re-architecture, not a copy. | | Overlay | This package. It replaces the base kit's identity/config with bridge versions and adds the files below. | | BRIDGE.md | The one-page cross-repo map: what lives where in each repo, which queues/crons exist on both sides, who owns what during cutover. Ships as a guided template; Kira drafts it. | | Shared-datastore hazard | The core danger: two repos pointing at the same Redis/DB means same-named queues are ONE queue and same crons fire TWICE. No error is ever thrown. | | Release gate | Kira's answer format — never prose, always SAME / DIVERGED / MISSING / BREAKS / UNPROVEN / VERDICT: GO or NO-GO. | | MIGRATION_VERDICT | The independent reviewer's structured GO / NO-GO on a migrated feature, produced without seeing Kira's own assessment. | | Ownership ledger | A table in BRIDGE.md §5: for every migrated queue/cron/feature — who owns it now, so nothing runs twice and nothing runs nowhere. |

The problem Kira exists for

When you split a service out of a live monolith, the migration default is both repos pointing at the same datastores. That creates failures that throw no errors:

• Same-named queue = the same queue. Two worker pools consume one queue; jobs split randomly between old code and its rewrite. (An environment prefix like prod_* does NOT isolate the repos.)
• Same cron in both repos = fires twice per tick. Duplicate customer messages, double charges.
• Producer moved without its queue/worker = silent job loss.
• The rewrite silently drops behaviour. A missing validation branch is a customer bug the day the target starts serving.
• A target-side improvement mutates shared schema under the live repo's feet.

None of these are visible from inside either repo alone. That's the bridge's job.

What's in the box

.claude/                           (overlaid onto the Acharya base kit)
├── identity.md                    Kira's persona — the bridge reflexes, replaces the base persona
├── acharya.config.json            ⭐ the repos block — YOUR repos' roots, roles, shared stores
├── BRIDGE.md                      the cross-repo map (guided template → Kira fills it)
├── commands/
│   ├── migrate-feature.md         /migrate-feature — assess + plan moving a feature safely
│   └── cross-check.md             /cross-check — the pre-push cross-repo safety gate
├── skills/cross-repo-safety/      the hazard matrix + A–G checklist (the kit's own skill)
└── agents/                        bridge-aware versions of reviewer/explorer/migrator/
                                   DB specialists — each resolves "which repo?" first

Everything else (contract, editor, hooks, the rest of the guild) comes from the base kit underneath.

Model economics are inherited from the base kit (which agent runs on which model, and why) — cheap Haiku hands, Sonnet planners on rails, Opus only where mistakes are expensive. Kira's bridge variants keep the same assignments, with one worth calling out: Netra runs on Opus deliberately. She is the production GO / NO-GO gate for a live migration — the one verdict in this whole workflow you never want from a budget model. A bridge instance reads two codebases, so everywhere else the kit stays aggressively frugal; the gate is where the saved tokens get spent.

How a migration check works

> /migrate-feature notification sender

Kira: comparing both impls… the source threads dial_code through
send(); the target's rewrite DROPPED it — every non-default-region
number would be misrouted, and the ledger would still say "sent".
Firing Netra for the independent verdict…

MIGRATION_VERDICT (excerpt)
  PORT_FIDELITY: DIVERGED
    - DROPPED: dial-code threading (sender.js:1553 ↔ dispatch.js:88)
  USER_SAFETY:   AT_RISK — international messages silently misrouted
  CROSS_REPO:    hazard — shared queue, no enqueue dedup key
  PROD_VERDICT:  NO-GO
    condition_to_flip: thread dial_code at the 4 producer sites +
                       close the duplicate-enqueue path

Note what happened there: Kira made her own assessment, then Netra (the reviewer agent) re-derived the verdict independently — she reads both implementations fresh and is never shown Kira's conclusion. A planner double-checking itself is not a gate; a second pair of eyes is.

Every assessment ends as a release gate:

SAME:       what is identical and safe
DIVERGED:   behavioural differences source vs target
MISSING:    source logic not reproduced in the target → correctness gaps
OPERATOR:   does the internal operator still get correct behaviour?
USER:       does the end user get correct + identical behaviour?
BREAKS:     concrete failures if this ships as-is
UNPROVEN:   what couldn't be verified, and who must confirm
VERDICT:    GO / NO-GO  + the single condition that flips it

The rules Kira never breaks

1. "Works in the target" ≠ done. "Users see no change" = done.
2. Unsure whether datastores are shared? Treat them as shared. Fail safe.
3. Feature knowledge lives in each repo's own skills — read live, never duplicated upward. The bridge owns only the cross-repo layer.
4. Editing one repo? State the impact on the other — unprompted.
5. Never push unasked. In either repo. Pushes happen on your explicit say-so, after the gates ran — /cross-check first for anything touching shared jobs or datastores. The base kit's settings force a prompt on git push regardless.

Workspace layout

your-workspace/                  ← Kira's seat (not itself a product repo)
├── .claude/                     ← base kit + this overlay
├── yourapp_web/                 ← live monolith (own git repo, own .claude/skills)
└── yourapp_admin/               ← the service being split out (own git repo, own .claude/skills)

FAQ

Why an overlay instead of a standalone kit? So the base kit stays the single source of the shared machinery (contract, hooks, guild) — Kira only carries what's genuinely cross-repo. doctor checks both layers are intact.

More than two repos? Yes — the repos block takes any number of entries (the production migration this comes from bridged three). The hazard math gets worse with each: a cron in N repos fires N times.

Does it need GitHub? No — plain git only. GitHub, GitLab, Bitbucket, or a bare remote.

Can Kira run the migration herself? She plans, verifies, and gates. Schema SQL is written but never executed; pushes always wait for your explicit go. The dangerous buttons stay yours.

License

MIT