A project, end to end

Every other page in this guide explains one part. This one follows a single project through all of them, in order, so you can see how the parts hand off to each other: an empty repo, a conversation about what to build, documents that get more specific until they are executable, and then an engine that executes them while you do something else.

The example is a tenant usage dashboard — the same feature the agent pages use — so you can watch one idea become a requirement, then a story, then a commit. Commands are exact; the documents are shortened to what matters at each step.

Read this once, then use the reference pages

This is the shape of the process. Workflows has the detail on each phase, and the epic engine has the detail on the last step.

---

1. Install into the repo

cd your-repo
npx @engineering11/e11-foundry install

The installer asks which IDE agents you use and which modules you want, then writes .foundry/ into the repo — skills, agents, config — and registers the project so the dashboard can find it later.

Two things worth knowing straight away:

• .foundry/ and .foundry-output/ are gitignored. Everything Foundry produces is local to your checkout unless you deliberately commit it.
• The target repo is where the code lands. Planning documents can live in another repo, and often do; only the repo that will receive the code needs the install.

Check it took:

npx @engineering11/e11-foundry epic dashboard --all-projects

Nothing to show yet — no runs, no documents. That is the point of opening it now: everything below appears here as you go.

---

2. Start the conversation, not the document

Invoke E11 Master in your IDE agent and say what you are trying to build. It routes you to a workflow rather than asking you to pick one:

Build a V2 React client library for our platform — typed contracts,
generated API client, no runtime dependency on the V1 tree.

You do not need to know that this is "phase 1 analysis". Master picks the workflow; the numbered phases exist so it can reason about order, not so you have to memorise them.

If you are ever unsure what to do next, e11-help answers that specific question.

---

3. Analysis and the PRD

The PRD workflow interviews you and writes the document. It lands in:

.foundry-output/planning-artifacts/prds/prd-<project>-<date>/prd.md

It carries numbered functional requirements, each stated as something checkable rather than a wish:

FR-4: Usage totals are aggregated per tenant per billing period from the metering event stream. Recomputing a closed period is deterministic and produces identical output.

That specificity is what makes the later steps possible. A requirement that cannot be checked cannot become a story with acceptance criteria, and a story without testable acceptance criteria is rejected by the plan compiler in step 6.

The PRD folder also collects the addenda and reconciliation passes — addendum.md, reconcile-architecture.md — so the record shows where the plan changed its mind, not just where it ended up.

---

4. Architecture

The architecture workflow reads the PRD and produces a spine: the decisions every story must share, numbered AD-1, AD-2, and so on.

.foundry-output/planning-artifacts/architecture/architecture-<project>-<date>/ARCHITECTURE-SPINE.md

A spine is not a design document for the whole system. It fixes the invariants — the paradigm, the conventions, the boundaries — and deliberately leaves per-story detail open. Stories that later contradict an AD are a conflict to surface, not a local decision to make.

---

5. Epics: where the plan becomes work

The epics workflow reads the PRD and the spine and produces the story breakdown. This is the document the engine executes, so its shape matters more than any other:

.foundry-output/planning-artifacts/epics.md

Its frontmatter records what it was derived from, which is how the trail stays intact:

---
stepsCompleted: [1, 2, 3, 4]
inputDocuments:
  - .foundry-output/planning-artifacts/prds/prd-…/prd.md
  - .foundry-output/planning-artifacts/architecture/architecture-…/ARCHITECTURE-SPINE.md
---

And each story states its dependency and its acceptance criteria:

### Story 1.4: Usage rollup job

**Depends on:** 1.2

**Acceptance Criteria:**

- **Given** a billing period containing metering events,
- **When** the rollup job runs,
- **Then** each tenant has exactly one usage record for that period.
- **And** re-running the job for a closed period changes nothing.

Depends on: is the whole graph. The engine runs stories in authored order and refuses to start a story whose dependency did not complete, so getting these edges right is the difference between an epic that runs unattended and one that stalls on story three.

---

6. The overlay: how the engine will judge the work

One more file, next to the epics file, and the engine will not trust anything else:

# epic-run.yaml
schemaVersion: 1
epic: "1"

# Runs once in the bare run worktree, controller-observed,
# before any worker spends a token.
setup:
  - id: install
    argv: [pnpm, install]

# The engine re-runs these itself per story and trusts only
# the exit codes it observed.
verification:
  - id: test
    argv: [pnpm, turbo, test]

This is the most important idea in the engine. A worker reporting "tests pass" is a claim; the engine re-runs verification itself and records the exit codes it saw. A story is done because the controller observed it, never because a model said so.

---

7. Preflight — free, and always worth it

npx @engineering11/e11-foundry epic plan epics.md --epic 1 --config epic-run.yaml

plan spawns no agents and costs nothing. It compiles the graph and prints it: serial order, per-story dependencies, the verification commands, and two guarantees — the sprint board is read-only, and your target branch is untouched.

Fix input problems here. A story with untestable acceptance criteria, a dependency cycle, a typo in a Depends on: — all of them surface now rather than forty minutes into a run.

---

8. Run it

npx @engineering11/e11-foundry epic run epics.md --epic 1 \
  --config epic-run.yaml --runtime claude

Before the first worker spends anything, the engine checks the environment can do the work at all, cheapest check first: the skills are installed, the runtime answers a one-turn prompt, setup runs, and the verification battery runs once against the fresh worktree. A missing tool or a runtime version the project cannot use stops the run here, for nothing — rather than failing every story in turn, each after paying for a worker.

Then it works through the stories. Each one gets its own worker in a dedicated git worktree on e11/epic/<run-id>; your branch is never touched.

Expect this to take hours. That is the point — go and do something else.

---

9. Watch it

npx @engineering11/e11-foundry epic dashboard --all-projects

The rail on the left lists every project on your machine with what it is doing. Open the run and you get the story pipeline, the live worker transcript, per-story spend, the diff, and the evidence behind every gate.

The Planning section is the documents from steps 3–5, rendered — so the PRD that a story came from is one click from the story itself. That matters at review time more than it sounds: the question "why does this story exist" has an answer on the same screen.

From the terminal, epic status <run-id> --follow streams the same events, heartbeats included.

---

10. When a story fails — because one will

Some story will fail. That is normal for unattended work, and the engine's job is to tell you which kind of failure it was, because the recovery differs:

What you see	What it means	What to do
attempts exhausted	The worker tried and could not finish	Read the transcript; usually the story is too big — split it
worker timed out	A clock verdict, not a verdict on the work	retry --worker-timeout-ms with a bigger budget, then resume
controller-observed verification failed	The code landed; the check failed	Fix the environment, then retry --verify-only — no new worker window
blocked: <condition>	A human decision is genuinely needed	Answer it in the epics file, then retry and resume
delivery refused: … lacks code:write	A permissions boundary, not a defect	See capabilities

And if you simply finish the story yourself — which is common and fine:

npx @engineering11/e11-foundry epic adopt <run-id> --story 1.4
npx @engineering11/e11-foundry epic resume <run-id> --runtime claude

adopt does not take your word for it. It runs the project's verification at your revision and refuses if it fails. The story is recorded as adopted — your delivery that the engine checked — and the promotion gate says so, because that is a different claim from one the engine produced.

---

11. The promotion gate

A completed epic parks at waiting_promotion. Nothing merges automatically.

npx @engineering11/e11-foundry epic approve <run-id>

Before you approve, epic-result.json and the gate tell you three things worth reading:

• What shipped per story — files, commits, line counts, and the exit codes the controller observed itself.
• The independence report — which story pairs touched overlapping files, in one plain sentence.
• Activation still owed — work that merging does not make live, because another story or a runbook owns it. "Merging makes X and Y live; Z still needs story 3.2's index deploy."

Approving records the decision. Merging and pushing stay yours.

---

What you have at the end

A branch with the work, and a trail that explains it: a PRD with numbered requirements, an architecture spine with numbered decisions, an epics file that cites both, an immutable plan snapshot, an append-only ledger of every transition, per-attempt worker transcripts, and the controller's own exit codes for every gate.

Six months later, "why is this code like this" has an answer that does not depend on anyone remembering.

---

Next

• The epic engine — dependencies, cost control, recovery, capabilities
• Quick flow — the same loop for a single change, without the ceremony
• Recipes — starting points for specific situations
• Troubleshooting — when something is wrong rather than merely failing