Authoring Manifests

Fragment

reference

Authoring Manifests

The mental model

A manifest is the soul of your project — its values, principles, goals, and system-wide requirements captured in one place. It answers: “What kind of system are we building, what do we believe, and what constraints are non-negotiable?”

Every project has exactly one manifest. It is the document that AI agents and new team members read first to understand the project’s identity and align their decisions accordingly.

Values, principles, and goals — the distinction

These three concepts are often conflated, but they serve different purposes:

Values are beliefs that guide trade-off decisions. They do not change unless the project’s identity changes. They answer: “When two good options conflict, which do we choose?”

Example: “Radical Simplicity” — favor zero-config over flexibility.

Principles are derived rules that operationalize values. They are more specific and may evolve as the team learns. They answer: “How do we apply our values in practice?”

Example: “Local-First” — always store data on the user’s machine before syncing.

Goals are time-bound outcomes the project aims to achieve. They have a status (pending or achieved) and represent concrete milestones of progress. They answer: “What does success look like in the near term?”

Example: “Ship v1” — deliver core feature set to early adopters by Q2.

Non-functional requirements

NFRs in the manifest apply system-wide. They set measurable targets that constrain all implementation decisions:

{% requirement id="response-time" priority="must" %}
The system must respond within 200ms for all read operations.
{% /requirement %}

Good NFRs are:

Measurable — include a number, threshold, or testable condition
Scoped — “all read operations” not “the system should be fast”
Prioritized — use must/should/could to communicate rigidity

Blueprint rules can reference manifest NFRs using ref="manifest/{id}#requirement-id", creating traceability from architecture decisions back to constraints.

When to write a manifest

Write the manifest early — ideally before any features or domains. It provides the decision-making framework that makes all subsequent authoring more consistent. A team without a manifest will make inconsistent trade-offs.

When to update

Update the manifest when:

The project pivots and values no longer reflect reality
New constraints emerge (regulatory, performance, scale)
Goals are achieved or abandoned
The team discovers a principle they have been following implicitly

Do not update the manifest for feature-level changes. If a requirement applies to only one feature, it belongs in that feature, not the manifest.

Structuring content

Order matters for readability:

Values first — they are the foundation
Principles — derived from values
Goals — current targets
Requirements — measurable constraints
Rules — conventions and invariants

Keep each item concise. A value that needs three paragraphs of explanation is probably two values or a principle in disguise.

Common mistakes

Mistake	Why it hurts
Aspirational fluff	”We value quality” says nothing. Values must help resolve real trade-offs.
Unmeasurable NFRs	”The system should be performant” cannot be tested. Always include a threshold.
Feature requirements in the manifest	If it only applies to one feature, it belongs there, not here.
Never updating	A manifest frozen at project inception becomes fiction. Review it quarterly.
Multiple manifests	One project, one manifest. If you need multiple, you might have multiple projects.
Missing goals	Without goals, the manifest is philosophy without direction. Goals ground it in reality.

Evolution

The manifest evolves slowly. Values are nearly immutable; principles shift as the team learns; goals rotate as they are achieved or superseded. When a goal is achieved, mark it status="achieved" rather than deleting it — the history of what you accomplished is valuable context.