Concepts

Foundry is four things working together. Once you have these in your head the rest of the guide makes sense.

1. Skills

The single unit of everything in Foundry. A skill is a directory your AI tool reads natively:

• SKILL.md — the instructions. Frontmatter (name, description) tells your tool when to surface it; the body is what the model executes.
• customize.toml — the skill's data surface: everything about the skill you're meant to be able to change, declared as TOML defaults you can override per project.
• Optionally steps/, templates, checklists, and reference files the skill loads just-in-time.

Agents, lifecycle workflows, and anytime tools are all skills — same format, same invocation, same override mechanism. You invoke one directly (skill:e11-prd, skill:e11-knowledge sdk:auth) or through an agent's menu.

2. Agents

Agents are skills with personas and menus. Eight ship with Foundry: E11 Master (the entry point and router), E11 Bootstrapper (scaffolding), and six role agents — Analyst, PM, UX Designer, Architect, Dev, Tech Writer. The full catalog is in 01-agents/.

Every agent runs the same eight-step activation protocol from its SKILL.md: resolve its [agent] block through the customization layers, adopt the persona (role, identity, communication style, principles), load persistent facts and central config, greet you, and present its menu. Because the persona, facts, and menu are all data in customize.toml, you can reshape any agent without touching Foundry files.

An agent's menu items dispatch to other skills — Dev's [DS] runs e11-dev-story, PM's [PR] runs e11-prd. The agent is the persona; the skills do the work.

3. Workflows and phases

Lifecycle skills are grouped by delivery phase. A multi-stage workflow keeps its procedure in numbered step files (steps/step-NN-*.md) that the agent reads one at a time — deterministic enough to be repeatable, structured enough to survive being paused and resumed.

Phase	What happens	Folder
1 — Analysis	Research, product briefs, PRFAQ	1-analysis/
2 — Planning	PRD and UX design	2-plan-workflows/
3 — Solutioning	Architecture, epics and stories, readiness check	3-solutioning/
4 — Implementation	Story dev, code review, sprint skills, quick flow	4-implementation/
5 — Scaffold	Bootstrap wizard + scaffolds for new repos and SDKs	5-scaffold/

Anytime tools (help, knowledge, refine, the review finders, shard/index, customize, …) live outside the phases and are available from any agent at any point. See the phase map.

Ceremony is a dial, not a mandate: e11-dev-flow handles small work in one pass (with an oneshot mode for tiny changes), e11-prd has a batched fast path, e11-dev-auto runs unattended, and the full lifecycle is there when the work warrants it. See Quick flow.

4. Alloy

Alloy is the knowledge corpus every E11-aware skill consults before making a platform-touching decision. It's a separately-versioned npm package, @engineering11/alloy, that you install in your project (the Foundry installer wires it for you). The e11-knowledge skill resolves each query through a ladder - MCP tools, the pinned cache, then node_modules/@engineering11/alloy/ - deriving layout and vocabulary from the corpus manifest.

Alloy organises E11 platform knowledge under sources/ (one namespace per source repo - sdks-nodejs holds backend-apis/, sdks/, microservices/; sdks-react and engineering11-platform hold their own) and shared/ (curated categories: foundation/, patterns/, conventions/, infrastructure/, integrations/), plus top-level meta/. The exact categories live under whichever view the repo pins - discover them from the manifest rather than assuming a fixed layout.

Skills don't read alloy files directly. They go through skill:e11-knowledge with a query key:

sdk:auth                       → sources/sdks-nodejs/sdks/auth/index.md
sdk:auth:backend-using         → sources/sdks-nodejs/sdks/auth/backend-using.md
api:datastores                 → sources/sdks-nodejs/backend-apis/datastores/index.md
pattern:multi-tenancy          → shared/patterns/multi-tenancy.md
convention:react-conventions   → shared/conventions/react-conventions.md
matrix:unit                    → meta/unit-matrix.yaml
list:sdks                      → sources/sdks-nodejs/sdks/index.md

When an alloy doc is missing, the skill falls back to pointing at the package source under node_modules/@engineering11/<pkg>/src/. When skills use alloy content, they cite the resolved path - e.g. alloy://sources/sdks-nodejs/sdks/auth/backend-using.md - so you can verify any claim.

See 04-knowledge-layer.md for the full query-key reference and citation rules.

Customization, in one paragraph

Every customizable skill resolves its customize.toml surface through three layers at activation: skill defaults ← your team's .foundry/custom/<skill>.toml ← your personal .foundry/custom/<skill>.user.toml. Override files are sparse — only the fields you're changing — so updates never clobber your intent. The e11-customize skill ([CF]) authors overrides conversationally. Full mechanics: Customization.

How they fit together

You ─► Invoke a skill (or an agent that dispatches one) ─► Skill consults e11-knowledge ─► Alloy
                     │
                     └► Artifacts land in planning-artifacts/ or implementation-artifacts/

A concrete trace, "ship a story":

1. You run e11-create-story ([CS]) — it drafts a story under {implementation_artifacts}/ with the full context Dev needs, including which @engineering11/* SDKs the story touches.
2. You run e11-dev-story ([DS]) — before writing code it pre-loads the alloy docs for every capability and SDK the tasks need, then implements task by task with tests green before any checkbox.
3. In a fresh session you run e11-code-review ([CR]) — five review layers in parallel (including the alloy citation auditor), findings triaged into decision-needed / patch / defer / dismiss.

Every platform-touching decision in that chain carries an alloy:// citation, and every behavior in it — templates, review layers, pre-load gates — is data you could have overridden from .foundry/custom/.

Next

→ Glossary for the precise terms · Agent quick-reference for the catalog.