# Foundation phases Most Forge phases describe a single **change**. Five do not. The **foundation phases** — `constitution`, `security`, `infra`, `brand`, `design` — establish **standing project truth**: the ground rules every later change operates within. You run them **once**, early, before the per-change spine gets busy. This page explains what each one establishes, where it writes, why it comes first, and the one place a foundation phase reaches forward and grips the rest of the workflow. ## Run once, then build on top The [SDD spine](/guide/workflow) — `explore → propose → specify → clarify → plan → tasks → implement → verify → archive` — runs **per change**. The foundation phases are different in kind. They are not steps in a change; they are the context a change is measured against. Set them first, and every change that follows inherits them. ```mermaid flowchart LR subgraph Foundation["Foundation (run once)"] K[constitution] S[security] I[infra] B[brand] D[design] end Foundation --> Spine subgraph Spine["Per-change spine (run every change)"] E[explore] --> P[propose] --> SP[specify] --> Mid[… clarify · plan · tasks · implement …] --> V[verify] --> A[archive] end ``` ::: info Foundations are context, not ceremony A foundation phase does not gate a change the way `verify` does. It supplies the **standing truth** — principles, posture, baseline, identity, system — that `specify`, `plan`, and `analyze` read from. Skip them and later phases have nothing to check against; set them and the whole spine gets sharper. ::: ## Scaffold them from the `forge init` wizard The interactive `forge init` wizard has a **Foundation** step: a checklist of these same five phases, asking which ones to scaffold now. `forge init` cannot run an interactive slash command itself — each phase gathers project context from you before it writes anything — so checking a box does not draft the file during `init`. Instead, once the wizard finishes, `forge init` prints the exact `/forge.*` command for every phase you checked, ready to run immediately after. Leave one unchecked and run its command later, whenever you actually reach it — nothing about the checklist is binding. ## The five phases Only two of these phases — `brand` and `design` — have deterministic `forge` seed commands. The other three (`constitution`, `security`, `infra`) are authored entirely through their `/forge.*` agent slash-commands; there is no `forge constitution`, `forge security`, or `forge infra` terminal command. See [Commands](/guide/commands) for the full surface. ### Constitution `/forge.constitution` defines the project's **non-negotiable principles and constraints** — the articles every change must respect. Modularity, test-first, simplicity, observability, the technology choices you refuse to relitigate. It is the most load-bearing artifact Forge holds, and the only foundation phase that reaches into scoring — see [The constitution caps your score](#the-constitution-caps-your-score). ### Security `/forge.security` defines the project's **security posture** — the baseline that declares what authentication, authorization, rate-limiting, and secrets handling every flow must satisfy. This is the advisory half of Forge's security story. The enforcing half is the [`forge secscan`](/features/review) gate, which statically scans a change's files for leaked secrets, PII, and prompt-injection strings and returns a non-zero exit on unwaived findings. The baseline says what "secure" means; the gate refuses to bless a change that violates it. ### Infra `/forge.infra` defines the **infrastructure baseline** — the standing spec for development, production, CI/CD, observability, and disaster recovery. It is the source of truth deployment files derive from, not the other way around. Once set, any change that assumes a service, environment, or capability the baseline does not declare is drift the reconciler can catch. ### Brand `/forge.brand` defines **brand identity and voice** — the color palette, typography, spacing scale, and design tokens the product speaks in. The CLI seeds it: `forge brand` writes `.forge/design/brand.md` if it does not already exist, then your agent authors the real content through the slash command. ### Design `/forge.design` defines the **design system** — the component specs, states, accessibility requirements, and token references built on top of the brand. `forge design` seeds both `.forge/design/brand.md` and `.forge/design/design-system.md`. Design references brand, so brand comes first. ::: tip Seeding is non-destructive `forge brand` and `forge design` only seed a file when it is missing — an existing artifact is never overwritten. The **authoring** happens in your agent via `/forge.brand` and `/forge.design`; the CLI just guarantees the file exists to author into. ::: ## What they write under `.forge/` Foundation artifacts are plain files, like everything else Forge tracks. They live under `.forge/` and belong in version control so the whole team shares one standing truth. | Phase | Establishes | Written under `.forge/` | | --- | --- | --- | | `constitution` | Principles and constraints | The project constitution (rendered to `constitution.html` in the dashboard) | | `security` | Security posture / baseline | The security baseline the `secscan` gate enforces against | | `infra` | Infrastructure baseline | The standing infra spec deployment files derive from | | `brand` | Brand identity and voice | `.forge/design/brand.md` | | `design` | Design system | `.forge/design/brand.md` + `.forge/design/design-system.md` | ::: tip Commit `.forge/` Everything under `.forge/` is plain files — **commit it**. When the foundations travel with the repository, every teammate's changes are measured against the same constitution, posture, baseline, and design. See [Best Practices](/guide/best-practices). ::: ## The constitution caps your score The constitution is not just documentation — it is wired into quality scoring. `forge analyze` produces a **100-point** quality score for the current state, and **constitution conflicts are blocking findings that cap that score**. A change that violates a declared principle cannot post a clean number, no matter how polished it is otherwise. That has a direct consequence: a **stale** constitution quietly drags down every assessment. If your principles have moved and the document has not, `analyze` scores your work against yesterday's truth. Revisit the constitution whenever your constraints change, so the score reflects reality rather than drift against an outdated article. ::: warning Keep the constitution current Because constitution conflicts cap the `analyze` score, an out-of-date constitution is not a harmless artifact — it is a standing penalty on every quality assessment. Treat it as living truth, not a one-time formality. ::: ## Foundations feed reconciliation The foundations are also the yardsticks the reconciler measures new specs against. When you write or change a spec, reconciliation checks it for constitution violations, security-baseline misalignment, infrastructure assumptions the baseline does not cover, and brand or design inconsistency — and **constitution violations cannot be deferred**. Set the foundations well and `/forge.reconcile` has something firm to hold every later change to. See [Drift and reconcile](/concepts/drift-and-reconcile). ## Next steps - [Drift and reconcile](/concepts/drift-and-reconcile) — how foundations keep later specs honest. - [The workflow](/guide/workflow) — the per-change spine foundations sit under. - [Commands](/guide/commands) — every foundation command, CLI and slash. - [Best practices](/guide/best-practices) — keep the constitution current, commit `.forge/`.