Part I · What Foundry is
Concepts — the mental model¶
Foundry is built around a small set of concepts that repeat everywhere in the product: Products move through a Lifecycle made of Phases; phases produce Artifacts and are worked by Agents; delivery happens in Epics and Features, and every build attempt is a Run. Alongside the lifecycle, every product keeps Records — decisions, tech debt, bugs, ideas, and screens — as citable registers.
Once you can place these eight concepts, every screen in Foundry is self-explanatory. This page defines each one: what it is, why it exists, and where it lives in the UI.
flowchart LR
PROD[Product] -->|follows one| PDLC[Lifecycle]
PDLC -->|defines| PH[Phases]
PDLC -->|staffs| AG[Agents]
PH -->|each produces| ART[Artifact]
AG -->|work| PH
PROD --> EPIC[Epics]
EPIC --> FEAT[Features]
FEAT -->|built by| RUN[Runs]
PROD --> REC[Records registers]
Products¶
What it is. The thing you are building. A product owns a git repository, a team, its knowledge registers, and exactly one lifecycle.
Why it exists. Everything in Foundry is scoped: agents work inside a product, artifacts belong to its phases, decisions land in its registers, runs push to its repo. The product is the unit of ownership and the boundary of context — nothing leaks between products.
Where it lives. The product picker at /products is the front door after login. Selecting a product opens the product shell — sidebar navigation over Overview, Mission Control, epics, knowledge registers, and product configuration (repo and branch, team, providers and agents, design system, dev environment, preview).
Honest note. Mission Control is a real page, but its sidebar entry carries a "COMING SOON" badge today — the badge marks the not-yet-shipped Missions concept, not the page (see Mission Control).
Lifecycle (PDLC)¶
What it is. The recipe for how a product gets built: which phases exist, in what order, which agent works each phase, and what artifact each phase produces. In Foundry the lifecycle — the Product Development Lifecycle, PDLC — is data, not code. Phases, their connections, artifact schemas, and agent rosters are all rows you can edit.
Why it exists. Every organization has its own delivery discipline. A hardcoded pipeline would force yours out; a configurable one lets a regulated enterprise encode its stage gates, vocabulary, and review culture directly. Lifecycles are defined at the instance level and are reusable: several products can follow the same lifecycle. Foundry ships a built-in default; built-ins are protected, so tailoring means forking — you never start from a blank page, and you never mutate the shared default. Even the tier vocabulary is data: what the default lifecycle calls "Epic" and "Feature" can be renamed per lifecycle.
Where it lives. The Lifecycle Studio: /pdlcs lists lifecycles; each opens onto a drag-and-drop canvas showing phases and their connections, plus roster views for the lifecycle's agents and artifact schemas. A product picks its lifecycle in product settings.
Phases¶
What it is. One step of the lifecycle — the default lifecycle runs Vision, Architecture, Business Spec, UX, IT Spec, Plan, and Execute. Each phase belongs to either the container tier (epic-level work like vision and architecture) or the delivery tier (feature-level work like specs, planning, and execution).
Why it exists. Phases are where structure replaces chat scroll. Each phase has a clear owner (an agent), a clear output (an artifact), an explicit approval, and a record of what upstream context it consumed — so when an upstream artifact changes after approval, downstream phases can be flagged as stale rather than silently drifting.
Where it lives. The lifecycle bar in the epic and feature workbenches shows the phase sequence and status; clicking a phase opens its chat and artifact canvas. Phase types themselves are edited on the Lifecycle Studio canvas.
Artifacts¶
What it is. The document a phase produces — a vision, an architecture, a business spec, a plan. Artifacts are schema-driven: their sections and fields are declared as data (JSON Schema), and content is validated against that schema on every write.
Why it exists. Structured artifacts are what make agent output consumable by the next phase and reviewable by a human. Because the schema is data, an organization can reshape what "an architecture document" means for its lifecycle in the Artifact Designer — without a code change. Every artifact keeps an append-only version history: each agent turn or block of human edits becomes a version, milestones mark significant states, and phase approval pins the exact version that was approved. Edit after approval and the phase is marked drifted, not silently re-blessed.
Where it lives. The artifact canvas inside the epic and feature workbenches is where you read and edit content; the product's "All artifacts" register lists everything; artifact schemas are edited per phase type in the Lifecycle Studio's Artifact Designer.
Agents¶
What it is. An AI role doing a department's work. Foundry ships thirteen behaviours — PM, Architect, Business Analyst, UX Designer, Tech Lead, Planner, Engineer, Reviewer, QA, Dev Lead, Orchestrator, Explore, and Librarian — each a configured agent with its own prompt, model allocation, tool grants, and the phase type it produces.
Why it exists. One general-purpose chatbot cannot hold a department's remit. Splitting the work into roles gives each agent a narrow, auditable job — and gives you a roster you can staff deliberately. The Engineer behaviour additionally comes in four seniority tiers — junior, mid, senior, expert — which are model allocations of the same behaviour, not separate agents: routine tasks route to cheaper models, critical tasks to the strongest, with automatic escalation when a tier gets stuck.
Where it lives. Each lifecycle has its agent roster in the Lifecycle Studio (/pdlc/:id/agents), with a full editor per agent for prompts, model, thinking level, and tool grants. Separately, one generic Copilot powers every non-lifecycle assist surface (onboarding interviews, prompt-editing help, the side panel); it is configured once, in Instance Settings.
Runs¶
What it is. One attempt at building a feature: a branch, an agent team, and a live scoreboard of tasks, costs, and findings. Runs are versioned per feature, comparable, and disposable.
Why it exists. Agentic execution should be cheap to retry and safe to judge. Instead of one fragile pipeline, Foundry treats each execution as an immutable, versioned entity: start a fresh run and it gets the next version number and its own branch; discard a run and its resources are freed while the branch stays on the remote, read-only, for audit. When several runs exist, you compare them on the scoreboard and select the winner — the rest remain on record.
Where it lives. The Run Cockpit at /features/:id/phases/execute: dispatch, live agent roster with per-agent costs, streaming reasoning, diffs, and the run scoreboard.
Epics and Features¶
What it is. The two delivery tiers inside a product. An epic is a body of work — it carries the container-tier phases (vision, architecture) and decomposes into features. A feature is the unit that gets specced, designed, planned, and built — it carries the delivery-tier phases through to execution.
Why it exists. The split keeps strategic context (why are we building this, how does it fit the architecture) separate from delivery context (exactly what ships next), while keeping them linked: every feature inherits its epic's approved upstream artifacts. Features can also carry provenance — a feature promoted from an idea in the Ideas register keeps a link back to the record it came from. The tier names themselves are lifecycle vocabulary and can be relabeled per lifecycle.
Where it lives. The EPICS group in the product sidebar; each epic and each feature has its own workbench with the lifecycle bar, phase chats, and artifact canvas.
The knowledge registers¶
What it is. Product-scoped registers for knowledge that is not a lifecycle artifact: Decisions, Tech debt, Bugs, Ideas, and Screens. Each record gets a stable, citable ID per product and kind — AD-11 means the same thing forever.
Why it exists. This is the traceability spine. Agents create records as they work — a dev lead recording an architectural decision mid-run, provenance stamped automatically as agent-authored — but sign-off is human: a decision carries who decided and when, and superseding a decision links the chain rather than rewriting history. Records deliberately skip the phase/approval machinery of artifacts; they are registers, not documents in flight.
Where it lives. The PRODUCT KNOWLEDGE group in the product sidebar: Screens, Decisions, Tech debt, Bugs, Ideas — plus Domain knowledge and All artifacts. The full treatment is in Decisions & ideas.
Honest note. Domain knowledge is currently a staged draft view with an honest empty state; it lands with the Artefact Store epic.
Where to go next¶
With the vocabulary in place, the Architecture overview shows how these concepts are implemented — the runtime chain, the data layer, and the execution machinery underneath the Run Cockpit.