Foundation Specs
Foundation specs describe the scaffolding code that has to exist before per-feature work begins — the minimum substrate that lets a developer run the app, write a user-story feature spec, and have it land on real patterns rather than vapor.
See .forge/forge-harness-framework.md §4.10 for the full doctrine — the elaborated discipline
rule and the worked tooling-vs-instance table live there, deliberately not restated here (the
two copies had already started drifting when this pointer replaced the restatement).
The Two Rules, in Brief
Foundation = anything required to run the app and write a user-story feature spec against it. If it has user-visible behavior with its own flows and edge cases, it is a feature, not foundation.
And when a slice is borderline: the substrate is foundation; the first instance ships with the feature that needs it — migration tooling vs the first table, ORM base classes vs entity models, design tokens vs feature components. §4.10 carries the worked table.
Typical Slice List
architecture.md § Foundation Backlog is authoritative for this engagement’s slices — read it, not this list. This engagement’s backlog is larger than the generic shape below (it added a scheduler substrate, API conventions and a file pipeline; the extension-point substrate and core workflow primitives that the core/domain separation planned were later dropped — AD #29 — and the split itself was collapsed by FS-14 — AD #31), so the numbering here does not match ours.
The generic shape, for orientation only:
- App shell — framework boots, routing skeleton, env config, dev server runs
- Data layer scaffolding — DB connection, migration tooling, repository pattern (no entity migrations yet)
- Design system primitives — design tokens + atomic components
- Build & CI — lint, typecheck, tests, build all green on a hello-world commit
- Observability stubs — logger, error reporter, request tracing wired into the app
- Developer onramp — README + “how to add a feature” guide
Naming Convention
Numeric prefix to enforce build order:
001-app-shell-spec.md
002-data-layer-spec.md
003-design-primitives-spec.md
004-build-and-ci-spec.md
005-observability-stubs-spec.md
006-developer-onramp-spec.md
Use the same _TEMPLATE-spec.md template as feature specs (one level up). Same lifecycle, same review rigor — the subdirectory exists for visual separation only.
How Foundation Work Happens
- Gate 2 enumerates the foundation backlog in
architecture.md(Foundation Backlog section). - Foundation specs draft — can run in parallel with late Gate 2 polish.
- Foundation plans + implementation — wait for full Gate 2 pass. Each slice runs through the standard spec → plan → implementation → check → review → PR pipeline. Per-step tooling will be introduced as patterns stabilize through real engagement experience; for now these steps run via direct conversation with Claude.
- Manual foundation review — pull all foundation specs and plans into one Claude Code session, walk them critically (optionally
/council). No dedicatedforge-foundation-checkcommand — one-time engagement work doesn’t justify automation. - Capture review outcome in
.forge/engagement-gate-runs.mdas a precondition note for Gate 3. - Gate 3 runs with foundation as a precondition — feature decomposition slices on top of an existing substrate.
Tracker Visibility
Each slice has an entry under setup.foundation.slices in .forge/tracker.yaml. Slice status uses the phase-gate vocabulary the tracker’s own schema comment documents — not-started → spec → plan → dev → done — so a slice row says which artifact it is waiting on, not just that it is “in progress”. Leadership can see “foundation 4/6 done” without opening individual artifacts.
Where Code Lives
Spec under .forge/specs/foundation/ carries the requirement. Code lives in the appropriate code repo:
- ORM base classes → backend repo
- Design tokens + atomic components → frontend repo
- App shell → frontend repo (or backend if API-only)
- CI/build config → wherever the build runs
The harness owns the spec; the repo owns the truth. Same ownership rule as feature work (see framework.md §4.9).