Upgrading Foundry

Foundry's agents are skills, the planning workflows are consolidated, and all customization lives in layered TOML overrides. If your project's install predates that shape, the upgrade is designed to be one command; this page tells you what that command does to an older install, and the short list of things only you can do.

Upgrading

npx @engineering11/e11-foundry install

The installer detects an older install (compiled agent .md files + .foundry/_config/ manifests) and upgrades it in the same run:

1. Compiled agents retire — every compiled agent whose replacement agent-skill is installed is deleted from your tool directories (.claude/skills/, etc.). The agent-skill directory takes its place. Nothing is deleted until its replacement is actually present.
2. Stale skills are removed — renamed/retired skill directories are cleaned from tool dirs via the shipped removals list.
3. customize.yaml → TOML translation — per-agent <agent>.customize.yaml files from older installs are translated, best-effort, into .foundry/custom/e11-agent-<role>.toml overrides:
   • memories: → persistent_facts
   • critical_actions: → activation_steps_prepend
   • menu items → [[agent.menu]] entries (codes derived from triggers; workflow: paths become prompt text, exec: skill:x becomes skill)
4. A migration report prints in the install summary listing everything translated and — more importantly — everything that couldn't be, so nothing is dropped silently.
5. Config answers survive. Your existing config.yaml answers are preserved and partitioned into the central config (.foundry/config.toml team scope, .foundry/config.user.toml user scope).
6. Idempotent. Running install again skips everything already migrated and never overwrites hand-authored or previously-translated overrides.

What lands where (the current layout)

.foundry/
  config.toml            ← central config, team scope (installer-owned)
  config.user.toml       ← central config, user scope (installer-owned, gitignored)
  custom/                ← YOUR overrides — never touched by the installer
  scripts/               ← resolve-customization.mjs, resolve-config.mjs, memlog.mjs
  foundry/config.yaml    ← runtime module config (kept)

Renamed skills (shims, one release)

Six old names forward to their consolidated replacement with the right intent, announce the deprecation once, and disappear in the next major release. Update saved prompts and docs now:

Old name	Current skill (intent)
e11-create-prd	e11-prd (Create)
e11-edit-prd	e11-prd (Update)
e11-validate-prd	e11-prd (Validate)
e11-create-product-brief	e11-product-brief (Create)
e11-create-ux-design	e11-ux (Create)
e11-create-architecture	e11-architecture (Create)

Two names kept working with no shim needed — same skill name, new engine inside: e11-spec-flow and e11-dev-flow. Existing skill:e11-spec-flow / skill:e11-dev-flow invocations behave as before, minus ceremony.

Menu codes that moved with the consolidation: PRD is [PR] (was [CP]/[VP]/[EP] — one code, three intents), UX design is [UX] (was [CU]), architecture stays [CA].

Retired names

Retired	Replacement	Details
sm agent	e11-sprint-planning [SP] · e11-sprint-status [SS] · e11-create-story [CS]/[VS] · e11-retrospective [ER] · e11-correct-course [CC] (also on PM's menu)	SM page
qa agent	e11-qa-generate-e2e-tests [QA] directly; review duties → e11-code-review layers	QA page
flow-solo-dev agent	e11-spec-flow + e11-dev-flow invoked directly (or Dev's [DF]); e11-dev-auto for unattended	Solo Dev page
compiled-agent pipeline	agents-as-skills	No YAML compile step exists anymore; agent identity is read-only in SKILL.md, everything else is customize.toml data

What you must do by hand

The migration report is your checklist. Specifically:

1. Review every translated override. The translation is best-effort — open each .foundry/custom/e11-agent-<role>.toml it wrote, run the resolver (or [CF] e11-customize in audit mode), and confirm the merged result is what you meant.
2. Re-check principles overrides — semantics changed. In older installs, a principles block in customize.yaml replaced the shipped principles. Today, principles (like all plain arrays) appends to them. If your old principles were written to override shipped behavior, rewrite them as explicit counter-rules or move the intent to persistent_facts/activation_steps_prepend. The report flags every translated principles block for exactly this reason.
3. Deal with the unmappable, reported items:
   • Agent display name — read-only (it lives in SKILL.md, not the customize surface).
   • prompts[] — no equivalent; convert useful ones into [[agent.menu]] items or persistent_facts.
   • sm / qa / flow-solo-dev customizations — their agents no longer exist. Port workflow-shaped bits to the replacement skills' [workflow] overrides (e.g. story conventions → .foundry/custom/e11-create-story.toml).
4. Commit the team layer. .foundry/custom/*.toml (non-.user) belongs in git. The installer's .gitignore handling excludes the .user.toml files, including rewriting a legacy bare .foundry ignore so custom/ can be tracked.
5. Retrain muscle memory on the consolidated codes ([PR], [UX]) and the retired-agent replacements above. e11-help ([BH]) knows the current catalog.

Verifying the upgrade

npx @engineering11/e11-foundry status   # modules + layout (scripts, central config, overrides)
node .foundry/scripts/resolve-config.mjs --project-root . --key agents   # roster landed?
node .foundry/scripts/resolve-customization.mjs --skill .claude/skills/e11-agent-pm --key agent   # overrides resolve?

If skills are missing from your tool after upgrade, see Troubleshooting.

See also

Customization (the override model your customize.yaml was translated into) · Agents quick-reference · Quick flow.