Manifest creation
A manifest captures the foundational identity of a product or initiative: values, principles, goals, and system-wide non-functional requirements. Agents use manifests to align suggestions with project intent.
Use this loop when adding a focused manifest for a specific concern (e.g. API design principles, accessibility standards, security posture). For a new initiative with no manifests yet, use starspec/agents/starscribe/brainstorm.create instead — it produces manifests as part of a broader discovery session.
Dependency Check
Before starting:
- Check
content/manifests/— does a manifest for this concern already exist? If so, extend it rather than creating a duplicate. - Review existing manifests to avoid contradicting established values or principles.
Phase 1 — Scope and Purpose
Ask:
- What concern or initiative does this manifest cover?
- Who are the primary readers — developers, product team, AI agents?
- Is this a product-wide manifest or scoped to a specific domain or initiative?
Name the manifest now: {name}.manifest.mdoc under content/manifests/.
Phase 2 — Values
Values are the non-negotiable beliefs that guide every decision.
Ask:
- What must never be sacrificed, even under deadline pressure?
- What does this project stand for that competitors do not?
- Are there values from existing manifests that apply here too? Reference them; do not duplicate.
Distill into value entries: short uppercase id, descriptive label, one paragraph explaining the value and why it matters to this project specifically.
Phase 3 — Principles
Principles are rules of thumb derived from values — they translate “what we believe” into “how we decide”.
Ask:
- What architectural, design, or process constraints follow from the values?
- What past mistakes should become standing rules?
- Are there principles from existing manifests that extend naturally here?
Distill into principle entries with the same id/label pattern.
Phase 4 — Goals
Goals are measurable outcomes that define success.
Ask:
- What does success look like — what is observable when this manifest’s intent is fulfilled?
- Are there phased goals (near-term vs. later)?
- Can each goal be linked to a milestone later?
Assign short ids (G1, G2, …), a label, and initial status="pending".
Phase 5 — Non-Functional Requirements
NFRs capture system-wide constraints that all features must respect.
Ask:
- Are there performance, security, accessibility, or reliability constraints?
- Are any hard constraints (
must) vs. aspirational (should)?
Write as requirement entries with priority and appropriate tags. These are referenced from design rules using ref="manifest/{id}#id".
Phase 6 — Draft & Confirm
Present the complete manifest draft for confirmation before writing.
Output: content/manifests/{id}.manifest.mdoc
Do’s and Don’ts
Do:
- Check for existing manifests covering the same concern before creating a duplicate
- Review existing manifests to avoid contradicting established values or principles
- Distill raw statements into structured entries with short ids and descriptive labels
- Link NFRs to specific manifest entries via
ref=attributes - Present the full draft for confirmation before writing
Don’t:
- Don’t duplicate values or principles already captured in another manifest — reference them instead
- Don’t create a manifest for a brand-new initiative; use the brainstorm loop first
- Don’t write NFRs that cannot be verified in code review or tests
- Don’t skip the existing-manifest check in the dependency phase
- Don’t assign the same short id to multiple entries within the document
Definition of Done
- Draft presented to user for confirmation
- Document written as
content/manifests/{id}.manifest.mdocwith correct frontmatter and root tag - Values, principles, and goals have unique short ids and descriptive labels
- NFRs have priority and appropriate tags
- No contradictions with existing manifests
- All cross-references resolve to existing documents
pnpm compilesucceeds