constitution-validation_skill

Overview

This skill creates and validates project constitutions by discovering real codebase patterns and generating governance rules. It produces a project-specific CONSTITUTION.md from a template and verifies code against those rules during implementation and review. The approach emphasizes discovery, user confirmation, and a three-tier (L1/L2/L3) rule severity model.

How this skill works

First, the skill explores the repository using globbing and content reads to identify frameworks, architecture, security patterns, and conventions. It replaces [NEEDS DISCOVERY] placeholders with concrete rules derived from observed patterns, writes the constitution to the project root, and can run validation mode to apply rules and report violations. Validation parses constitution rules, globs target files, executes regex or LLM semantic checks, and produces a prioritized compliance report.

When to use it

• When creating a new governance constitution based on the actual codebase
• When validating code against an existing constitution during review
• When updating constitution rules after adding frameworks or new patterns
• During implementation to enforce blocking rules (L1/L2) and run autofixes
• When auditing security-critical or architectural compliance before release

Best practices

• Always run discovery against the real repository; avoid assumptions about frameworks
• Present discovered patterns and proposed rules to users and require confirmation
• Use L1 only for objectively fixable or security-critical issues to enable autofix
• Reserve L2 for architecture or judgment calls that must block progress until fixed
• Keep L3 advisory rules lightweight and optional to reduce noise in CI

Example use cases

• Generate a CONSTITUTION.md that enforces environment variable usage instead of hardcoded secrets
• Validate a pull request to block merges if L2 architecture rules are violated
• Scan the codebase to detect eval() calls and auto-fix or flag them as L1
• Audit repository boundaries to flag cross-package relative imports as L2
• Provide a compliance report summarizing L1/L2/L3 findings for stakeholders