constitution— agent skill

Overview

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

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

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 |
|------|--------|--------|
| 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

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