constitution.md

Why the constitution comes first

Architectural drift is the signature failure of AI-assisted engineering: as a chat grows, the model forgets earlier decisions, introduces a second HTTP client, bypasses the repository layer, or quietly relaxes a security rule. Prompt-level hints such as .cursorrules are transient; the constitution is the permanent, version-controlled sandbox that survives every prompt, commit, and branch.

• It resolves conflicts. When two requirements pull in different directions, the Core Principles say which wins.
• It bounds the solution. solution.md may only use technologies the constitution approves.
• It is the reviewer's checklist. MySpec's independent reviewer rejects a draft requirement, solution, or task that contradicts it.

Where it lives and when it is written

The interview that precedes it deliberately asks nothing technical - product, users, journeys, MVP scope only. Technology, architecture, testing, and security questions belong to the constitution's own collect substage, which is why the constitution ends up traceable to your answers rather than to the model's defaults.

The nine sections (MySpec)

All nine must be present, in this order. A section with nothing to say gets an explicit N/A, never a silent omission.

# Project Constitution: [Project Name]

## Project Vision
## Core Principles
## Technology Constraints
## Architecture Constraints
## Testing Approaches
## Coding Standards
## Security Constraints        (may be "N/A")
## Performance Targets         (may be "N/A")
## Integration Points          (may be "N/A")

A complete example

Short on purpose: three to five items per section is the sweet spot. Every line is traceable to something the user said.

# Project Constitution: A Generic Product

## Project Vision
Build a product that solves a real user problem with minimal friction, remains easy
to evolve over time, and can be confidently operated by a small team. Favor clarity
over cleverness and long-term maintainability over short-term velocity.

## Core Principles
- MVP scope only - focus on essential features first
- User-centric design - prioritize user experience in all decisions
- Performance first - optimize for speed and responsiveness

## Technology Constraints
- MUST use TypeScript for all frontend and backend code
- MUST use PostgreSQL as the primary database
- MUST use AWS services for cloud infrastructure

## Architecture Constraints
- Microservices architecture with clear service boundaries
- Stateless services for horizontal scalability
- Event-driven communication between services

## Testing Approaches
- Minimum 80% unit test coverage required
- Integration tests for all API endpoints
- E2E tests for critical user flows

## Coding Standards
- Functional programming style preferred
- Dependency injection required for testability
- ESLint and Prettier for code formatting

## Security Constraints
- OWASP Top 10 compliance required
- No secrets or credentials in code repositories
- All data encrypted at rest and in transit

## Performance Targets
N/A

## Integration Points
N/A

Need a production-grade starting point for a specific stack? The constitution.md templates page has Next.js 15 and FastAPI constitutions with prohibited-pattern lists, verification gates, and a decision-precedence hierarchy.

The Spec Kit constitution

The Spec Kit workflow mirrors GitHub Spec Kit's constitution-template.md: principles become numbered Articles (Roman numerals, three to seven of them, more than nine is over-prescriptive), genuinely non-negotiable ones are marked (NON-NEGOTIABLE), and the file carries its own version history.

<!--
SYNC IMPACT REPORT (constitution rev)
- Version: (initial) → 1.0.0
- Changed Articles: all new
- Downstream artifacts that may need re-sync: none (first ratification)
-->

# Photo Albums Constitution

## Core Principles

### I. Library-First
Every feature is implemented in a self-contained library first; the app is a thin
shell that wires libraries together.

### II. Test-First (NON-NEGOTIABLE)
TDD: tests written → user-approved → tests fail → implement. Red-Green-Refactor
strictly enforced.

### III. Integration-First Contracts
Integration tests define a feature's contract before any implementation detail.

## Additional Constraints
- Storage MUST default to SQLite for local dev; production may swap to PostgreSQL.
- All public APIs are versioned MAJOR.MINOR; breaking changes require a MAJOR bump.

## Development Workflow
PRs must pass the spec quality review; the Constitution Check gates in plan.md must
be re-evaluated for any new feature.

## Governance
Constitution supersedes all other practices. Amendments require an explicit PR, the
Sync Impact Report block updated, and approval from a code owner.

**Version**: 1.0.0 | **Ratified**: 2026-06-13 | **Last Amended**: 2026-06-13

• Sync Impact Report - an HTML comment at the top of every revision recording the SemVer bump and which downstream files (spec.md, plan.md, tasks.md) may need re-syncing.
• Governance - who can amend it, how, and the rule that added complexity must be justified.
• Footer - **Version** | **Ratified** | **Last Amended**, all three required.
• Constitution Check - plan.md re-evaluates Simplicity, Anti-Abstraction, and Integration-First gates against it for every feature.

Authoring and review rules

These are the rules MySpec's generator follows and its reviewer enforces. They are just as useful when you write one by hand.

How AI coding agents should use it

1. Read it first, every session. With the MySpec MCP server connected, the agent calls read_spec_file on the constitution before touching code; or download the bundle to .specs/ and reference the file from CLAUDE.md / .cursorrules.
2. Treat it as a gate, not a suggestion. A diff that adds an unapproved dependency, skips a verification command, or violates an architecture boundary is wrong even if it works.
3. Escalate instead of amending. If a task cannot be completed inside the constitution, the agent should say so; changing the constitution is a human decision (and, in Spec Kit, a versioned one).

You are an autonomous senior engineer. Before proposing any change, read and strictly
adhere to every invariant, prohibition, and verification gate in .specs/<bundle>/constitution.md.