Scenario: Multiple adapters side-by-side

When to use #

You want to drive the same project from more than one AI CLI — for example Claude Code for deep refactors and Codex for everyday edits, or all three of Claude Code, Codex, and Copilot for a team that mixes preferences. Adapters are siblings: each emits its own engine directory, but docs/, agent-artifacts/, and .beads/ are shared substrate across all of them.

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
  init["aidokit init --adapter "]:::cli
  add["aidokit add adapter "]:::cli
  shared[".beads/ + docs/ + agent-artifacts/"]:::artifact
  cc[".claude/"]:::adapter
  cx[".codex/"]:::adapter
  cp[".copilot/"]:::adapter
  ok(["multi-adapter ready"]):::ok
  you --> init --> shared
  init --> add
  add --> cc & cx & cp
  cc & cx & cp --> ok

Step-by-step #

1. Bootstrap with one adapter #

Pick whichever adapter you want to lead the initial scaffold. Run one of the following (alphabetised, neutral):

If Claude Code

npx aidokit init --adapter claude-code --tier standard --stack node-ts --yes

If Codex

npx aidokit init --adapter codex --tier standard --stack node-ts --yes

If Copilot

npx aidokit init --adapter copilot --tier standard --stack node-ts --yes

Expected: the picked adapter's engine directory plus the shared substrate (docs/, agent-artifacts/, .beads/) and that adapter's agent rules file (CLAUDE.md for claude-code, AGENTS.md for codex and copilot).

2. Add each remaining adapter #

For each adapter you still want, layer it on. Skip whichever you already initialised with — aidokit add adapter is idempotent and re-running on the bootstrap adapter is a no-op.

aidokit add adapter claude-code
aidokit add adapter codex
aidokit add adapter copilot

Expected: one new engine directory per added adapter; the manifest now lists every picked adapter.

3. Verify #

aidokit doctor

Expected: doctor lists every picked adapter alongside its conformance tier; shared dirs report healthy.

4. Confirm the multi-adapter file tree #

ls -la

You should see roughly:

my-app/
├── AGENTS.md         ← if codex or copilot was picked
├── CLAUDE.md         ← if claude-code was picked
├── .claude/          ← if claude-code was picked
├── .codex/           ← if codex was picked
├── .copilot/         ← if copilot was picked
├── docs/             ← shared
├── agent-artifacts/  ← shared
└── .beads/           ← shared

Common mistakes #

Running aidokit init twice with different adapters. Use aidokit add adapter <name> for everything after the bootstrap.
Editing files inside one engine directory and expecting changes to apply to the others. Engine directories are independent — share via docs/ or a stack-pack instead.
Forgetting that AGENTS.md is shared between codex and copilot. Edits to it affect both.