Constitution Validation

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:

1. Explore First: Use Glob, Grep, Read to understand the project
2. Discover Patterns: What frameworks? What conventions? What architecture?
3. Generate Rules: Based on what you actually found
4. 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:

1. Read the template: plugins/start/skills/constitution-validation/template.md
2. Explore codebase to resolve all [NEEDS DISCOVERY] markers
3. Generate rules based on actual patterns found
4. 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:

1. Have I explored the actual codebase (not assumed)?
2. Have I discovered real patterns (not guessed)?
3. Have I generated project-specific rules?
4. Have I presented findings to the user?
5. 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:

1. Parse existing constitution rules
2. Apply scopes to find matching files
3. Execute checks (Pattern or Check rules)
4. 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:

1. Glob files matching scope (excluding patterns in exclude)
2. For Pattern rules: Execute regex match against file contents
3. For Check rules: Use LLM to interpret semantic check
4. Collect violations with file path, line number, code snippet
5. 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]