AgentSkillsCN

Constitution Guard

宪法卫士

SKILL.md

Constitution Guard Skill

Overview

The constitution_guard skill enforces constitution constraints and prevents scope creep, shortcuts, or manual code writing during the "Evolution of Todo" hackathon. It validates that all development work adheres to the project's constitution and Spec-Driven Development (SDD) principles.

Skill Metadata

  • •Name: constitution_guard
  • •Description: Enforces constitution constraints and prevents scope creep, shortcuts, or manual code writing
  • •Expected Input: Current constitution, specs, plans, or code changes
  • •Expected Output: Validation confirmations or violation warnings with specific guidance
  • •Usage Example: Used to validate Phase I implementation against constitution requirements

Constraints

  • •No automatic code generation
  • •No enforcement action (reports only)
  • •Single file implementation
  • •Must cite specific constitution sections in feedback

Validation Rules

1. SDD Compliance Check

Verifies that the feature follows Spec-Driven Development principles:

markdown
**Validation Criteria**:
- ✓ Spec file exists at `specs/<feature>/spec.md`
- ✓ Plan file exists at `specs/<feature>/plan.md`
- ✓ Tasks file exists at `specs/<feature>/tasks.md`
- ✓ PHR (Prompt History Record) created for all user inputs
- ✗ Any missing SDD artifact triggers warning

Constitution Reference: Section requiring that all development must follow SDD and generate spec/plan/tasks before implementation.

2. Scope Creep Detection

Identifies additions or changes that exceed the defined scope:

markdown
**Validation Criteria**:
- ✓ Feature implementation matches spec exactly
- ✓ No "bonus" features added without spec updates
- ✓ Code changes align with stated acceptance criteria
- ✗ Additional functionality not in spec triggers warning

Constitution Reference: Section about "smallest viable change" and avoiding over-engineering.

3. Manual Code Prevention

Prevents unauthorized manual code writing:

markdown
**Validation Criteria**:
- ✓ Code generated from specs using Claude Code
- ✓ No hand-written implementations without corresponding specs
- ✓ Tests written before implementation (TDD)
- ✗ Direct code modification without spec approval triggers warning

Constitution Reference: Constraint: "You cannot write code manually. You must refine the spec until Claude Code generates the correct output."

4. Constitution Principles Check

Validates compliance with project constitution principles:

markdown
**Validation Criteria** (examples based on typical constitution):
- ✓ Test-First approach enforced (tests before implementation)
- ✓ Reusable Intelligence used appropriately
- ✓ Proper PHR documentation for all prompts
- ✓ ADR (Architecture Decision Records) created for significant decisions
- ✗ Violation of any constitution principle triggers warning

Constitution Reference: All constitutional principles and requirements.

Usage Instructions

Command Line Interface (CLI)

bash
# Validate a specification against constitution
claude --skill constitution_guard "Validate spec.md against constitution"

# Check a plan for scope creep
claude --skill constitution_guard "Check plan.md for scope violations"

# Validate code changes
claude --skill constitution_guard "Verify implementation matches spec.md"

# Full validation
claude --skill constitution_guard "Validate complete feature: Phase I Todo"

Interactive Mode

  1. •Provide the constitution reference, spec, plan, and/or code to validate
  2. •The skill performs comprehensive validation against all rules (1-4 above)
  3. •Review validation results - confirmations or violations with specific guidance
  4. •Address any violations before proceeding with implementation
  5. •Re-validate after making corrections

Integration Mode

Embed constitution_guard validation in your workflow:

  • •Run before submitting PRs
  • •Use as pre-commit hook
  • •Include in CI/CD pipeline for automated checks

Input Validation & Constraints

Required Input Format

  • •Type: Markdown files (constitution, spec, plan, tasks) or code changes
  • •Minimum files: At least one constitutional document (.specify/memory/constitution.md)
  • •Format: Spec-Kit Plus compatible markdown structure
  • •Context: Full understanding of the hackathon requirements and constraints

Input Schema Validation

The skill validates input against these criteria:

  • •Constitution file must exist and be readable
  • •Spec files must be in specs/<feature>/spec.md format
  • •Plan files must be in specs/<feature>/plan.md format
  • •Tasks files must be in specs/<feature>/tasks.md format
  • •All paths must be relative to project root

Invalid Input Handling

  • •Missing files: Returns error "Required file not found: <path>"
  • •Unreadable files: Returns error "Unable to read file: <path>"
  • •Invalid format: Returns error "Invalid format in <file> - expected Spec-Kit Plus structure"
  • •Missing context: Requests additional files or clarification

Output Format Options

  • •Format: Always text report (can be wrapped in markdown code blocks)
  • •Structure: Sectioned validation results for each rule (1-4)
  • •Detail level: Specific citations with line numbers where applicable
  • •Severity levels: INFO, WARNING, ERROR for each finding

Version Compatibility

  • •Claude Code Version: Compatible with v2.0 and above
  • •Spec-Kit Plus: Compatible with v1.0 and above
  • •Project Type: Designed for Hackathon II - Evolution of Todo
  • •Last tested: 2026-01-27

Error Handling

1. Input Validation Errors

  • •File not found: Specific error with suggested path corrections
  • •Parse errors: Detailed explanation of format issues with examples
  • •Missing context: Requests specific additional information needed

2. Processing Errors

  • •System errors: "System error - constitution_guard validation failed"
  • •Timeout errors: "Validation timed out - files too large or complex"
  • •Logic errors: "Unable to complete validation - please verify input format"

Error Recovery: All errors include suggestions for resolution and reference documentation.

Implementation Notes

Validation Approach

  • •Rule-based checking: Each constitutional requirement becomes a validation rule
  • •Specific citations: Every finding references exact constitution sections
  • •Actionable feedback: Warnings include specific guidance on how to fix issues
  • •No enforcement: Skill reports violations but doesn't block development

Spec-Kit Plus Integration

  • •Aligns with Spec-Kit Plus directory structure (specs/<feature>/)
  • •Understands SDD workflow phases (spec → plan → tasks → implement)
  • •Validates PHR creation in history/prompts/
  • •Checks for ADR documentation in history/adr/

Hackathon-Specific Knowledge

  • •Understanding of 5-phase Evolution of Todo structure
  • •Awareness of bonus points categories (reusable intelligence, blueprints, etc.)
  • •Validates against Hackathon II requirements document
  • •Checks timeline and phase-specific deliverables

Optional vs Required Sections

Required Inputs (Must Be Provided)

  • •Constitution file (.specify/memory/constitution.md)
  • •At least one document to validate (spec, plan, or tasks file)

Optional Inputs (Improves Validation Quality)

  • •Implementation code or diffs
  • •PHR files for context
  • •ADR files for architectural decisions
  • •Project README or requirements documents

Output Sections (Always Included)

  • •Executive summary (pass/fail with severity counts)
  • •Detailed results for Rule 1 (SDD Compliance)
  • •Detailed results for Rule 2 (Scope Creep Detection)
  • •Detailed results for Rule 3 (Manual Code Prevention)
  • •Detailed results for Rule 4 (Constitution Principles)
  • •Recommendations for addressing violations

Example Validations

Example 1: Valid Phase I Spec

code
Input: specs/phase-i/spec.md

*** CONSTITUTION GUARD VALIDATION REPORT ***

✓ EXECUTIVE SUMMARY: PASS (0 errors, 0 warnings, 2 notes)

Rule 1 - SDD Compliance: PASS
  ✓ Spec file exists: specs/phase-i/spec.md
  ✓ Plan file exists: specs/phase-i/plan.md
  ✓ Tasks file exists: specs/phase-i/tasks.md
  ✓ PHR created: history/prompts/phase-i/
  Note: Consider adding ADR for architectural decisions

Rule 2 - Scope Creep Detection: PASS
  ✓ Feature scope clearly defined
  ✓ No unplanned features detected
  ✓ Acceptance criteria are specific and testable

Rule 3 - Manual Code Prevention: N/A (pre-implementation)
  Note: Remember - no manual code writing. Use Claude Code with this spec.

Rule 4 - Constitution Principles: PASS
  ✓ Test-First approach documented in tasks.md
  ✓ Smallest viable change principle followed
  ✓ Reusable Intelligence consideration noted

Next Steps: Proceed with Phase I implementation using Claude Code

Example 2: Detecting Scope Creep

code
Input: specs/phase-i/spec.md with implementation changes

⚠️  CONSTITUTION GUARD VALIDATION REPORT ⚠️

✗ EXECUTIVE SUMMARY: WARNING (1 error, 2 warnings)

Rule 1 - SDD Compliance: PASS
  ✓ All SDD artifacts present

Rule 2 - Scope Creep Detection: FAIL
  ✗ SCOPE CREEP DETECTED: Implementation includes "export to CSV" feature
    Location: todo_app.py:45-67
    Issue: Not defined in spec.md
    Constitution Ref: "Do not add features, refactor code, or make \"improvements\" beyond what was asked"
    Fix: Remove CSV export OR update spec.md with CSV export requirements

Rule 3 - Manual Code Prevention: PASS
  ✓ No unauthorized manual code detected

Rule 4 - Constitution Principles: PASS
  ✓ All constitutional principles followed

⚠️  Critical: Remove scope creep before proceeding

Example 3: Missing SDD Artifacts

code
Input: specs/phase-i/spec.md (only spec file)

✗ CONSTITUTION GUARD VALIDATION REPORT ✗

✗ EXECUTIVE SUMMARY: FAIL (2 errors, 0 warnings)

Rule 1 - SDD Compliance: FAIL
  ✓ Spec file exists: specs/phase-i/spec.md
  ✗ MISSING: Plan file (specs/phase-i/plan.md)
  ✗ MISSING: Tasks file (specs/phase-i/tasks.md)
  ✗ MISSING: PHR documentation
  Constitution Ref: "You must write a Markdown Constitution and Spec for every feature of the phase"

  Fix: Run '/sp.plan' and '/sp.tasks' for Phase I before implementation

Rule 2 - Scope Creep Detection: SKIPPED (depends on Rule 1)
Rule 3 - Manual Code Prevention: SKIPPED (depends on Rule 1)
Rule 4 - Constitution Principles: SKIPPED (depends on Rule 1)

✗ Critical: Complete SDD artifacts before implementation (Constitution Ref)

Example 4: Manual Code Violation

code
Input: Implementation attempting manual code writing

✗ CONSTITUTION GUARD VALIDATION REPORT ✗

✗ EXECUTIVE SUMMARY: CRITICAL ERROR (1 critical error)

Rule 1 - SDD Compliance: PASS
  ✓ All SDD artifacts present

Rule 2 - Scope Creep Detection: PASS
  ✓ No scope creep detected

Rule 3 - Manual Code Prevention: CRITICAL FAILURE
  ✗ MANUAL CODE WRITING DETECTED
    Location: todo_app.py (entire file appears hand-written)
    Issue: Code does not follow spec-driven generation pattern
    Constitution Ref: "Constraint: You cannot write the code manually. You must refine the spec until Claude Code generates the correct output."

  Fix: DELETE this code. Use Claude Code with the spec to generate implementation.

Rule 4 - Constitution Principles: PASS
  ✓ Other principles followed

✗ CRITICAL: Remove manually-written code and regenerate using Claude Code

Advanced Usage

Batch Validation

bash
# Validate multiple features at once
claude --skill constitution_guard "Validate all specs in specs/ directory"

# Validate before commit
claude --skill constitution_guard "Pre-commit validation of current changes"

Custom Rule Extensions

bash
# Add project-specific rules
claude --skill constitution_guard "Add custom rule: All functions must have docstrings"

# The skill learns from your constitution and can extend validation

Continuous Validation

bash
# Watch mode for ongoing development
claude --skill constitution_guard "Watch specs/ directory for changes and validate"

Skill Version History

  • •v1.0.0 (2026-01-27): Initial implementation
    • •4 core validation rules (SDD, Scope, Manual Code, Constitution)
    • •Text-based reporting with specific citations
    • •Hackathon II Evolution of Todo specialization

Maintenance Notes

For Skill Developers

  • •When constitution changes, update validation rules accordingly
  • •Test with sample spec/plan/tasks files before deploying updates
  • •Maintain backward compatibility with existing projects

For Users

  • •Always validate before significant milestones (pre-implementation, pre-PR, etc.)
  • •Address WARNING level findings promptly to avoid ERROR escalation
  • •Keep constitution.md updated as project evolves

Skill Version: 1.0.0 Last Updated: 2026-01-27 Compatibility: Claude Code v2.0+, Spec-Kit Plus v1.0+ Project: Hackathon II - Evolution of Todo