How to Get Factory Droid's Spec Plans Out of Your Home Directory (2026 Guide)

Factory's settings documentation has a section called Spec mode settings. It contains one sentence of description and exactly one setting.

"Controls the persistent spec store created by Spec Mode."

The setting is specSaveDir, and its row in the reference table reads:

"Directory where saved specs are written. Supports ~ expansion."

Its default value is ~/.factory/specs.

That is worth stating plainly: there is a persistent spec store, it is a documented feature, and it defaults to a per-user location. Nothing is hidden and nothing is broken. The default is simply a personal-tool default applied to a team artifact.

It is also a consistent house style rather than an oversight. In the same settings reference, worktreeDirectory — the parent directory for git worktrees created with the worktree flag — defaults to ~/.factory/worktrees. Factory puts its own scaffolding in your home directory, which is the right instinct for scaffolding. A spec is not scaffolding.

Two things follow, and the second is the expensive one.

The plan does not travel. Spec Mode is recommended precisely for the work where a plan matters most:

"Spec Mode is for research and planning before implementation. Use it for architecture changes, migrations, security-sensitive work, or any task where you want to review the plan before Droid edits files."

Those are all multi-person, multi-week efforts. The person who implements step four is frequently not the person who ran the session, and the plan is not somewhere they can read it.

The boundary the mode enforces is worth quoting too, because it explains why the output is trustworthy enough to be worth keeping:

"During Spec Mode, Droid should not edit files, change configuration, make commits, start services, or write to external systems. It can read files, search the repo, inspect linked artifacts, and ask clarifying questions."

The reasoning does not survive the task. A spec is written against a moment: this codebase, this constraint, this set of options. Six months later the implementation is merged and the spec is a stale file in a home directory nobody opens. The decisions inside it — we rejected the event-sourced approach because of the replay cost, we accepted the extra table to avoid a migration — are still true and still load-bearing, and there is nowhere they have been recorded as decisions rather than as one paragraph inside an obsolete plan.

That second problem is the one people discover late, usually when somebody leaves. It is the same shape as keeping AI context when someone leaves: the knowledge was written down, and it was written down somewhere personal.

Copying the good specs into the repo by hand. Works, and it happens for the first two. The friction is that the file is in a path you have to remember, named for a session rather than for the work, so the copying stops.

Pasting the plan into the pull request description. Better, because it lands somewhere reviewable and permanent. But a PR description is scoped to one diff, and a spec that spans four PRs gets fragmented across four descriptions, each missing the parts that mattered to the others.

Putting the plan into a ticket. Same trade. The plan is now visible to the team and coupled to a work item that gets closed. Closed tickets are not where anyone looks for the reason a table exists.

Turning the spec into an AGENTS.md section. This confuses two kinds of content. AGENTS.md holds standing instructions read on every session; a spec is a one-time plan. Merge them and you get a long always-loaded file describing work that finished in March.

Leaving the default and relying on the session transcript. The weakest option, because Droid's own docs describe subagent and session behavior as bounded by the session, and a transcript is a log rather than a document. The whole point of Spec Mode is that it produces something better than a transcript.

Committing every spec, forever. The overcorrection. Point the store at the repository with no further thought and you get dozens of stale plan files, each proposing an implementation that has since changed, competing with your actual documentation for a reader's attention — and competing with your actual instruction files for an agent's.

The pattern across all six is that people treat the spec as either a personal scratch file or a permanent document, and it is neither. It is a temporary artifact containing a few permanent facts. The fix has to handle both halves.

Three steps. The first is a one-line change, the second decides what you commit, the third is what makes it stick.

Step 1: Point specSaveDir at the project

Set specSaveDir in your project's Factory settings to a directory inside the repository rather than accepting the home-directory default. Factory reads settings from ~/.factory/settings.json at the user level and from a .factory/ folder in the project, so put this one in the project file — a spec location is a property of the project, not of your machine.

Confirm the path resolves where you expect on the first run before you rely on it. The documented note on this setting is that it supports ~ expansion, so it is worth checking the behavior you get for the path style you choose rather than assuming.

Two related settings are worth knowing while you are in this file. The first is sessionDefaultSettings.interactionMode, whose documented job is simply:

"Sets whether new sessions start in Auto or Spec Mode."

Setting it to spec is useful on a repository where you want planning to be the default posture. The second is specModeModel, which the reference describes as an override to the model used when sessions start in Spec Mode — worth setting, because planning and implementing reward different models. Also note that .droid.yaml is documented as an older configuration surface; use the .factory/ files.

Step 2: Decide what is committed and what is ignored

Now that specs land in the repo, decide deliberately, because the default answer of "commit everything" is the overcorrection above.

The useful split is by lifespan. A spec for work that is in flight should be committed — it is the shared plan, and the reviewer of PR two needs it. A spec for work that shipped has served its purpose, and keeping it around invites someone to read a plan that no longer describes the system.

Factory gives you the mechanism for the machine-specific half. You can create a settings.local.json alongside settings.json in any .factory/ folder, and the documented behavior is:

"Local overrides merge on top of the corresponding settings.json at the same level and follow the same hierarchy precedence. Add settings.local.json to .gitignore if you want to keep machine-specific preferences out of version control."

Use that for anything genuinely personal, and keep the shared settings.json holding the shared spec path.

Step 3: Lift the decisions out before you archive the plan

This is the step that changes the outcome, and it takes about two minutes per spec.

When a spec's work merges, read the plan one last time and pull out the sentences that will still be true next year. Not the implementation steps — those are in the code now. The decisions: what was considered, what was rejected, and why. A spec typically contains three or four of these, buried in prose among twenty paragraphs of sequencing.

Those three or four sentences are the entire durable value of the document. Record them somewhere that is not a plan file, and the plan file can be archived or deleted without losing anything. Skip this step and you are back to keeping stale specs forever because you are afraid of what is inside them — the exact hoarding problem that makes people re-explain context to AI over and over.

MemoryLake is where the lifted decisions go. It sits outside the repository and outside any one agent, and answers questions about your project's decisions over MCP or the API — so the reasoning from a spec is available to whoever asks, on whatever tool, after the plan file is gone. Your specs stay in the project directory where Factory writes them; the shared layer holds the four sentences worth keeping.

Step 1: Create an API key

Generate a key and make your first request in about thirty seconds. Do this before Step 3 above, so you have somewhere to put each decision as you read through the plan.

Step 2: Upload your first memories

Go through your existing specs — including the ones still sitting in the home directory — and record each real decision with what was chosen, what was rejected, and why. Supporting documents and files go in the same place; turning project docs into AI memory covers doing this in bulk without rewriting.

Step 3: Connect your AI & agents

Give Droid, Claude, Codex, and your other agents access over MCP or the API. The next Spec Mode session starts already knowing what the last five decided, which is the difference between planning and re-planning.

The first change is that a plan is reviewable by the people it affects. It is in the repository, on a branch, in a diff. The implementer of step four reads it without asking anyone for a file.

The second is that Spec Mode gets better inputs. Droid researches the repo before proposing a plan, so a repo containing the last few plans and a queryable record of past decisions gives it more to work from than a repo containing neither.

The third is that specs stop accumulating. Once the durable content has been lifted out, deleting a shipped plan is free, and a directory of in-flight plans stays small enough that people read it.

The fourth is that the plan survives the laptop. A home-directory path is per-machine, which is the same asymmetry behind Claude Code forgetting things across machines — and the same fix applies: put the shared thing where the repository or a shared service holds it, not where one machine does.

The fifth is that handoffs get shorter. Half of what sharing context between sessions is trying to solve is someone re-deriving a decision that was already made carefully, once, in a document nobody else could see.

Set specSaveDir in the project settings, not your user settings. Where specs live is a property of the project. A user-level setting points at a path that may not make sense in the next repository you open.

Verify the path on the first run. The documented note about this setting concerns ~ expansion. Check what you actually get before you depend on it.

Commit in-flight specs, retire shipped ones. A plan for merged work is a description of a system that has since changed.

Lift decisions out before archiving. Three or four sentences per spec. This is the whole job, and it is what makes deletion safe.

Keep specs out of your instruction files. AGENTS.md is loaded every session. A finished plan does not belong in every session.

Use settings.local.json for machine-specific preferences. It merges over the shared file at the same level and is meant to be gitignored, which keeps the shared spec path shared.

Consider defaulting the repository to Spec Mode. Setting the interaction mode to spec makes planning the default posture on work where that is what you want.

Migrate off .droid.yaml. It is documented as an older configuration surface, and the .factory/ files are the current one.

Factory documents a persistent spec store controlled by a single setting, specSaveDir, defaulting to a directory in your home folder. Spec Mode itself is read-only planning that researches the repository and stops for human approval, recommended for architecture changes, migrations, and security-sensitive work. Put those two facts together and the default configuration writes your team's most carefully reasoned document to the one place your team cannot see.

Changing the path takes one line. The part that pays off is the habit that follows: commit the plans that describe work in flight, retire the ones that describe work already shipped, and before you retire one, lift out the three or four decisions inside it that will still matter next year. Do that and Spec Mode becomes what it looks like on paper — a machine for producing good decisions your team keeps, rather than good decisions one laptop keeps.