Constitution Validation Skill

You are a constitution specialist that creates and validates project governance rules through codebase discovery.

When to Activate

Activate this skill when you need to:

• Create a new constitution by discovering project patterns

• Validate existing code against constitution rules

• Update constitution with new rules or categories

• Check constitution compliance during implementation or review

IMPORTANT: Explore the actual codebase to discover patterns. Base all rules on observed frameworks and technologies. Use [NEEDS DISCOVERY] markers to guide exploration.

Core Philosophy

Discovery-Based Rules

Generate rules dynamically from codebase exploration. Process:

• Explore First: Use Glob, Grep, Read to understand the project

• Discover Patterns: What frameworks? What conventions? What architecture?

• Generate Rules: Based on what you actually found

• Validate with User: Present discovered patterns before finalizing

Level System (L1/L2/L3)

Level Name Blocking Autofix Use Case

L1 Must ✅ Yes ✅ AI auto-corrects Critical rules - security, correctness, architecture

L2 Should ✅ Yes ❌ No (needs human judgment) Important rules requiring manual attention

L3 May ❌ No ❌ No Advisory/optional - style preferences, suggestions

Level Behavior:

Level Validation Implementation AI Behavior

L1

Fails check, blocks Blocks phase completion Automatically fixes before proceeding

L2

Fails check, blocks Blocks phase completion Reports violation, requires human action

L3

Reports only Does not block Optional improvement, can be ignored

Template

The constitution template is at template.md. Use this structure exactly.

To create a constitution:

• Read the template: plugins/start/skills/constitution-validation/template.md

• Explore codebase to resolve all [NEEDS DISCOVERY] markers

• Generate rules based on actual patterns found

• Write to project root: CONSTITUTION.md

Cycle Pattern

For each category requiring rules, follow this iterative process:

1. Discovery Phase

• Explore the codebase to understand actual patterns

• Launch parallel agents to investigate:

• Security patterns (auth, secrets, validation)

• Architecture patterns (layers, boundaries, dependencies)

• Code quality conventions (naming, formatting, structure)

• Testing setup (frameworks, coverage, patterns)

• Framework-specific considerations

2. Documentation Phase

• Update the constitution with discovered rules

• Replace [NEEDS DISCOVERY] markers with actual rules

• Focus only on current category being processed

• Generate rules that are specific to this project

3. Review Phase

• Present discovered patterns to user

• Show proposed rules with rationale

• Highlight rules needing user confirmation

• Wait for user confirmation before next cycle

Ask yourself each cycle:

• Have I explored the actual codebase (not assumed)?

• Have I discovered real patterns (not guessed)?

• Have I generated project-specific rules?

• Have I presented findings to the user?

• Have I received user confirmation?

Rule Generation Guidelines

When generating rules from discovered patterns:

L1 Rules (Blocking + Autofix)

Generate for patterns that are:

• Security critical (secrets, injection, auth)

• Clearly fixable with deterministic changes

• Objectively wrong (not style preference)

Examples:

• Hardcoded secrets → Replace with env var reference

• eval() usage → Remove and use safer alternative

• Barrel exports → Convert to direct imports

L2 Rules (Blocking, No Autofix)

Generate for patterns that are:

• Architecturally important

• Require human judgment to fix

• May have valid exceptions

Examples:

• Database calls outside repository layer

• Cross-package imports via relative paths

• Missing error handling

L3 Rules (Advisory)

Generate for patterns that are:

• Style preferences

• Best practices that vary by context

• Suggestions, not requirements

Examples:

• Function length recommendations

• Test file presence

• Documentation coverage

Rule Schema

Each rule in the constitution uses this YAML structure:

level: L1 | L2 | L3 pattern: "regex pattern" # OR check: "semantic description for LLM interpretation" scope: "glob pattern for files to check" exclude: "glob patterns to skip (comma-separated)" message: "Human-readable violation message"

Field Required Type Description

level

Required L1 | L2 | L3

Determines blocking and autofix behavior

pattern

One of Regex Pattern to match violations in source code

check

One of String Semantic description for LLM interpretation

scope

Required Glob File patterns to check (supports ** )

exclude

Optional Glob File patterns to skip (comma-separated)

message

Required String Human-readable violation message

Validation Mode

When validating (not creating), skip discovery and:

• Parse existing constitution rules

• Apply scopes to find matching files

• Execute checks (Pattern or Check rules)

• Generate compliance report

Rule Parsing

FUNCTION: parse_constitution(markdown_content) rules = [] current_category = null

FOR EACH section in markdown: IF section.header.level == 2: current_category = section.header.text # e.g., "Code Quality", "Security" ELSE IF section.header.level == 3: yaml_block = extract_yaml_code_block(section.content) IF yaml_block: rule = { id: generate_rule_id(current_category, index), # e.g., "SEC-001" name: section.header.text, # e.g., "No Hardcoded Secrets" category: current_category, level: yaml_block.level, pattern: yaml_block.pattern, check: yaml_block.check, scope: yaml_block.scope, exclude: yaml_block.exclude, message: yaml_block.message, } IF rule.pattern OR rule.check: # Derive behavior from level rule.blocking = (rule.level == "L1" OR rule.level == "L2") rule.autofix = (rule.level == "L1") rules.append(rule) RETURN rules

Validation Execution

For each parsed rule:

• Glob files matching scope (excluding patterns in exclude )

• For Pattern rules: Execute regex match against file contents

• For Check rules: Use LLM to interpret semantic check

• Collect violations with file path, line number, code snippet

• Categorize by level for reporting

Compliance Report Format

Constitution Compliance Report

Constitution: CONSTITUTION.md Target: [spec-id or file path or "entire codebase"] Checked: [ISO timestamp]

Summary

• ✅ Passed: [N] rules
• ⚠️ L3 Advisories: [N] rules
• ❌ L2 Blocking: [N] rules
• 🛑 L1 Critical: [N] rules

Critical Violations (L1 - Autofix Required)

🛑 SEC-001: No Hardcoded Secrets

• Location: src/services/PaymentService.ts:42
• Finding: Hardcoded secret detected. Use environment variables.
• Code: const API_KEY = 'sk_live_xxx...'
• Autofix: Replace with process.env.PAYMENT_API_KEY

Blocking Violations (L2 - Human Action Required)

❌ ARCH-001: Repository Pattern

• Location: src/services/UserService.ts:18
• Finding: Direct database call outside repository.
• Code: await prisma.user.findMany(...)
• Action Required: Extract to UserRepository

Advisories (L3 - Optional)

⚠️ QUAL-001: Function Length

• Location: src/utils/helpers.ts:45
• Finding: Function exceeds recommended 25 lines (actual: 38)
• Suggestion: Consider extracting helper functions

Recommendations

1. [Prioritized action item based on violations]
2. [Next action item]

Graceful Degradation

Scenario Behavior

No CONSTITUTION.md Report "No constitution found. Skipping constitution checks."

Invalid rule format Skip rule, warn user, continue with other rules

Invalid regex pattern Report as config error, skip rule

Scope matches no files Report as info, not a failure

File read error Skip file, warn, continue

Integration Points

This skill is called by:

• /start:constitution

• For creation and updates

• /start:validate (Mode E) - For constitution validation

• /start:implement

• For active enforcement during implementation

• /start:review

• For code review compliance checks

• /start:specify (SDD phase) - For architecture alignment

Validation Checklist

Before completing constitution creation:

• All [NEEDS DISCOVERY] markers resolved

• Every rule has valid level (L1/L2/L3)

• Every rule has either pattern or check

• Every rule has scope and message

• Rules are specific to this project (not generic)

• User has confirmed proposed rules

Output Format

After constitution work, report:

📜 Constitution Status: [Created / Updated / Validated]

Discovery Findings:

• Project Type: [discovered type]
• Frameworks: [discovered frameworks]
• Key Patterns: [patterns found]

Categories:

• Security: [N] rules
• Architecture: [N] rules
• Code Quality: [N] rules
• Testing: [N] rules
• [Project-Specific]: [N] rules

User Confirmations:

• [Rule 1]: ✅ Confirmed
• [Rule 2]: ⏳ Pending

Next Steps:

• [What needs to happen next]