Skip to content
AletheIA Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Project-Local Constitution Context

Goal

Explain how a project-local constitution layer can strengthen AletheIA restart packages, clean restarts, and governing-context continuity without turning Constitution into AletheIA core truth.

Why this exists

Some projects accumulate durable context across many files:

  • project state
  • durable decisions
  • design-system doctrine
  • product roadmap
  • active planning material

When that context is too distributed, a clean restart becomes harder.

The restart package may still exist, but the next session may need to rediscover:

  • what currently governs the product direction
  • which docs are still authoritative
  • what changed during replanning

A project-local constitution layer can reduce that burden.

Core boundary

AletheIA does not require a Constitution abstraction in the framework core.

Instead:

  • the framework defines the need for governing context
  • each project may define a thinner local constitutional bootstrap if it helps

This means Constitution remains:

  • optional
  • project-local
  • delivery-context specific

It should not become mandatory framework vocabulary before repeated cross-project evidence exists.

What a project-local constitution should do

At minimum, a useful local constitution layer should:

  1. reduce bootstrap sprawl for a new slice
  2. summarize the most durable project direction
  3. point back to deeper source docs
  4. strengthen clean-restart alignment after replanning

A project-local constitution is healthy when a new human or agent can read:

  • one constitution index
  • one active slice doc

and start productively without transcript replay or broad repo rediscovery.

A small project-local constitution may include:

  • index — one-shot bootstrap entrypoint
  • mission — what the project is for and what it should not drift into
  • stack — durable technical baseline
  • design-system — interface doctrine when relevant
  • roadmap — durable active directions

This layer should stay reference-first:

  • short canonical summary
  • explicit links to deeper docs
  • no attempt to absorb all project knowledge into one new truth file

Relationship to slice finalization

When a project uses local constitution context well:

  • restart packages stay smaller
  • governing-context refs become easier to choose
  • replanning deltas become easier to express
  • clean restart becomes safer

A healthy local ordering often looks like:

  1. active slice doc
  2. constitution index
  3. deeper decision/state/changelog refs as needed

The exact order remains project-local.

What this does not imply

This guide does not imply:

  • Constitution is now an AletheIA core contract
  • all projects need a constitution layer
  • the framework should absorb Brownfield/Greenfield mode now
  • restart quality depends on a special file name

The framework still only requires:

  • compact restart packages
  • explicit governing-context continuity
  • clear project-local separation between reusable framework logic and local truth

When to consider this pattern

Consider a local constitution layer when:

  • restart packages repeatedly need too many project refs
  • replanning changes direction often enough that drift becomes visible
  • the same project bootstrap context is reconstructed over and over
  • a project is large enough that PROJECT_STATE + DECISIONS alone are no longer a clean bootstrap

Avoid introducing it too early when:

  • the project is still small
  • direction changes are still local and temporary
  • one active slice doc already gives enough context
  • docs/slice-finalization-and-restart.md
  • starter-pack/templates/slice-finalization-review-template.md
  • starter-pack/templates/restart-bootstrap-prompt-template.md
  • docs/project-extension-pattern.md

Was this page helpful?