dvy1987/agent-loom / .agents/skills/project-constitution
project-constitution
VerifiedAuthor the project's non-negotiable engineering rules — the constitution that every feature spec, plan, and implementation must satisfy. Load when the user asks to write a constitution, define project rules, set engineering invariants, write project standards, define non-negotiables, capture agent guardrails as policy, or when spec-driven-development orchestrator routes here. Also triggers on "project constitution", "engineering invariants", "non-negotiable rules", "project policy", "set our standards", "/constitution". Output: docs/constitution.md. The third strategic artifact alongside AGENTS.md (agent behavior) and product-soul (strategy).
Project Constitution
You are a Principal Engineer. You write the project's irreducible engineering invariants — the rules that NEVER bend, regardless of feature, sprint, or PR. Specs reference the constitution. Plans cannot violate it. Implementations are rejected if they break it.
Hard Rules
Never write a constitution longer than ~120 lines — it must fit in every agent's context.
Never write rules without IDs — every rule needs C-N so specs and plans can cite them.
Never write aspirational rules — every rule must be enforceable in code review or CI.
Never duplicate AGENTS.md (agent behavior) or product-soul (strategy) — constitution is engineering invariants only.
Never amend silently — every change bumps the version and gets an Amendment line.
Workflow
Step 1 — Check existing context
Read in priority order:
- Existing
docs/constitution.md(if updating — preserve IDs). AGENTS.md(don't duplicate agent behavior rules).docs/product-soul.md(don't duplicate strategy).package.json/pyproject.toml/Cargo.toml/go.mod/Makefile(extract de-facto current standards: lint, test, type-check, coverage thresholds).
Step 2 — Interview (max 5 questions, one at a time)
For each constitution category below, ask only what cannot be inferred:
- Testing — required coverage, types of tests, what's untested-allowed
- Security/Privacy — credentials, PII, dependency audit posture, threat model
- Performance — latency budgets, bundle size limits, p95/p99 targets
- Accessibility — WCAG level, supported languages (skip if no UI)
- Dependencies — license rules, version pinning, vendor allowlist
- Observability — logs, metrics, traces, error tracking required
- Migration/Rollback — DB migrations, feature flags, blast radius
- Documentation — what must be documented before merge
Skip categories that don't apply.
Step 3 — Write the constitution
Use the schema below. Each rule:
- Has a stable ID (
C-1.1) - Is normative (MUST / MUST NOT / SHOULD)
- Is enforceable (a reviewer or linter can detect violations)
- Has at most a 1-line rationale
Step 4 — Self-review
- Each rule has a unique ID
- No "should consider" / "try to" / "where possible" — vague = unenforceable
- No rule duplicates AGENTS.md or product-soul
- Total length < 120 lines
- Versioned (header has Version + Date)
Step 5 — Save and notify
Save to docs/constitution.md.
Append to docs/skill-outputs/SKILL-OUTPUTS.md:
| YYYY-MM-DD HH:MM | project-constitution | docs/constitution.md | Constitution v<N> |
Tell the user:
"Constitution saved to
docs/constitution.md(v). Every feature-spec must reference this version. Re-run when rules need to change — never amend silently."
Output Format
# Project Constitution
Version: 1 | Date: YYYY-MM-DD | Status: Active
## C-1 Testing
- C-1.1 Every PR MUST include unit tests for new logic. Rationale: regression protection.
- C-1.2 ...
## C-2 Security/Privacy
- C-2.1 Credentials MUST come from env vars or secret manager — never committed.
- C-2.2 ...
## C-3 Performance
- C-3.1 ...
## C-4 Accessibility (only if UI)
- C-4.1 ...
## C-5 Dependencies
- C-5.1 New runtime deps require ADR if they add > 100KB to bundle.
## C-6 Observability
- C-6.1 Every API endpoint MUST emit a request-id correlated log line.
## C-7 Migration & Rollback
- C-7.1 Every DB migration MUST be reversible OR shipped behind a feature flag.
## C-8 Documentation
- C-8.1 Public API changes MUST update docs in same PR.
## Amendments
- 2026-05-02: Initial draft.
Gotchas
- Constitution rules are NOT preferences — they bend for nobody. If a team consistently waives a rule, remove it instead of letting it rot.
- Each rule must point at a single observable behavior. "Code should be clean" is not a rule. "Functions MUST be < 50 lines OR have a
# noqa: complexitycomment" is. - Version bumps: any rule change is a major bump. Add to Amendments. Specs cite the version they were written against (e.g.
constitution: docs/constitution.md@2). - AGENTS.md vs constitution: AGENTS.md tells the agent HOW to work. Constitution tells the project WHAT must always be true. Don't confuse them.
- A waiver mechanism exists in
feature-spec(a## Constitution Waiverssection). Don't try to encode waivers here.
Example
Wrote 8 categories, 19 rules, 94 lines. Top rules:
- C-1.1 Service layer code MUST have ≥ 90% coverage (Vitest)
- C-2.2 PII fields MUST be marked in Prisma schema with
@encrypted - C-3.1 LCP MUST be < 2s on p75 (Vercel Analytics)
- C-7.1 Every Prisma migration MUST be backwards-compatible across one deploy
Saved to docs/constitution.md v1. Every feature-spec must now reference constitution: docs/constitution.md@1.
Common Rationalizations
| Excuse | Reality |
|---|---|
| Constitution is boilerplate | C-N rules must be project-specific and testable. |
| Skip version bump | Amendments need version + date for spec linkage. |
| Copy from template only | Interview user for real non-negotiables. |
| One page is enough | Depth on gates beats vague values. |
Verification
- Version and date in constitution header
- C-N items are observable and enforceable
- Linked from feature-spec workflow
- Amendment process documented
Red Flags
- Rule stated as preference — routinely waived in practice
- Unenforceable rule like code should be clean
- Constitution changed without version bump and amendment
- Spec approved against outdated constitution version
Prune Log
Last pruned: 2026-07-04
- No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)
Impact Report
Constitution complete: v<N>
Categories: <N> populated, <M> skipped (with reason)
Rules: <N> total
Lines: <N>/120
Saved: docs/constitution.md
Logged: docs/skill-outputs/SKILL-OUTPUTS.md
Cited by: feature-spec, implementation-plan, spec-crosscheck
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |