autospec-constitution

name	autospec-constitution
description	Generate or update project constitution in YAML format.

autospec-constitution

This Agent Skill is generated from autospec.constitution. When the user invokes "$autospec-constitution" or "/autospec.constitution", load and follow these instructions directly. Treat the text after the skill or command name as "$ARGUMENTS". Do not route back through "autospec constitution"; this skill is the prompt for the stage.

Project specs directory: ./specs

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

You are creating or updating the project constitution. This file defines the non-negotiable principles and governance rules for the project that all specifications, plans, and implementations must adhere to.

Pre-computed Context

The following values have been pre-computed and are available for use:

• AUTOSPEC_VERSION: {{.AutospecVersion}}
• CREATED_DATE: {{.CreatedDate}}

Follow this execution flow:

1. Load existing context:

   • Check if .autospec/constitution.yaml exists (preferred path)
   • Check if .autospec/memory/constitution.yaml exists (legacy fallback)
   • Check if .autospec/memory/constitution.md exists (for migration)
   • Check if AGENTS.md exists at project root (or agent-specific file like CLAUDE.md as fallback)
   • Extract any existing principles, governance rules, or project guidelines

2. Collect/derive values:

   • If user input supplies principles, use them
   • Otherwise infer from existing repo context (README, docs, prior constitution)
   • For governance dates:
     • ratified: Original adoption date (if unknown, use today)
     • last_amended: Today if changes are made
   • For versioning: Use semantic versioning
     • MAJOR: Backward incompatible governance/principle changes
     • MINOR: New principle/section added
     • PATCH: Clarifications, wording fixes

3. Generate constitution.yaml:

   constitution:
     project_name: "<project name>"
     version: "1.0.0"
     ratified: "<YYYY-MM-DD>"
     last_amended: "<YYYY-MM-DD>"
   
   preamble: |
     <Brief statement of the project's purpose and why these principles matter.
     This should be 2-3 sentences that set the context for the principles below.>
   
   principles:
     - name: "Test-First Development"
       id: "PRIN-001"
       category: "quality"  # quality | process | architecture | security | governance
       priority: "NON-NEGOTIABLE"  # NON-NEGOTIABLE | MUST | SHOULD | MAY
       description: |
         All new code must have tests written before implementation.
         Tests define the expected behavior and serve as living documentation.
       rationale: "Ensures code quality and prevents regressions"
       enforcement:
         - mechanism: "Pre-commit hooks"
           description: "Automated checks prevent commits without tests"
         - mechanism: "CI pipeline"
           description: "Build fails if test coverage decreases"
       exceptions:
         - "Prototype/spike code explicitly marked as such"
         - "Configuration files and documentation"
   
     - name: "Performance Standards"
       id: "PRIN-002"
       category: "quality"
       priority: "MUST"
       description: |
         Validation functions must complete in <10ms.
         User-facing operations must complete in <1s.
       rationale: "Maintains responsive user experience"
       enforcement:
         - mechanism: "Benchmark tests"
           description: "Automated performance regression tests"
       exceptions: []
   
     - name: "Idempotency & Retry Logic"
       id: "PRIN-003"
       category: "architecture"
       priority: "MUST"
       description: |
         All operations must be idempotent where possible.
         Configurable retry limits for recoverable failures.
       rationale: "Enables reliable distributed operations"
       enforcement:
         - mechanism: "Code review"
           description: "Reviewers check for idempotent patterns"
       exceptions:
         - "One-time initialization operations"
   
   sections:
     - name: "Code Quality"
       content: |
         All code must pass linting and formatting checks.
         No warnings allowed in production builds.
         Dependencies must be explicitly versioned.
   
     - name: "Documentation"
       content: |
         Public APIs must have documentation.
         Architecture decisions must be recorded.
         Breaking changes must be documented in CHANGELOG.
   
     - name: "Security"
       content: |
         No secrets in code or version control.
         Dependencies must be regularly audited.
         User input must be validated and sanitized.
   
   governance:
     amendment_process:
       - step: 1
         action: "Propose change via pull request"
         requirements: "Include rationale and impact assessment"
       - step: 2
         action: "Review period"
         requirements: "Minimum 48 hours for team review"
       - step: 3
         action: "Approval"
         requirements: "Requires maintainer approval"
       - step: 4
         action: "Merge and version bump"
         requirements: "Update version and last_amended date"
   
     versioning_policy: |
       Constitution versions follow semantic versioning.
       MAJOR: Changes that invalidate existing compliant code.
       MINOR: New principles or expanded guidance.
       PATCH: Clarifications without behavioral change.
   
     compliance_review:
       frequency: "quarterly"
       process: "Review all principles for relevance and enforcement effectiveness"
   
     rules:
       - "Changes require review by at least one maintainer"
       - "Breaking changes require explicit team discussion"
       - "Emergency changes may bypass review with post-hoc documentation"
   
   sync_impact:
     # This section is auto-generated when constitution is updated
     version_change: "1.0.0 -> 1.0.0"
     modified_principles: []
     added_sections: []
     removed_sections: []
     templates_requiring_updates: []
     follow_up_todos: []
   
   _meta:
     version: "1.0.0"
     generator: "autospec"
     generator_version: "{{.AutospecVersion}}"
     created: "{{.CreatedDate}}"
     artifact_type: "constitution"
   

4. Write the constitution to .autospec/constitution.yaml

   • Create .autospec/ directory if it doesn't exist

5. Validate the artifact:

   autospec artifact .autospec/constitution.yaml
   

   • If validation fails: fix schema errors (missing required fields, invalid types/enums) and retry
   • If validation passes: proceed to report

6. Report: Output:

   • Full path to constitution.yaml
   • Version (new or updated)
   • Number of principles defined
   • Governance rules summary
   • Suggested commit message (e.g., docs: establish project constitution v1.0.0)

Principle Categories

• quality: Code quality, testing, performance standards
• process: Development workflow, review requirements
• architecture: Technical patterns, structure guidelines
• security: Security requirements, data handling
• governance: Decision-making, change management

Priority Levels

• NON-NEGOTIABLE: Cannot be bypassed under any circumstances
• MUST: Required unless explicitly exempted
• SHOULD: Strongly recommended with documented exceptions
• MAY: Optional best practice

Guidelines

Formatting & Style

• Use clear, declarative language
• Each principle should be testable/verifiable
• Avoid vague terms ("should", "may" without context)
• Wrap long content to keep readability
• Keep single blank line between sections

For AI Generation

When creating this constitution from user input:

1. Extract implicit principles: Look for patterns in existing codebase that suggest unwritten rules
2. Infer from tools: Package.json scripts, Makefile targets, CI config reveal expectations
3. Balance strictness: Not everything needs to be NON-NEGOTIABLE
4. Consider enforcement: Each principle should have at least one enforcement mechanism
5. Allow exceptions: Most principles have edge cases; document them

Validation Checklist

Before finalizing:

• All principles have unique IDs (PRIN-001, PRIN-002, etc.)
• All principles have enforcement mechanisms
• Priority levels are appropriate
• Governance section includes amendment process
• Version follows semantic versioning
• Dates are in ISO 8601 format (YYYY-MM-DD)