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

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"

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

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]