Skip to content

constitution.md

Latest commit

 

History

History
412 lines (286 loc) · 12.8 KB

constitution.md

File metadata and controls

412 lines (286 loc) · 12.8 KB
Raw

Constitutional Governance

Version: 1.0 Status: Immutable Enforcement: Mandatory via constitution-enforcer skill

Overview

This document defines the 9 Constitutional Articles that govern all development activities in this project. These articles are immutable and must be enforced at every stage of the SDD workflow.

Enforcement Agent: The constitution-enforcer skill validates compliance with these articles before proceeding to implementation.

Article I: Library-First Principle

Statement: All new features SHALL begin as independent libraries before integration into applications.

Requirements

  • Every feature MUST start as a standalone library
  • Libraries MUST have their own test suites
  • Libraries MUST be independently deployable
  • Libraries MUST NOT depend on application code
  • Libraries MAY be published to package registries

Rationale

  • Enforces modularity and reusability
  • Prevents tight coupling
  • Enables independent testing and versioning
  • Facilitates code sharing across projects

Validation Checklist

  • Feature implemented as library in /lib or separate package
  • Library has independent package.json (if applicable)
  • Library has dedicated test suite
  • Library exports public API
  • No imports from application code

Article II: CLI Interface Mandate

Statement: All libraries SHALL expose functionality through CLI interfaces.

Requirements

  • Every library MUST provide a CLI interface
  • CLI MUST expose all primary functionality
  • CLI MUST follow consistent argument conventions
  • CLI MUST provide help text and usage examples
  • CLI MAY delegate to library API

Rationale

  • Enables scriptability and automation
  • Facilitates testing and debugging
  • Improves developer experience
  • Enables integration with CI/CD pipelines

Validation Checklist

  • Library provides CLI entry point (bin/ or scripts/)
  • CLI documented with --help flag
  • CLI supports common operations
  • CLI uses consistent argument patterns (flags, options)
  • CLI exit codes follow conventions (0=success, non-zero=error)

Article III: Test-First Imperative

Statement: Tests SHALL be written before implementation (Red-Green-Blue cycle).

Requirements

  • Tests MUST be written before production code
  • Tests MUST follow Red-Green-Blue cycle:
    1. Red: Write failing test
    2. Green: Write minimal code to pass
    3. Blue: Refactor with confidence
  • Tests MUST cover all EARS requirements
  • Test coverage MUST exceed 80%
  • Integration tests MUST use real services (see Article IX)

Rationale

  • Ensures requirements are testable
  • Prevents over-engineering
  • Provides executable specifications
  • Enables safe refactoring

Validation Checklist

  • Tests exist before implementation
  • All EARS requirements have corresponding tests
  • Test coverage ≥ 80%
  • Tests follow Red-Green-Blue evidence (git history)
  • No production code without tests

Article IV: EARS Requirements Format

Statement: All requirements SHALL use EARS (Easy Approach to Requirements Syntax) format.

Requirements

  • Requirements MUST use one of 5 EARS patterns:
    1. Event-driven: WHEN [event], the [system] SHALL [response]
    2. State-driven: WHILE [state], the [system] SHALL [response]
    3. Unwanted behavior: IF [error], THEN the [system] SHALL [response]
    4. Optional features: WHERE [feature enabled], the [system] SHALL [response]
    5. Ubiquitous: The [system] SHALL [requirement]
  • Requirements MUST be unambiguous
  • Requirements MUST include acceptance criteria
  • Requirements MUST be traceable to design and tests

Rationale

  • Eliminates ambiguity
  • Improves testability
  • Enables traceability
  • Standardizes requirements format

Validation Checklist

  • All requirements use EARS patterns
  • Requirements are unambiguous (single interpretation)
  • Acceptance criteria defined
  • Requirements mapped to tests (see traceability-auditor)
  • Requirements reviewed by stakeholders

Reference: See steering/rules/ears-format.md for complete EARS guide.

Article V: Traceability Mandate

Statement: 100% traceability SHALL be maintained between Requirements ↔ Design ↔ Code ↔ Tests.

Requirements

  • Every requirement MUST map to:
    • Design decisions (architecture, API, database)
    • Implementation (source files, functions)
    • Tests (test cases, scenarios)
  • Every test MUST reference requirement ID
  • Design documents MUST include requirements coverage matrix
  • Task breakdowns MUST map to requirements

Rationale

  • Ensures nothing is missed
  • Validates completeness
  • Enables impact analysis
  • Facilitates audits and compliance

Validation Checklist

  • Requirements have unique IDs (REQ-XXX-NNN)
  • Design documents include requirements matrix
  • Code comments reference requirement IDs
  • Tests reference requirement IDs in descriptions
  • traceability-auditor validation passes

Enforcement Agent: Use traceability-auditor skill to validate coverage.

Article VI: Project Memory (Steering System)

Statement: All skills SHALL consult project memory (steering files) before making decisions.

Requirements

  • steering/structure.md MUST define architecture patterns
  • steering/tech.md MUST define technology stack
  • steering/product.md MUST define business context
  • All skills MUST read steering files before executing
  • Steering files MUST be kept up-to-date
  • Changes to steering REQUIRE stakeholder approval

Rationale

  • Ensures consistency across skills
  • Provides project context to AI agents
  • Prevents architectural drift
  • Enables autonomous decision-making

Validation Checklist

  • Steering files exist and are current
  • Skill reads steering files before execution
  • Decisions align with steering context
  • Changes to steering are documented
  • Steering sync performed regularly

Management Agent: Use steering skill to generate/update project memory.

Article VII: Simplicity Gate (Phase -1 Gate)

Statement: Projects SHALL start with maximum 3 sub-projects initially.

Requirements

  • Initial architecture MUST NOT exceed 3 projects
  • Projects = independently deployable units
  • Additional projects require Phase -1 Gate approval
  • Complexity MUST be justified with:
    • Business requirements
    • Technical constraints
    • Team capacity analysis

Rationale

  • Prevents premature complexity
  • Reduces coordination overhead
  • Enables faster iteration
  • Forces prioritization

Validation Checklist

  • Project count ≤ 3 initially
  • Each project has clear purpose
  • Projects are independently deployable
  • Additional projects require approval gate
  • Complexity justified in design.md

Phase -1 Gate: Requires system-architect + project-manager approval before exceeding 3 projects.

Article VIII: Anti-Abstraction Gate (Phase -1 Gate)

Statement: Framework features SHALL be used directly without custom abstraction layers.

Requirements

  • MUST use framework APIs directly
  • MUST NOT create custom abstractions over frameworks
  • MUST NOT build "wrapper libraries" around frameworks
  • Abstractions require Phase -1 Gate approval with:
    • Multi-framework support justification
    • Team expertise analysis
    • Migration path documentation

Rationale

  • Prevents over-engineering
  • Reduces maintenance burden
  • Leverages framework best practices
  • Enables framework updates

Validation Checklist

  • Framework APIs used directly in application code
  • No custom wrapper libraries around frameworks
  • Framework-specific features leveraged
  • Abstractions justified with multi-framework need
  • Team has framework expertise

Phase -1 Gate: Requires system-architect + software-developer approval for abstraction layers.

Example Violations:

  • Creating MyDatabase wrapper around Prisma/TypeORM
  • Building custom HttpClient wrapper around axios/fetch
  • Implementing custom Logger abstraction over framework logging

Valid Abstractions:

  • Multi-framework support (e.g., database library supporting Prisma AND TypeORM)
  • Domain-specific abstractions (e.g., PaymentGateway interface with multiple providers)

Article IX: Integration-First Testing

Statement: Integration tests SHALL use real services; mocks are discouraged.

Requirements

  • Integration tests MUST use real databases, APIs, services
  • Test databases MUST be isolated (containers, test schemas)
  • External APIs MUST use sandbox/test environments
  • Mocks ALLOWED only when:
    • External service unavailable in test environment
    • External service has usage limits/costs
    • External service has no test environment
  • Mock usage REQUIRES justification in test documentation

Rationale

  • Tests real system behavior
  • Catches integration issues early
  • Validates actual service interactions
  • Builds confidence in deployment

Validation Checklist

  • Integration tests use real databases (Docker, test schema)
  • External APIs use test/sandbox environments
  • Mocks justified with unavailability/cost reasons
  • Test data cleanup automated
  • Tests pass against real services

Tools: Docker Compose, Testcontainers, test database schemas

Phase -1 Gates

Phase -1 Gates are validation checkpoints that occur BEFORE implementation begins. They enforce constitutional compliance.

Gate Triggers

Gates are triggered when:

  • Project count exceeds 3 (Article VII)
  • Custom abstraction layers proposed (Article VIII)
  • EARS requirements incomplete (Article IV)
  • Traceability gaps detected (Article V)

Gate Process

  1. Detection: constitution-enforcer skill detects violation
  2. Documentation: Proposer documents justification
  3. Review: Required skills review proposal
  4. Approval: Stakeholders approve/reject
  5. Proceed: Implementation continues only after approval

Required Reviewers

Gate Required Skills Stakeholders
Simplicity (Article VII) system-architect, project-manager Tech lead, Product owner
Anti-Abstraction (Article VIII) system-architect, software-developer Tech lead, Senior engineer
EARS Compliance (Article IV) requirements-analyst Product owner, QA lead
Traceability (Article V) traceability-auditor QA lead, Compliance officer

Enforcement

Validation Agent

The constitution-enforcer skill automatically validates compliance:

# Validate before implementation
@constitution-enforcer validate requirements.md
@constitution-enforcer validate design.md

Validation Stages

Stage Articles Validated Trigger
Requirements IV, V Before design
Design I, II, VI, VII, VIII Before tasks
Implementation III, V Before commit
Testing III, V, IX Before deployment

Violation Response

  1. Blocker: Implementation MUST NOT proceed
  2. Documentation: Violation documented in design.md
  3. Resolution: Either fix violation OR trigger Phase -1 Gate
  4. Re-validation: constitution-enforcer re-runs validation

Amendment Process

Constitutional articles are IMMUTABLE. Amendments require:

  1. Unanimous stakeholder agreement
  2. Documentation of rationale
  3. Update to this file with version increment
  4. Update to constitution-enforcer skill validation logic
  5. Communication to all team members

Version History:

  • v1.0 (Initial) - 9 Articles established

Summary

Article Principle Enforced By
I Library-First constitution-enforcer
II CLI Interface constitution-enforcer
III Test-First constitution-enforcer, test-engineer
IV EARS Format constitution-enforcer, requirements-analyst
V Traceability traceability-auditor
VI Project Memory All skills (steering system)
VII Simplicity Gate constitution-enforcer (Phase -1)
VIII Anti-Abstraction constitution-enforcer (Phase -1)
IX Integration Testing test-engineer

Powered by MUSUBI - Constitutional governance for specification-driven development.