How to Migrate From GitHub Copilot to Factory Droid Without Losing Context (2026)

Copilot documents three types of repository custom instructions, plus two more layers above and below them.

The repository-level three:

"Repository-wide custom instructions, which apply to all requests made in the context of a repository. These are specified in a copilot-instructions.md file in the .github directory of the repository."

"Path-specific custom instructions, which apply to requests made in the context of files that match a specified path. These are specified in one or more NAME.instructions.md files within or below the .github/instructions directory in the repository."

"Agent instructions, which are similar to repository-wide custom instructions, but are currently not supported by all Copilot features. These are specified in files called AGENTS.md, CLAUDE.md, or GEMINI.md."

Above them sit personal instructions, which you set "in a popup on the Copilot Chat page on GitHub.com" and which "Copilot will only apply to you." Below them sit organization custom instructions, which "can only be set by organization owners for organizations with a Copilot Business or Copilot Enterprise subscription."

The precedence chain is documented top to bottom: personal instructions, then path-specific, then repository-wide, then agent instructions, then organization. And there is a clause in that section that changes how the migration should be planned:

"Multiple types of custom instructions can apply to a request sent to Copilot. Personal instructions take the highest priority. Repository instructions come next, and then organization instructions are prioritized last. However, all sets of relevant instructions are provided to Copilot."

Read the last sentence carefully. Precedence resolves conflicts; it does not exclude anything. Everything relevant goes in.

Factory's model is deliberately narrower. Its AGENTS.md documentation describes one file with a specific job:

"AGENTS.md gives Droid the project briefing it should carry into every session: how to install, run, test, edit, verify, and stay inside your repository's boundaries."

And it is explicit about structure and scope:

"Add AGENTS.md at the repository root. Start with one file, then add nested files only where a package, app, or service needs different rules."

"Use it for guidance that should be loaded before Droid writes code. Keep it short, specific, and easy to verify."

So what transfers is this. Your repository-wide file transfers almost directly. Your AGENTS.md — if you already have one for Copilot's agent instructions — transfers as-is and is now the primary surface rather than the lowest-precedence one. Your path-specific instructions transfer in content but change mechanism. And your personal and organization instructions do not transfer at all, because there is nothing to copy: one lives in a web popup scoped to you, the other in organization settings scoped to your company.

Step 1: Collect the two layers that are not files, and decide where they go

This is the step that gets skipped, so do it first.

Personal instructions. Open the Copilot Chat page on GitHub.com and read what is in that popup. In most teams it holds two kinds of thing: genuine individual preference ("explain a single concept per line," "always respond in Portuguese" — the documentation's own examples) and rules that should never have been personal in the first place, because they describe how the project works and every teammate needs them.

Split them. The individual preferences belong in Factory's user-level settings, which live at ~/.factory/settings.json on macOS and Linux, alongside an optional settings.local.json. The project rules that were hiding in your personal popup belong in the repository's AGENTS.md, where the rest of the team finally gets them. This is usually the single most valuable outcome of the whole migration, and it is invisible if you only migrate files.

Organization instructions. These need an admin to read out, and they are worth capturing even though Factory's instruction surface does not document a per-organization equivalent layer. Note that Copilot's own documentation limits their reach — they are "currently only supported for Copilot Chat on GitHub.com, Copilot code review on GitHub.com and Copilot cloud agent on GitHub.com." So there is a decent chance the org instructions were never affecting your IDE sessions anyway. Confirm that before you decide how much to carry over.

Whatever genuinely applies to every repository goes into the user-level or project-level .factory/ configuration and the repository AGENTS.md. Whatever was compliance boilerplate that never reached the IDE can be dropped with a note saying why.

Step 2: Resolve the conflicts Copilot let you defer, then rebuild the scoping

Because Copilot provides all relevant instruction sets and uses precedence only to settle disagreements, a team can run for a year with two layers that contradict each other and never notice. The higher-precedence one wins and the lower one sits there.

Factory's guidance runs the other way. Its AGENTS.md documentation asks for rules that are "short, specific, and easy to verify," recommends putting the exact install, development, test, type check, lint, and build commands first, and draws a clear line about what belongs where:

"Keep human onboarding, screenshots, and contributor background in README.md. Put Droid-specific commands, guardrails, and completion criteria in AGENTS.md."

It also asks for something Copilot's format does not: a verification section that states the required proof before Droid calls work finished. The docs contrast concrete rules that change how Droid works against "vague rules that cannot be checked." If your copilot-instructions.md contains a line like "write good code," this is where it gets deleted rather than ported.

So write one root AGENTS.md with the commands first, then the repository map, conventions, testing rules, generated-file rules, security boundaries, and verification steps. Where two old layers disagreed, pick one. That decision is real work, and it is the work Copilot's precedence chain was absorbing for you. If you already keep a CLAUDE.md alongside your Copilot files, converting a CLAUDE.md into Copilot's instruction format covers what tends to survive that kind of consolidation and what does not — and what coding agents actually read is worth a pass before you decide how long the new file can be.

Then handle the path-specific files. Copilot's .github/instructions/NAME.instructions.md files target file patterns, and the documentation explains why they exist: "By using path-specific instructions you can avoid overloading your repository-wide instructions with information that only applies to files of certain types, or in certain directories."

That purpose survives; the mechanism changes. Factory scopes nested AGENTS.md files by directory — "add nested files only where a package, app, or service needs different rules." A rule scoped to a directory ports cleanly: put an AGENTS.md in that directory. A rule scoped to a file type across the whole tree does not have a directory to live in, so you have two honest options. If the file type is concentrated in one area, place it there. If it genuinely spans the repository, state the scope in the rule's own first sentence and accept that it is now stated rather than matched.

One more thing to check while you are in the repository: if you find a .droid.yaml, it is a deprecated surface. Factory's settings documentation says to use the current .factory/ files instead, and to "use AGENTS.md for repository instructions, conventions, and validation commands."

The two steps above are a translation plus a set of decisions. The decisions are the expensive part, and right now they exist only in whoever's head made them during the migration.

That is the layer worth putting somewhere durable. When you resolved a conflict between a personal instruction and a repository one, you made a call about which convention the project actually follows. When you deleted "write good code," you decided it was unverifiable. Six months from now, someone will find the surviving rule and ask why it says what it says.

MemoryLake holds those decisions outside both products and serves them to whichever agent asks, over MCP or the API. Copilot's own memory features and Factory's own configuration stay exactly where they are and keep working the way their vendors document.

Step 1: Create an API key

Generate a key and make your first request in about thirty seconds. Do it before you start Step 2 above, so there is somewhere to put each decision as you make it.

Step 2: Upload your first memories

Every conflict you resolve is a memory worth keeping: which rule won, which one lost, and why. Add the rules that came out of a specific incident, and the libraries or patterns you deliberately do not use. Documents and other supporting files go in the same place.

Step 3: Connect your AI & agents

Give Claude, Codex, OpenClaw, and Droid access over MCP or the API. Once connected, "why is this the convention" is answered with the reason attached, which is what lets the root AGENTS.md stay as short as Factory recommends.

The first change is that the personal-instruction problem stops recurring. Once the project rules that were hiding in one person's popup are in the repository and the reasoning is in a shared store, there is no longer a private layer silently outranking the team's.

The second is about Spec Mode, which is where Factory produces its most valuable artifact and also where the durability gap sits. Spec Mode is read-only planning that ends by asking for approval — Droid "should not edit files, change configuration, make commits, start services, or write to external systems" while in it. The plan it produces is the reasoning for a change, written down at exactly the right moment. But the default save location is ~/.factory/specs, which is a per-user directory outside the repository. That is a reasonable default and it is configurable through specSaveDir. It is also the reason a good plan can exist on one laptop and nowhere else. Either point specSaveDir at something committed, or make a habit of moving the conclusions into the shared store.

The third change arrives at the next tool migration. The instruction file gets rewritten again — that is unavoidable, and every tool's format is a little different. The decisions behind it do not, because they were never in anyone's instruction format.

Read the personal-instructions popup before you touch a file. It is the layer with the highest precedence and the lowest visibility, and some of what is in it belongs to the whole team.

Ask an admin for the organization instructions, then check whether they ever applied. Copilot's documentation limits their support to specific surfaces. Carrying over rules that never reached your IDE is wasted work.

Delete anything unverifiable rather than porting it. Factory's documentation asks for rules that can be checked, and contrasts them with vague ones. A rule nobody can verify was not doing anything in Copilot either.

Put the commands first. Install, run, test, type check, lint, build. Factory's own step order recommends this, and it is the part of your instruction file that pays for itself on the first session.

Write the verification section. State the proof required before Droid calls work finished. Nothing in Copilot's instruction format asked for this, so you probably do not have it yet.

Decide where specs live on day one. The default is a per-user directory outside the repository. Point specSaveDir somewhere shared, or move the reasoning out by hand.

The Copilot to Factory Droid migration is a file copy plus two things that are not files. Personal instructions live in a popup on GitHub.com and outrank everything else; organization instructions live in company settings and, by Copilot's own documentation, only reach certain surfaces. Neither can be migrated by copying anything, and the first one usually contains project rules that were never meant to be private.

The second half of the work is resolving conflicts that Copilot's precedence chain was absorbing. Because all relevant instruction sets are provided and precedence only settles disagreements, contradictions could sit unnoticed for a long time. Factory asks for one short root file with concrete, checkable rules — which means someone has to actually pick a winner.

Do the two non-file layers first, resolve the conflicts deliberately, decide where specs get saved, and keep the reasoning somewhere no instruction format can strand it.