/constitution

name: constitution
description: "Creates, updates, validates, and displays the architectural DNA of a project through two shared documents: docs/specs/architecture.md (technology stack, architectural rules, security constraints, AI guardrails) and docs/specs/ontology.md (domain glossary / Ubiquitous Language). Use BEFORE brainstorm as a project setup step, or at any point in the SDD lifecycle to validate specs/tasks against architecture principles. Triggers on 'create constitution', 'update constitution', 'constitution check', 'validate against constitution', 'project principles', 'architectural guardrails', 'setup project architecture', 'define ontology'."
allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion, TodoWrite

Overview

The Constitution skill manages the architectural DNA of a project through two shared documents:

| File | Purpose | |------|---------| | `docs/specs/architecture.md` | Technology stack, infrastructure, architectural rules, security constraints, AI guardrails | | `docs/specs/ontology.md` | Domain glossary (Ubiquitous Language) — terms, definitions, bounded contexts |

These files live at `docs/specs/` and are shared across all specifications. Unlike a monolithic `constitution.md`, these are created/enriched by `brainstorm` (Phase 6.8.6) and `spec-to-tasks` (Phase 1.5).

Instructions

1. Identify the operation from `$ARGUMENTS` or user intent: `create`, `update`, `check`, or `show`. 2. For **create**: ask which files to create (architecture.md, ontology.md, or both), gather required information via `AskUserQuestion`, then write the files using the templates below. 3. For **update**: identify the target file and section, apply the change surgically, update the `Last Updated` date. 4. For **check**: read both constitution files, read the target file, validate against architectural rules and ontology terms, output a Constitution Check Report. 5. For **show**: read and display both files formatted for readability. 6. Always confirm with the user before writing or overwriting files.

Examples

# Create constitution before first brainstorm
/developer-kit-specs:constitution create

# Validate a spec against architecture and ontology
/developer-kit-specs:constitution check --target=docs/specs/001/2024-01-15--user-auth.md

# Update the security constraints section
/developer-kit-specs:constitution update --file=architecture --section=security

# Show current constitution
/developer-kit-specs:constitution show

When to Use

| Scenario | Operation | |----------|-----------| | New project — define stack and domain language before first brainstorm | `create` | | Stack or security rules changed | `update` | | Validate a spec, task, or file against architecture and ontology | `check` | | Review current architecture and ontology | `show` |

**Trigger phrases:**

• "Create constitution", "Setup project architecture", "Define ontology"
• "Update constitution", "Update architecture", "Update ontology"
• "Constitution check", "Validate against constitution"
• "Show constitution", "Project principles", "Architectural guardrails"

Operations

create

1. Ask which files to create: "Both" (recommended), "architecture.md only", "ontology.md only" 2. Check if files exist → ask to overwrite or skip 3. For **architecture.md**: gather via `AskUserQuestion` (domains, infrastructure, stack, data, style, rules) 4. For **ontology.md**: ask for terms or create empty scaffold 5. Confirm before writing each file

Template lookup order:

• Primary: `${CLAUDE_PLUGIN_ROOT}/templates/architecture.md`
• Fallback: `skills/constitution/references/architecture.md`

update

1. Parse `--file=architecture|ontology` and `--section=<name>` 2. Read target file, apply change surgically 3. Update `Last Updated` date 4. Write file

check

1. Read both constitution files 2. Read target file (`--target=<path>`) 3. Validate against architecture rules, security constraints, and ontology 4. Output **Constitution Check Report**

show

1. Read both `docs/specs/architecture.md` and `docs/specs/ontology.md` 2. Display formatted for readability

Context Rot Prevention

The Constitution survives context rot through file-based storage:

• **Read at session start**: Both `docs/specs/architecture.md` and `docs/specs/ontology.md`
• **Never assume in context**: MUST be read from file before implementation
• **Validate work**: Compare against constitution, not memory

For detailed scenarios and recovery protocols, see `references/context-rot-prevention.md`.

Constraints and Warnings

• **Does NOT modify source code** — only creates/updates constitution files
• **CRITICAL violations MUST be resolved** — WARNINGs are advisory
• **One architecture.md and one ontology.md per project** — shared across all specs
• **Update `Last Updated` date** on every change
• **Use ADRs** for significant architectural decisions
• **Context rot risk**: Files > 30 days old may have drifted

Best Practices

• **Create before brainstorm**: Constitution established early ensures consistency
• **Library Verification**: Before using ANY external library, verify it's in the architecture's Library Verification section
• **Spec Death Principle**: Archive completed specs to `archived/` — never let specs become stale
• **Ontology enrichment**: Updated by `brainstorm` (Phase 6.8.6) and `spec-to-tasks` (Phase 1.5)
• **Report format**: Security section first, then CWE compliance, architecture, library verification, ontology

Constitution Check Report Format

## Constitution Check Report
Target: <file path>
Date: YYYY-MM-DD

### Security Check (CWE/OWASP Compliance)
| Rule | Level | Status | Location | CWE/OWASP |
|------|-------|--------|----------|-----------|
| No SQL injection | CRITICAL | ✅ OK | - | CWE-89 |

### CWE Compliance Report
| CWE | OWASP | Status | Location |
|-----|-------|--------|----------|
| CWE-89 | A03 | ✅ OK | - |

### Architecture Check
| Rule | Status | Detail |
|--