Constitution Agent Skill

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

• Identify the operation from $ARGUMENTS or user intent: create, update, check, or show.
• 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.
• For update: identify the target file and section, apply the change surgically, update the Last Updated date.
• For check: read both constitution files, read the target file, validate against architectural rules and ontology terms, output a Constitution Check Report.
• For show: read and display both files formatted for readability.
• 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

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

Template lookup order:

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

update

• Parse --file=architecture|ontology and --section=<name>
• Read target file, apply change surgically
• Update Last Updated date
• Write file

check

• Read both constitution files
• Read target file (--target=<path>)
• Validate against architecture rules, security constraints, and ontology
• Output Constitution Check Report

show

• Read both docs/specs/architecture.md and docs/specs/ontology.md
• 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 |
|------|--------|--------|
| Constructor injection | ✅ OK | - |

### Library Verification Check
| Library | Status | Detail |
|---------|--------|--------|
| bcrypt | ✅ OK | Using hash(password, 12) |

### Ontology Check
| Term | Status | Detail |
|------|--------|--------|
| "User" used consistently | ✅ OK | - |

### Summary
- CRITICAL violations: 0
- WARNING violations: 0
- Compliant rules: N

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

Integration with SDD Workflow

[Session Start] → Read Constitution files
        ↓
[Optional] constitution create        ← this skill (pre-brainstorm setup)
        ↓
brainstorm                            ← Constitution loaded before brainstorming
        ↓
spec-to-tasks                         ← Constitution validates spec
        ↓
task-implementation                   ← Constitution guardrails active
        ↓
task-review                           ← Constitution check validates
        ↓
[Session End] → Constitution files updated if needed

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.