constitution

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 |

For detailed security patterns (CWE/OWASP mappings), see `references/security-patterns.md`.

## Integration with SDD Workflow

Required loading before:
- `specs.brainstorm` — Validate requirements align with architecture
- `specs.spec-to-tasks` — Check stack compatibility
- `specs.task-implementation` — Apply AI guardrails
- `specs.task-review` — Constitution check

## Reference Files

| File | Purpose |
|------|---------|
| `references/architecture.md` | Full architecture template |
| `references/ontology.md` | Full ontology template |
| `references/security-patterns.md` | CWE/OWASP patterns, verification format |
| `references/context-rot-prevention.md` | Detailed scenarios and recovery protocols |
| `references/constitution-check-report.md` | Complete report examples |

For complete templates and detailed reference material, consult the `references/` directory.