Dual-Agent Migration for AI Coding Projects: Shared Assets and Thin Adapters

Many developers, when switching AI coding agents, first copy the old configuration directory and tweak paths for the new environment. That can get a project running quickly. Over time, problems usually appear: rules diverge, long-term memory falls out of sync, automation is invoked differently, and hooks work on one side but not the other. The two agents end up with different views of the same project.

The real issue is not whether every file was copied. It is the lack of a split between project assets and runtime adaptation. A reliable approach treats business knowledge, engineering standards, and workflows as independent assets, then gives each agent a thin entry point and adapter config.

1. Separate project assets from environment adapters

A long-lived AI-assisted project typically includes:

• Development standards and code style
• Directory layout, module boundaries, and architecture conventions
• Current tasks, stage goals, and to-dos
• Historical decisions, incident notes, and lessons
• Business context, terminology, and references
• Repeatable scripts and automation
• Permission boundaries and confirmation rules for sensitive operations
• Instruction files the agent must load at startup
• Skills, plugins, event hooks, and runtime parameters

The first seven belong to the project. They are team knowledge and engineering assets and should not be bound to one agent. The rest is an adapter layer, shaped by directory layout, config format, event model, and permissions.

In short:

Project assets: how the project should work
Adapter layer: how the current agent should read and execute those assets

Without this split, teams copy everything, then edit two trees. The copies drift into “looks compatible, actually dual maintenance.”

2. Recommended layout: one source of truth plus dual entry points

A shared asset directory plus a thin entry file per agent is more stable.

Example:

project/
├── AGENTS.md
├── .assistant/
│   ├── shared/
│   │   ├── project-rules.md
│   │   ├── architecture.md
│   │   ├── memory/
│   │   ├── knowledge/
│   │   └── workflows/
│   ├── adapter-a/
│   │   ├── entry.md
│   │   ├── skills/
│   │   └── hooks/
│   └── adapter-b/
│       ├── entry.md
│       ├── skills/
│       └── hooks/
├── scripts/
└── docs/

Principles:

1. shared holds agent-agnostic project assets only.
2. Each agent keeps its own entry, skill discovery, and event adaptation.
3. Business rules, memory, and docs must not be duplicated in adapter trees.
4. The entry points the way; it does not copy the entire project protocol.

A third agent later needs only a new adapter directory, not a copy of the knowledge base.

3. Keep entry files thin

Agents look for different startup files—some at the repo root, others in a dedicated config dir. The entry should never carry the full spec.

Limit it to four kinds of information:

1. Project identity and working goals
2. Locations of shared rules, long-term memory, and knowledge
3. Files that must be read before a task starts
4. Confirmation requirements and adapter notes for special operations

Example:

# Project agent entry
You are working on a long-maintained software project.
Before starting a task, read in order:
1. .assistant/shared/project-rules.md
2. .assistant/shared/architecture.md
3. .assistant/shared/memory/current-state.md
Confirm first for:
- Deleting or bulk-editing files
- Changing data structures or migration scripts
- Commands that may affect the external environment
- Overwriting existing implementations or changing public APIs
For execution details in this agent environment, see:
.assistant/adapter-b/entry.md

The goal is a stable load order, not dumping all knowledge into one file. That keeps entries small and reduces differences in how environments handle long context.

4. Keep long-term memory out of tool-specific directories

Memory is often stored in a hidden agent directory: progress, past failures, decisions, items to verify. That is convenient for one agent and tightly coupled for migration.

Split memory into structured files:

memory/
├── current-state.md
├── decisions.md
├── known-issues.md
├── lessons-learned.md
└── pending-tasks.md

Roles:

• current-state.md: current stage, in-progress work, next steps
• decisions.md: confirmed architecture choices and why
• known-issues.md: known defects, repro, temporary workarounds
• lessons-learned.md: experience from past incidents
• pending-tasks.md: unfinished follow-ups

Prefer append-first updates with a reason to change. After a task, do not rewrite memory wholesale. Add shared memory only when the new information will affect later work.

5. Split skill definition from how it is executed

Skills are reusable flows, for example:

• Code review
• Test generation
• Doc sync
• Change-impact analysis
• Log investigation
• Pre-release checks

The core can be shared; invocation often cannot. The same pre-release checklist may use different call sites, permissions, or output formats.

Split into:

Skill definition: goal, inputs, steps, outputs, acceptance criteria
Skill adapter: how this environment discovers, calls, and returns results

Definition example:

# Change impact analysis
## Inputs
- Changed file list
- Related requirements
## Steps
1. Identify affected modules
2. Check public APIs and data structures
3. Find related tests
4. Output risk level and recommendations
## Outputs
- Impact scope
- Potential risks
- Suggested extra tests
- Items that need human confirmation

The adapter only describes how this agent runs that flow. It should not recopy the definition.

6. When migrating hooks, check protocol differences

Hooks fail most often because they depend on:

• Event names
• Input payload shape
• stdin/stdout conventions
• Exit-code meaning
• Execution permissions
• Working directory
• Timeouts and failure handling

Do not copy scripts only. Verify call conditions in the new environment.

Document each hook, for example:

Hook: pre-commit check
When: after change results are produced
Input: files to commit
Action: format check and basic tests
Success: success status and no blocking issues
Failure: return an error summary to the agent and require a human decision

If event models differ, keep one shared check and two thin wrappers. Wrappers convert input, call the shared script, and shape output.

7. Permissions are not inherited by copy

After migration, review permissions and execution boundaries. What was allowed in the old environment may not have the same safety meaning in the new one.

Classify operations:

1. Auto-allowed

Low-risk work such as reading project files, analyzing code, and generating temporary reports.

2. Confirm before execute

Irreversible or wide-impact work: deletes, schema changes, overwriting config, bulk rename.

3. Denied by default

High-risk work: unauthorized paths, reading secrets, sending data to external systems.

Put the policy in shared rules; put confirmation UX in the adapter so principles stay consistent while interaction can differ.

8. Validation is more than “it starts”

Cover at least:

1. Entry — The new agent finds the root entry and loads shared rules as intended.
2. Memory — Ask a question that needs history; confirm current state and past decisions are read.
3. Skills — Run a low-risk workflow; check discovery, parameters, and output.
4. Scripts — Run a read-only script; check cwd, env, and results.
5. Hooks — Simulate the event; check timing, input format, and failure handling.
6. Permissions — Simulate a high-risk action; confirm pause and confirmation.
7. Consistency — Have both agents summarize project state; compare answers.

The last check matters most. Different answers on stage, constraints, or to-dos usually mean duplicated assets or one side still reading old config.

9. Make dual-agent sync a process, not a memory task

Stability comes from ongoing rules:

• Change project standards only in shared
• Do not keep business-rule copies in adapter dirs
• When adding long-term memory, record why it was created
• After changing a skill definition, update acceptance criteria
• Adapter changes require a dual-agent verification
• Run config-diff checks regularly
• Cap entry-file size so they do not grow without bound
• Keep human confirmation for sensitive ops; do not relax permissions because of a migration

A small scan can flag duplicated rules, memory, or knowledge files in adapter dirs and prompt maintainers on commit.

Conclusion

Migrating AI coding agents looks like directory and config work. It is really a restructuring of project knowledge. What you should keep is not one agent’s folder convention, but the project’s standards, memory, skills, and workflows.

Prefer a single source of truth for shared assets and a thin adapter per environment: one copy of project knowledge, entries that only navigate, skill definitions separate from execution, hook logic separate from event wrappers, unified permission policy with independent confirmation UX.

That supports a smoother migration and keeps continuity when more environments are added later, instead of rebuilding a rule set every time the tool changes.