A Single Source of Truth for Project Assets Across Two Coding Assistants

When a long-running project onboards a second AI coding assistant, the usual failure is not “files were never copied.” After the copy, two rule sets, two memories, and two workflows grow independently. A constraint changed on one side is forgotten on the other. In the short term the difference is invisible; over time the two sides disagree on architecture, current tasks, and risk boundaries for the same repository. That is not compatibility. It is a fork.

The right split is not directory duplication. It is ownership: what describes the project itself versus what describes how a given assistant reads, executes, and asks a human.

Two kinds of objects

Project assets do not belong to any assistant. They often happened to live in a tool directory. Typical examples:

• Architecture boundaries, directory responsibilities, naming and interface conventions
• Current iteration goals, open questions, and pitfalls already hit
• Business terms, domain rules, and read-only reference material
• Repeatable check, build, release, and data-repair procedures
• Deterministic steps expressed as scripts, not improvised in chat

Tool adapters cover which instructions to read at startup, where skills are discovered, where external-tool connections are declared, hook input/output, and whether commands default to ask, allow, or deny. The first class should be shared. Only the second needs a thin layer per assistant.

Without that split, the fastest move is to mirror entire directories. It runs in the short term; later every spec change is dual-written, and conflicts have no single source of truth.

Where the single source of truth lives

Create an assistant-neutral asset root in the repo, such as docs/project or .agent-shared. Layer by stability:

1. Stable specs: architecture and quality gates that change rarely and must be reviewed.
2. Working memory: current tasks, decision logs, known defects—frequent updates, with dates and owners.
3. Executable processes: scripts and checklists, not steps that exist only in a past conversation.
4. Reference material: long docs, API summaries, environment differences, indexed by topic rather than dumped into the startup file.

Use ordinary markup and scripts, not a vendor-private syntax, so humans can read and merge them during reviews or tool switches.

Version these files with application code. Spec changes follow the same review path. Memory files may update more often, but neither side may keep a shadow copy. Experiments on a branch must merge back into the main assets or be explicitly discarded—never two “official” descriptions in parallel.

Thin launchers, not a second protocol

Each assistant typically auto-reads an entry file, often from the repo root down to the working directory, with nearer files winning, and often with a length cap. The entry file is the wrong place to paste a giant spec.

The root entry should be a launcher that does four things: declare the asset root; point in a fixed order at specs, memory, and process indexes; state this tool’s permission and hook differences; resolve conflicts in favor of shared assets. Sketch:

# Entry (keep it short)
Asset root: docs/project
Read order:
  1. specs/architecture.md
  2. memory/current.md
  3. processes/index.md
Conflicts: shared assets win; this file is local adapter only
Do not: paste spec body here

Subdirectory conventions should be incremental only (for example, “generated code in this directory must include contract tests”). Do not recopy global specs locally, or nearer text will silently override distant rules and reviewers will not see that the override came from duplication rather than an intended exception.

Mapping memory, skills, and hooks

Long-term memory must be mergeable. Each record includes context, decision, blast radius, and expiry. Assistants may append candidate memories; a human confirms before they become facts. Keep current work separate from historical decisions so startup does not treat expired goals as active.

Skills or reusable workflows should state goal, inputs, steps, success criteria, and stop conditions on failure—not a UI button. Discovery indexes can be per assistant and should only reference shared processes, not copy their bodies. Process edits then happen once.

Hooks are the easiest adapter to hard-code. One side may fire after edit, before command, or at session start; names and payloads differ. Shared layer defines when to check, what to check, and whether failure blocks. Each adapter maps that policy to its events. Example shared policy: “before commit, run static checks and critical tests; on failure stop and report the log path.” The adapter only attaches that policy to the right event.

External-tool connections: purpose and least privilege live in shared docs; concrete config stays in each adapter directory. Secrets stay out of the repo.

Spell out permission-model differences

Assistants differ on commands, writes, and network: some conservative, some freely executable in the workspace. The adapter must translate the project’s real risk appetite, not inherit tool defaults.

Three tiers in the shared spec, enforced by adapters:

• Do immediately: format, read-only search, run existing check scripts in agreed directories.
• Explain first: add dependencies, change public APIs, bulk rename, touch config outside generated code.
• Must ask: delete data, change permissions, access production, send content externally, rewrite the shared specs themselves.

If a tool lacks fine-grained switches, the entry file must require: stop and list a plan for tier two and above. Do not loosen existing human-confirmation boundaries for convenience. Permission mismatch is an adapter problem, not a reason to downgrade established safety habits.

Migration steps

1. Inventory existing tool directories; tag each file as asset or adapter. If unsure, treat it as an asset draft until review.
2. Move specs, memory, processes, and scripts to the asset root; strip old-tool field names and startup incantations.
3. Write thin entries and indexes for old and new sides; delete body-level copies.
4. Open a new session on both sides with the same acceptance questions: what are the project constraints, where is current work, what must be asked first. If answers diverge, tighten the source—do not add a “comparison note.”
5. Make one small change only in shared assets; confirm both sides pick it up on next start with no manual sync.
6. Watch at least one full iteration: a new skill, a spec edit, a hook failure. Dual-write still happening means body text remains in the adapter layer.

Common failures and responses

Whole-tree copy plus document diffs: cost grows with spec length; merge conflicts pick the wrong side. Ban body-level duplicates.

Dumping all chat history into the entry file: hits length limits and buries current constraints. Keep indexes in the entry; load details on demand.

Skills hard-coding one side’s CLI or config paths: they break on the other side. Skills call in-repo scripts that detect the environment.

Hooks block on one side and only warn on the other while the team assumes equivalence. In acceptance, force a check failure and confirm blocking matches the shared policy.

Memory without expiry: old decisions suppress a new architecture. Scope every decision; void or rewrite related memory when architecture changes.

Team conventions

Solo projects can rely on discipline. Multi-person work must put “edit the asset root only” in the contribution guide. Review checklists add three items: no spec body pasted into adapters; memories have source and date; new workflows are reproducible by script without opening a specific assistant.

If the organization already has a knowledge base, still treat the repo as canonical. External docs are mirrors or longer background. Otherwise you get a new fork between repo and wiki. Mirrors may auto-export; there is only one edit entry.

Summary

The goal is not to make two assistants look the same. It is that both understand the same project from the same place: single-source project assets, very thin tool adapters, entries that only navigate, processes as scripts where possible, permission differences explicit. Then adding or running a second coding assistant costs about one commit, not two diverging project memories.