Project Constitution Skill

Project Constitution Skill

Create or refine a practical project constitution: a short, durable governance artifact that downstream agents and humans can use to make consistent project decisions.

A constitution is not a manifesto, product spec, architecture document, or task plan. It is a decision contract: principles, boundaries, quality gates, memory rules, and routing guidance that remain useful across multiple delivery tasks.

Mode Selection

Select the lightest mode that satisfies the request:

• Create: use when no constitution exists or the user asks for a new governance artifact. Draft a complete constitution and write it only when file creation is requested or clearly implied by the workflow.
• Update: use when the user names an existing constitution path or asks to revise current governance. Read the existing artifact first, then make targeted changes that preserve stable decisions.
• Review: use when the user asks to assess, critique, audit, or identify weaknesses. Return findings and recommendations instead of rewriting files unless the user also asks for edits.

Core Workflow

1. Inspect the available project context before drafting:
   • Read the user's request, product idea, constraints, delivery context, and any named files.
   • Check for existing governance artifacts such as AGENTS.md, README.md, .agentspec/memory/constitution.md, .specify/memory/constitution.md, docs/project/constitution.md, or similar local conventions.
   • Treat AGENTS.md, README.md, ADRs, PRDs, and release checklists as context unless the user explicitly says one of them is the constitution.
   • If updating an existing constitution, preserve stable approved decisions unless the user asks for a rewrite.
2. Separate durable governance from temporary execution detail:
   • Durable: product boundaries, engineering standards, architectural constraints, testing policy, security/privacy posture, release discipline, memory boundaries, and agent routing.
   • Temporary: sprint tasks, implementation steps, speculative stack choices, unresolved preferences, and one-off estimates.
3. Choose the artifact path:
   • Use an explicit user-provided constitution path first.
   • Reuse an existing constitution path when present.
   • Otherwise prefer .agentspec/memory/constitution.md.
   • If the user only asked for advice or review, return the draft/review in chat instead of writing a file.
4. Draft or revise the constitution using assets/constitution-template.md as the default structure.
5. Make every principle pass the decision-impact test:
   • It must change or constrain at least one future decision.
   • It must be specific enough for a downstream agent to follow.
   • It must avoid slogans such as "write clean code" unless paired with a concrete rule.
6. Add quality gates that can be verified later:
   • Define what must be checked, when it applies, and what evidence satisfies it.
   • Prefer commands, artifacts, review criteria, or explicit test expectations over vague assurances.
7. Add open governance questions only when the answer could materially change architecture, testing, security, UX, release, or memory behavior.
8. Run the verification checklist before finalizing.

Principle and Gate Quality

Write principles as decision rules, not values statements:

• Prefer: API changes preserve backwards compatibility unless a versioned migration path is documented. Verification: contract tests or migration notes accompany the change.
• Avoid: Build high-quality APIs.

Each principle should include or imply:

• scope: where it applies
• rule: the decision it constrains
• evidence: how future work proves compliance
• exception path: when deviations are allowed, if relevant

Write quality gates in a form a reviewer can grade:

Memory Model

Use memory deliberately and keep the layers separate:

• Runtime memory: use temporary working notes while reading, reconciling constraints, and drafting. Do not persist these notes unless the user asks.
• Project-local memory: store durable project governance in the constitution file. Include only stable, project-scoped principles, quality gates, routing rules, and open questions.
• Shared memory: treat cross-project or cross-agent memory as an external dependency. Use a shared-memory skill or explicit integration only when the user asks for broader reuse. Do not silently promote project-local decisions into shared memory.

Promotion rules:

• Do not promote runtime assumptions into the constitution without labeling them as assumptions or open questions.
• Do not promote project-local policy into shared memory without explicit user approval.
• Do not invent organization-wide policy. If the user supplies policy, scope it to this project unless they explicitly request broader governance.

Skill Routing Policy

Include a routing section when downstream agents will continue the work.

• Prefer installed, relevant skills over generic reasoning for recurring work.
• Only name a skill as preferred when it is actually available in the current environment or the user explicitly named it as an external dependency.
• If a useful skill is missing, write a capability need instead of inventing a skill name.
• Acceptable route values are exact installed skill names, user-supplied external dependencies, repository-native processes, or capability needs.
• Keep routing advisory, not absolute; downstream agents must still respect newer user instructions and repository conventions.

Common routing categories:

Guardrails

• Do not write implementation code as part of this skill.
• Do not select a complete architecture unless the user supplied or approved the decision.
• Do not turn the constitution into a backlog, PRD, ADR set, or release plan.
• Do not store secrets, credentials, personal data, or private policy details beyond what the user explicitly authorized.
• Do not overfit the constitution to a single sprint or immediate feature.
• Do not bury uncertainty. Capture material unknowns in Open Governance Questions.
• Keep the document compact enough for future agents to read quickly.

Constitution Template

Use assets/constitution-template.md when creating a new constitution or normalizing a weak one.

Adapt section names when the repository already has a strong convention, but preserve these responsibilities:

• purpose and scope
• durable project context
• product, engineering, architecture, testing, UX/accessibility, security/privacy, release, and operations principles
• memory model
• skill routing policy
• quality gates
• open governance questions
• change control

Update Existing Constitutions

When revising an existing artifact:

1. Identify whether the user asked for a targeted patch, a modernization pass, or a full rewrite.
2. Preserve ratified principles, numbering, and terminology when they still serve the project.
3. Remove or rewrite principles that are vague, stale, duplicated, unverifiable, or outside the constitution's scope.
4. Mark material changes clearly in the final response.
5. If a requested change conflicts with existing approved governance, surface the conflict instead of silently overriding it.

Verification Checklist

Before writing or returning the final constitution, confirm:

• The selected path follows an existing convention or defaults to .agentspec/memory/constitution.md.
• Every principle has decision impact.
• The document distinguishes facts, assumptions, and open questions.
• Quality gates are observable and tied to delivery phases or evidence.
• The memory model separates runtime, project-local, and shared memory.
• The skill-routing policy does not invent unavailable skills.
• No organization-wide policy, secrets, or unsupported architecture decisions were invented.
• The final document is concise enough for downstream agents to use.

Final Response

Report:

• the path created, updated, reviewed, or intentionally left unwritten
• the most important principles or changes
• the quality gates established or strengthened
• any open governance questions needing human confirmation
• any validation or review performed