Skip to main content

Chapter 14: The Constitutional Foundation

Learning Objectives​

By the end of this chapter, you will be able to:

  • Define what a constitution is in SDD: immutable principles that govern how specifications become code
  • Explain the Nine Articles model (Library-First, CLI Mandate, Test-First, Simplicity, Anti-Abstraction, Integration-First)
  • Implement pre-implementation gates: Simplicity Gate, Anti-Abstraction Gate, Integration-First Gate
  • Enforce constitutions through templates and phase gates
  • Understand the constitutional evolution and amendment process
  • Create a project constitution for your running project
  • Apply template-driven quality to constrain LLM output
  • Use [NEEDS CLARIFICATION] markers and prevent premature implementation details
  • Understand the compound effect of multiple constraints working together

What Is a Constitution?​

In Spec-Driven Development, a constitution is a set of immutable principles that govern how specifications become code. It sits above individual constraints—it is the meta-constraint that defines how constraints are applied and what values the entire development process must uphold.

Think of it like a national constitution. Laws (constraints) can change: speed limits, tax rates, building codes. But the constitution defines the fundamental structure: separation of powers, bill of rights, amendment process. The constitution is hard to change because it embodies the identity of the system. In SDD, the constitution embodies the identity of your development methodology.

Specifications say what to build. Constraints say what must never happen. The constitution says how we approach building—the principles that apply to every specification, every constraint, every implementation.

The Nine Articles Model​

The SDD methodology (from spec-driven.md) defines nine articles that form the constitutional foundation. We focus on the ones most relevant to constraint engineering and AI code generation.

Article I: Library-First Principle​

The principle: Every feature must begin as a standalone library. No feature shall be implemented directly within application code without first being abstracted into a reusable library component.

Why it matters: AI tends to generate monolithic code—everything in one place, tightly coupled. The Library-First principle forces modular design from the start. When the LLM generates an implementation plan, it must structure features as libraries with clear boundaries and minimal dependencies.

Real-world analogy: A chef doesn't add "salt to taste" by reaching into a bulk salt bin. The salt is in a shaker—a reusable, bounded component. Library-First does the same: every capability is packaged as a reusable unit before being used in the application.

Constitutional expression:

## Article I: Library-First Principle

Every feature in [Project] MUST begin its existence as a standalone library.
No feature shall be implemented directly within application code without
first being abstracted into a reusable library component.

### Implications
- New features create new library modules (or extend existing ones)
- Application code imports from libraries; libraries do not import from application
- Libraries have minimal dependencies; application wires them together

Article II: CLI Interface Mandate​

The principle: Every library must expose its functionality through a command-line interface. All CLI interfaces must accept text as input (stdin, arguments, files) and produce text as output (stdout). JSON format is supported for structured data exchange.

Why it matters: This enforces observability and testability. The LLM cannot hide functionality inside opaque classes—everything must be accessible and verifiable through text-based interfaces. You can test any library by running it from the command line. You can script it. You can inspect its behavior without a debugger.

Real-world analogy: A black box that only works when plugged into the main system is hard to test. A device with a standard USB port can be tested on any computer. The CLI mandate gives every library a "USB port"—a standard interface for inspection and verification.

Constitutional expression:

## Article II: CLI Interface Mandate

All libraries MUST expose functionality through a CLI:
- Input: stdin, arguments, or files (text)
- Output: stdout (text)
- Structured data: JSON format supported

### Implications
- Every library has a `main` or `cli` entry point
- Behavior can be verified without the full application
- Enables scripting and automation

Article III: Test-First Imperative​

The principle: All implementation MUST follow strict Test-Driven Development. No implementation code shall be written before: (1) unit tests are written, (2) tests are validated and approved by the user, (3) tests are confirmed to FAIL (Red phase).

Why it matters: This completely inverts traditional AI code generation. Instead of generating code and hoping it works, the LLM must first generate comprehensive tests that define behavior, get them approved, and only then generate implementation. This prevents "code that looks right but doesn't work" and ensures specifications are testable.

Real-world analogy: You don't build a bridge and then check if it holds weight. You define the load requirements first, then build to meet them. Test-First does the same: define the expected behavior (tests), then build to satisfy it.

Constitutional expression:

## Article III: Test-First Imperative

This is NON-NEGOTIABLE: All implementation MUST follow strict TDD.
No implementation code shall be written before:
1. Unit tests are written
2. Tests are validated and approved
3. Tests are confirmed to FAIL (Red phase)

### Implications
- Implementation plan must specify test file creation order
- Tests before source code in every task
- Red-Green-Refactor cycle enforced

Articles VII & VIII: Simplicity and Anti-Abstraction​

Article VII (Simplicity): Maximum 3 projects for initial implementation. No future-proofing. No speculative features. Start with the minimum that works.

Article VIII (Anti-Abstraction): Use framework features directly rather than wrapping them. Single model representation. No "we might switch frameworks" abstractions.

Why they matter: AI over-engineers. It creates abstraction layers "for flexibility," adds interfaces "for testability," and builds "for scale we don't have." These articles force justification for every layer of complexity. The implementation plan template's "Phase -1 Gates" directly enforce these principles.

Real-world analogy: A carpenter doesn't build a custom jig for every cut. They use the saw directly. Simplicity and Anti-Abstraction say: use the tools you have. Don't wrap them in "just in case" layers.

Constitutional expression:

## Article VII: Simplicity

- Maximum 3 projects for initial implementation
- Additional projects require documented justification
- No future-proofing or speculative features
- YAGNI: You Aren't Gonna Need It

## Article VIII: Anti-Abstraction

- Use framework features directly; do not wrap them
- Single model representation (no DTO + Entity + API model duplication without cause)
- No abstraction for "might switch X someday"
- Prefer concrete over abstract

Article IX: Integration-First Testing​

The principle: Tests MUST use realistic environments. Prefer real databases over mocks. Use actual service instances over stubs. Contract tests are mandatory before implementation.

Why it matters: Unit tests with mocks can pass while the integrated system fails. AI often generates tests that mock everything—tests that are green but meaningless. Integration-First ensures generated code works in practice, not just in theory.

Real-world analogy: A car's components might each pass bench tests, but the car might not start when assembled. Integration-First says: test the assembled system. Use real parts where possible.

Constitutional expression:

## Article IX: Integration-First Testing

Tests MUST use realistic environments:
- Prefer real databases over mocks
- Use actual service instances over stubs
- Contract tests mandatory before implementation
- E2E tests for critical paths

### Implications
- Mock only when necessary (external APIs, time-dependent logic)
- Integration tests run in CI with real DB (e.g., Testcontainers)
- Contract tests validate API shape before implementation

How Constitutions Are Enforced Through Templates and Phase Gates​

Constitutions are not merely documented—they are operationalized through templates and gates. The implementation plan template embeds constitutional checks. The LLM cannot proceed without passing them.

The Implementation Plan Template Structure​

# Implementation Plan: [Feature Name]

## Phase -1: Pre-Implementation Gates

### Simplicity Gate (Article VII)
- [ ] Using ≤3 projects?
- [ ] No future-proofing?
- [ ] No speculative features?

### Anti-Abstraction Gate (Article VIII)
- [ ] Using framework directly?
- [ ] Single model representation?
- [ ] No "might switch" abstractions?

### Integration-First Gate (Article IX)
- [ ] Contracts defined?
- [ ] Contract tests written?
- [ ] Real DB in integration tests?

### Complexity Tracking
If any gate fails, document justification here. Approval required.

---

## Phase 0: Setup
...

## Phase 1: Implementation
...

The template forces the LLM to answer these questions before generating code. The gates act as compile-time checks for architectural principles.

Phase Gate Enforcement​

When a gate fails, two paths:

  1. Fix the plan: Simplify the design, remove abstractions, add contract tests. The plan is revised until gates pass.

  2. Documented exception: If there is a legitimate reason (e.g., 4th project for shared contracts), it goes in "Complexity Tracking" with rationale and approval. This creates accountability—exceptions are visible and reviewed.

Pre-Implementation Gates in Detail​

Simplicity Gate (Article VII)​

Checklist:

  • Using ≤3 projects?
  • No future-proofing?
  • No speculative or "might need" features?

What it catches: Plans with 5+ projects, "we'll add caching for scale," "generic repository for future databases." The gate blocks these unless justified.

Example failure:

Plan: Create core/, domain/, application/, infrastructure/, api/ (5 projects)
Gate: FAIL — exceeds 3 projects
Action: Consolidate. Use 3: lib/, api/, tests/

Anti-Abstraction Gate (Article VIII)​

Checklist:

  • Using framework directly?
  • Single model representation?
  • No unnecessary wrappers?

What it catches: Custom repository interfaces when the ORM has one, wrapper services around framework auth, DTOs that duplicate entity fields with no transformation.

Example failure:

Plan: Create IUserRepository wrapping TypeORM's Repository
Gate: FAIL — framework has Repository<T>; use it directly
Action: Use TypeORM Repository<User> directly

Integration-First Gate (Article IX)​

Checklist:

  • Contracts defined (OpenAPI, etc.)?
  • Contract tests written?
  • Integration tests use real DB?

What it catches: Plans that start with unit tests and mocks, no API contract, no integration tests. The gate forces contract-first and integration tests.

Example failure:

Plan: Write unit tests with mocked UserRepository
Gate: FAIL — Integration-First requires contract tests and real DB
Action: Define OpenAPI contract first; write contract test; add integration test with Testcontainers

Constitutional Evolution and Amendment Process​

Constitutions are immutable in spirit but not frozen. They can evolve when the rationale for change is strong.

Amendment Process​

## Amendment Process

Modifications to this constitution require:
1. Explicit documentation of the rationale for change
2. Review and approval by project maintainers
3. Backwards compatibility assessment
4. Dated amendment record

When to Amend​

  • Technology change: A new framework makes an article obsolete (e.g., "use framework X" when you've migrated to Y).
  • Team learning: The team has found a better approach through experience.
  • Scale change: The project has grown; "max 3 projects" no longer fits. Document why and update.

Amendment Record​

Keep a log of changes:

## Amendment History

| Date | Article | Change | Rationale |
|------|---------|--------|-----------|
| 2026-03-09 | VII | Max projects 3→4 | Shared contracts package needed for frontend/backend |
| 2025-11-01 | III | Clarified TDD | Added "tests approved before implementation" |

Tutorial: Create a Project Constitution​

Step 1: Choose Your Articles​

For your project, select which articles apply. Not every project needs all nine. Minimum recommended:

  • Article I (Library-First): If you have multiple features or packages
  • Article III (Test-First): Always—ensures testable specs
  • Article VII (Simplicity): Always—prevents over-engineering
  • Article VIII (Anti-Abstraction): Always—prevents unnecessary layers
  • Article IX (Integration-First): For APIs and services

Step 2: Create the Constitution Document​

Create memory/constitution.md or specs/global/constitution.md:

# [Project Name] Constitution

## Preamble

This constitution defines the immutable principles governing how specifications
become code in [Project]. All implementation plans and generated code must
comply with these articles.

## Article I: Library-First Principle
[Copy from above, customize for your stack]

## Article III: Test-First Imperative
[Copy from above]

## Article VII: Simplicity
[Copy from above]

## Article VIII: Anti-Abstraction
[Copy from above]

## Article IX: Integration-First Testing
[Copy from above]

## Amendment Process
[Copy from above]

## Amendment History
| Date | Article | Change | Rationale |
|------|---------|--------|-----------|
| (empty) | | | |

Step 3: Add Phase -1 Gates to Your Implementation Template​

If you use a template for implementation plans, add the gates section. If you use Spec Kit or similar, ensure the template includes Phase -1. If not, create a checklist file that every plan must satisfy.

Step 4: Integrate with AI Context​

Add to .cursor/rules/constitution.mdc:

---
description: Project constitution - immutable principles
globs: ["specs/**", "src/**"]
---

Before generating implementation plans or code, you MUST comply with
specs/global/constitution.md (or memory/constitution.md).

Key principles:
- Library-First: Features as standalone libraries
- Test-First: Tests before implementation
- Simplicity: ≤3 projects, no future-proofing
- Anti-Abstraction: Use framework directly
- Integration-First: Real DB, contract tests

Phase -1 gates must pass before implementation. Document exceptions in Complexity Tracking.

Step 5: Validate​

Ask AI to generate an implementation plan for a small feature. Review: did it pass the gates? Did it respect the constitution? Refine the constitution and rules based on what you observe.

Template-Driven Quality: How Templates Constrain LLMs​

The true power of constitutions lies in how they are embedded in templates. Templates act as sophisticated prompts that constrain LLM output in productive ways.

1. Preventing Premature Implementation Details​

The feature specification template explicitly instructs:

- ✅ Focus on WHAT users need and WHY
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)

This constraint forces the LLM to maintain proper abstraction levels. When an LLM might naturally jump to "implement using React with Redux," the template keeps it focused on "users need real-time updates of their data." Specifications remain stable even as implementation technologies change.

2. Forcing Explicit Uncertainty Markers​

Both templates mandate the use of [NEEDS CLARIFICATION] markers:

When creating this spec from a user prompt:
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question]
2. **Don't guess**: If the prompt doesn't specify something, mark it

This prevents the common LLM behavior of making plausible but potentially incorrect assumptions. Instead of guessing that a "login system" uses email/password authentication, the LLM must mark it as [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?].

Example:

## User Authentication

Users must authenticate to access the system.
[NEEDS CLARIFICATION: Authentication method? Email/password, SSO, OAuth, magic link?]

Password requirements:
[NEEDS CLARIFICATION: Min length? Complexity rules?]

3. Structured Thinking Through Checklists​

Templates include checklists that act as "unit tests" for the specification:

### Requirement Completeness

- [ ] No [NEEDS CLARIFICATION] markers remain
- [ ] Requirements are testable and unambiguous
- [ ] Success criteria are measurable

These checklists force the LLM to self-review systematically, catching gaps that might otherwise slip through.

4. Constitutional Compliance Through Gates​

The implementation plan template enforces architectural principles through phase gates (as described above). If a gate fails, the LLM must document why in "Complexity Tracking," creating accountability.

5. Hierarchical Detail Management​

Templates enforce proper information architecture:

**IMPORTANT**: This implementation plan should remain high-level and readable.
Any code samples, detailed algorithms, or extensive technical specifications
must be placed in the appropriate `implementation-details/` file

This prevents specifications from becoming unreadable code dumps. The LLM learns to maintain appropriate detail levels.

6. Test-First Thinking​

The implementation template enforces test-first development:

### File Creation Order
1. Create `contracts/` with API specifications
2. Create test files in order: contract → integration → e2e → unit
3. Create source files to make tests pass

This ordering constraint ensures the LLM thinks about testability and contracts before implementation.

7. Preventing Speculative Features​

Templates explicitly discourage speculation:

- [ ] No speculative or "might need" features
- [ ] All phases have clear prerequisites and deliverables

This stops the LLM from adding "nice to have" features that complicate implementation.

The Compound Effect of Multiple Constraints​

Constraints do not work in isolation. They compound. When multiple constraints apply together, they produce outcomes that no single constraint could achieve.

Example: Adding a New Feature​

Constitution: Test-First, Simplicity, Anti-Abstraction Architecture: Thin controllers, Repository-only DB Security: Auth required, No PII in logs

When AI generates a "user profile update" feature:

  1. Test-First forces tests before code → behavior is defined
  2. Simplicity prevents "profile service + profile manager + profile facade" → one service
  3. Anti-Abstraction prevents custom DTO layer → use framework's validation
  4. Thin controller keeps the endpoint as orchestration only
  5. Repository-only keeps DB access in UserRepository
  6. Auth required ensures the endpoint is protected
  7. No PII in logs ensures email/name aren't logged

The result: a simple, testable, secure endpoint that fits the architecture. No single constraint would have achieved this. The compound effect of all constraints shapes the output.

Synergy Matrix​

Constraint AConstraint BCompound Effect
Test-FirstIntegration-FirstTests that actually validate behavior
SimplicityAnti-AbstractionMinimal, direct implementation
Thin controllersRepository-onlyClear layer boundaries
Auth defaultNo PII in logsSecure and compliant
Library-FirstSimplicityReusable but not over-engineered

Preventing Premature Implementation Details​

One of the most valuable constitutional effects is preventing the LLM from jumping to implementation too early.

Without constraint: User says "add search." LLM generates: Elasticsearch setup, custom query builder, search service, API endpoint, frontend component—all in one response. Much of it may be wrong (maybe you use Postgres full-text, not Elasticsearch).

With constraint: The specification template says "focus on WHAT, not HOW." The LLM produces: "Users need to find items by keyword. Results should be ranked by relevance. Performance: results in < 500ms." No implementation details. The implementation plan comes later, with research and explicit technology choices.

The constitution, through the template, creates a phase separation: specification first (what), plan second (how), code last (implementation). This prevents wasted effort and wrong assumptions.

Forcing Explicit Uncertainty: [NEEDS CLARIFICATION]​

The [NEEDS CLARIFICATION] marker is a constitutional mechanism. It forces the LLM to admit what it doesn't know instead of guessing.

Without marker: LLM assumes "login" means email/password, generates code. Later: "We need SSO." Rework.

With marker: LLM writes [NEEDS CLARIFICATION: Auth method - email/password, SSO, OAuth?]. Human answers. Then implementation proceeds with correct assumption.

The marker creates a handoff point: the LLM signals uncertainty; the human resolves it. This prevents the LLM from making decisions that belong to the product owner or architect.

Best practices:

  • Use for any assumption the prompt doesn't specify
  • Be specific: "Auth method?" not "Need more info"
  • One clarification per marker
  • Resolve before implementation

Key Takeaways​

  1. A constitution is a set of immutable principles that govern how specifications become code. It sits above constraints and defines the identity of your development methodology.

  2. The Nine Articles (Library-First, CLI Mandate, Test-First, Simplicity, Anti-Abstraction, Integration-First) provide a proven constitutional model for SDD.

  3. Constitutions are enforced through templates and phase gates. The implementation plan template embeds Phase -1 gates (Simplicity, Anti-Abstraction, Integration-First) that must pass before implementation.

  4. Template-driven quality constrains LLMs: prevent premature implementation details, force [NEEDS CLARIFICATION] markers, use checklists, enforce test-first ordering.

  5. Amendment process allows evolution while maintaining stability. Document rationale, get approval, keep an amendment history.

  6. The compound effect of multiple constraints produces better outcomes than any single constraint. Constitutions, architecture constraints, and security/performance constraints work together.

Constitution vs. Constraints: The Hierarchy​

Understanding the relationship between constitution and constraints clarifies when to use each:

LevelDocumentScopeMutability
Constitutionconstitution.mdPrinciples governing how we buildAmended rarely, with process
Architecture Constraintsconstraints/architecture.mdStructural rules (layers, patterns)Evolve with architecture
Security/Performance Constraintsconstraints/security.md, performance.mdOperational rulesEvolve with requirements
Feature Constraintsfeatures/001-x/constraints.mdFeature-specific overridesPer-feature

The constitution does not replace constraints—it governs them. A constraint might say "controllers cannot contain business logic." The constitution says "we value simplicity and testability," which is why we have that constraint. When adding a new constraint, ask: does it align with our constitutional principles?

Constitutional Principles as Design Philosophy​

The constitution is not just a rulebook—it's a philosophy that shapes how LLMs think about code generation:

  • Observability Over Opacity: Everything must be inspectable (CLI mandate)
  • Simplicity Over Cleverness: Start simple, add complexity only when proven necessary (Simplicity, Anti-Abstraction)
  • Integration Over Isolation: Test in real environments, not artificial ones (Integration-First)
  • Modularity Over Monoliths: Every feature is a library with clear boundaries (Library-First)
  • Verification Over Hope: Tests define behavior before implementation (Test-First)

When the LLM encounters a design choice, these principles guide the decision. "Should I add a caching layer?" Simplicity says no—not until we have evidence we need it. "Should I mock the database?" Integration-First says no—use a real DB in tests.

Enforcing the Constitution in Practice​

For Human Developers​

  • Onboarding: New team members read the constitution first. It's the "why" behind the rules.
  • Code review: Reviewers check constitutional compliance. "Does this respect Test-First? Simplicity?"
  • Retrospectives: When something goes wrong, ask: did we violate a constitutional principle?

For AI Agents​

  • System prompt: Include constitution in the agent's system prompt or loaded context.
  • Template gates: Implementation plan template requires gate sign-off.
  • Rules: Cursor rules, .cursor/rules/, reference the constitution for every implementation task.

For CI/CD​

  • Plan validation: Script that parses implementation plans and verifies Phase -1 gates are addressed.
  • Complexity tracking: If gates fail, COMPLEXITY.md must exist and be referenced. CI can check this.

Common Constitutional Violations and Fixes​

ViolationArticleFix
Feature implemented in app code, not libraryIExtract to library first
No CLI for libraryIIAdd CLI entry point
Code before testsIIIDelete code, write tests first, then re-implement
5 projects for MVPVIIConsolidate to 3; document exception if legitimate
Custom wrapper around frameworkVIIIUse framework directly
All tests use mocksIXAdd integration tests with real DB
Spec includes "use React"TemplateRemove; focus on WHAT not HOW
Assumption without clarificationTemplateAdd [NEEDS CLARIFICATION]

Try With AI​

Prompt 1: Constitution Draft​

"I'm creating a constitution for my [describe project]. Based on the Nine Articles model, which articles should I include? For each, explain why it applies (or doesn't) to my project. Draft the constitution document with the articles that fit."

Prompt 2: Gate Compliance Check​

"Here's my implementation plan: [paste plan]. Check it against the Phase -1 gates: Simplicity (≤3 projects, no future-proofing), Anti-Abstraction (framework directly, single model), Integration-First (contracts, real DB). Does it pass? If not, what changes are needed?"

Prompt 3: [NEEDS CLARIFICATION] Audit​

"Review this specification: [paste spec]. Find every place where the LLM made an assumption that wasn't in the original prompt. Replace those with [NEEDS CLARIFICATION: specific question] markers. Show me the revised spec."

Prompt 4: Constitutional Violation Fix​

"This implementation violates our constitution: [paste code or plan]. Our constitution requires: Test-First, Simplicity (≤3 projects), Anti-Abstraction. Identify each violation and suggest how to fix it while preserving the feature's functionality."

Practice Exercises​

Exercise 1: Write Your Project Constitution​

Create a constitution for your current project (or a hypothetical one). Include at least Articles I, III, VII, VIII, and IX. Customize each for your stack (e.g., "use Express middleware directly" for Anti-Abstraction). Add the amendment process. Then ask a colleague or AI to review it for clarity and completeness.

Expected outcome: A complete constitution document ready for use.

Exercise 2: Add Phase -1 Gates to a Plan​

Take an existing implementation plan (yours or from a tutorial). Add a Phase -1 section with Simplicity, Anti-Abstraction, and Integration-First gates. Evaluate the plan against each gate. Does it pass? If not, revise the plan until it does, or document justified exceptions in Complexity Tracking.

Expected outcome: A plan that explicitly passes (or justifies exceptions for) all gates.

Exercise 3: Template Constraint Experiment​

Take a feature prompt: "Add file upload with progress indicator." Give it to AI twice: (1) with no template or constitution, (2) with a template that includes "focus on WHAT not HOW" and "[NEEDS CLARIFICATION] for ambiguities." Compare the outputs. How much did the template improve the specification? What assumptions did the unconstrained version make that the constrained version marked for clarification?

Expected outcome: A before/after comparison demonstrating template-driven quality improvement.

Chapter Quiz​

  1. What is a constitution in SDD, and how does it differ from a constraint?

  2. Name the Nine Articles. For Article III (Test-First), explain why it "inverts" traditional AI code generation.

  3. What are the three Phase -1 gates? What does each gate check?

  4. How does the implementation plan template enforce the constitution?

  5. When should you amend a constitution? What must the amendment process include?

  6. Explain "template-driven quality." How do templates constrain LLM output?

  7. What is the purpose of [NEEDS CLARIFICATION]? Give an example where it would prevent a wrong assumption.

  8. Describe the "compound effect" of multiple constraints. Give an example of two constraints that work together synergistically.

Appendix: Full Constitution Template​

# [Project Name] Constitution

## Preamble

This constitution defines the immutable principles governing how specifications
become code. All implementation plans, generated code, and development decisions
must align with these articles.

---

## Article I: Library-First Principle

Every feature MUST begin as a standalone library. No feature shall be implemented
directly in application code without first being abstracted into a reusable component.

---

## Article II: CLI Interface Mandate

All libraries MUST expose functionality through a CLI:
- Input: stdin, arguments, or files (text)
- Output: stdout (text)
- Structured data: JSON format supported

---

## Article III: Test-First Imperative

All implementation MUST follow strict TDD. No implementation code before:
1. Tests written
2. Tests approved
3. Tests confirmed FAILING (Red phase)

---

## Article VII: Simplicity

- Maximum 3 projects for initial implementation
- No future-proofing or speculative features
- YAGNI

---

## Article VIII: Anti-Abstraction

- Use framework features directly
- Single model representation
- No "might switch" abstractions

---

## Article IX: Integration-First Testing

- Prefer real databases over mocks
- Contract tests before implementation
- E2E for critical paths

---

## Amendment Process

1. Document rationale
2. Maintainer approval
3. Backwards compatibility assessment
4. Dated amendment record

---

## Amendment History

| Date | Article | Change | Rationale |
|------|---------|--------|-----------|

Summary: The Constraint Engineering Stack​

Part V has built a complete constraint engineering stack:

LayerDocumentPurpose
Constitutionconstitution.mdImmutable principles; how we build
Architectureconstraints/architecture.mdStructure, layers, dependencies
Securityconstraints/security.mdAuth, crypto, PII, validation
Performanceconstraints/performance.mdLatency, bundle, queries
Featurefeatures/*/constraints.mdFeature-specific overrides

Together with specifications (Part IV), this stack ensures that AI-generated code is not only correct but also compliant, secure, performant, and architecturally sound. Constraints protect systems from AI mistakes. The constitution ensures the protection is principled and consistent.

The Constitutional Mindset​

Adopting a constitutional foundation is as much a mindset as a document. Ask these questions before every implementation:

  1. Does this respect Test-First? Have we defined behavior in tests before writing code?
  2. Does this respect Simplicity? Are we adding the minimum necessary?
  3. Does this respect Anti-Abstraction? Are we using our tools directly?
  4. Does this respect Integration-First? Will our tests catch real integration issues?
  5. Does this respect Library-First? (If applicable) Is this packaged as a reusable unit?

When the answer is "no," fix the plan before writing code. The constitution is not a checklist to satisfy after the fact—it is a filter that shapes every decision from the start.