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 — 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.

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 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.

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 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.

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

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.

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.

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.

Next steps

• Drift and reconcile — how foundations keep later specs honest.
• The workflow — the per-change spine foundations sit under.
• Commands — every foundation command, CLI and slash.
• Best practices — keep the constitution current, commit .forge/.