Make the intent clear.
Write the purpose, users and non-negotiable outcomes in language the whole team understands.
[01] AN OPEN FRAMEWORK FOR AI DEVELOPMENT
Code evolves. Your product’s promises should endure. Give people and AI a shared constitution for what must stay true.
The promise stays.
The code evolves.
Shared intent.Protected principles.Verifiable change.
HUMAN DIRECTION × AI CAPABILITY01 / THE METHODOLOGY
Before another line of code, agree on the heart of the product.
Constitution-First Development turns that agreement into a small set of protected laws. Everyone can understand them. Developers can implement them. Tests and review make changes accountable.
AI has room to improve how the software works. Changes to what the product fundamentally promises follow an explicit amendment process.
Write the purpose, users and non-negotiable outcomes in language the whole team understands.
Connect each law to code boundaries, tests and named human owners who review amendments.
Check the affected promises before a release, and record what was tested and what remains unknown.
02 / A SHARED SOURCE OF TRUTH
From the boardroom to the pull request.
Choose your perspective.
A CEO, designer, customer success lead and engineer should be able to read the same promises and agree on what they mean.
The human README explains who the product serves, the problem it solves and the outcomes an update must protect.
Read the six foundation lawsWe help teams manage projects, invoices and shared responsibilities without losing control of their information.
Your records. Your access boundaries.
The workflows you already rely on.
The layout, the performance and the way features are built — while those promises hold.
A clear ID, a precise promise, a responsible owner and a meaningful check turn a principle into an engineering task.
Keep the structured laws authoritative. Generate the readable version, protect both, and connect them to tests of actual behaviour.
{
"methodology": "Constitution-First Development",
"version": "1.0.0",
"law": {
"id": "LAW-002",
"title": "Preserve customer data",
"promise": "Ordinary upgrades preserve existing records.",
"checks": ["migration_preserves_records"],
"amendment": "authorised human review required"
}
}Review the change against the approved baseline. Check the evidence, the impact and the exact revision being released.
When a foundation needs to change, the proposal explains why. The accountable human decides. That decision belongs in the project history.
An ordinary feature change, assessed against the constitution.
03 / THE FOUNDATION LAWS
A reference constitution you can adapt to your product.
Select a law to see the intent, the example and the check.
The people responsible for a product decide when its fundamental promises change.
AI can propose an amendment. It must identify the law, explain the need, show alternatives and describe the impact. An authorised human reviews that proposal before it becomes the new baseline.
An AI proposes removing the approval step to make releases faster. That is a change to the constitution itself, so the existing approval process still applies.
# Replace @your-org/constitution-owners with real owners.
# Configure REQUIRED owner reviews in repository settings.
/laws.json @your-org/constitution-owners
/CORE-LAWS.md @your-org/constitution-owners
/AGENTS.md @your-org/constitution-owners
/amendments/ @your-org/constitution-owners
/scripts/ @your-org/constitution-owners
/tests/ @your-org/constitution-owners
/.github/ @your-org/constitution-owners
# This file routes reviews. It cannot enforce them alone.How to enforce it: Protect the laws, their tests, the validator and the release workflow. Require owner review and fresh approval through repository settings.
Installing a better version must not silently erase the work people have already done.
Preserve records, identities, relationships and permissions through ordinary upgrades. Plan migrations explicitly, verify the result and define how recovery will work before release.
Adding a project archive field preserves every existing project, its owner and its invoices. Removing customer records is a separate, explicitly authorised operation.
def test_upgrade_preserves_existing_records():
original = {
'id': 42, 'owner_id': 7,
'title': 'Studio launch', 'invoice_ids': [108]
}
upgraded = migrate_project(original.copy())
for field, value in original.items():
assert upgraded[field] == value
assert upgraded['archived'] is False
assert migrate_project(upgraded) == upgradedHow to enforce it: Run migration fixtures against realistic old data. Check values and relationships, not just the number of rows.
An improvement should keep the workflows your team and customers already rely on.
Record what the product promises to do. When implementation changes, check those outcomes again. Deliberate removals or changed promises need an agreed amendment and migration plan.
A redesigned invoice screen still exports the approved totals, tax and customer details. A new layout does not authorise deleting the export feature.
test('the redesign preserves invoice export', async () => {
const invoice = await fixtures.invoice({ total: 15000 });
await invoices.open(invoice.id);
const document = await invoices.exportPDF();
expect(document.customerId).toBe(invoice.customerId);
expect(document.totalInCents).toBe(15000);
expect(document.invoiceNumber).toBe(invoice.number);
});
// Test the promise, independently of the screen layout.How to enforce it: Use behaviour tests for approved journeys and contract tests for public interfaces. Review intentional changes instead of quietly rewriting failing expectations.
People can only read or change the data they are entitled to access.
Enforce authorisation on the server for every relevant action. A hidden button is useful interface design, but it is not an access control. Check object ownership as well as the account role.
A member changing an invoice ID in a request must not gain access to another organisation’s invoice.
function can_read_project( $project_id ) {
$project = get_post( $project_id );
if ( ! is_user_logged_in() || ! $project
|| 'project' !== $project->post_type ) {
return false;
}
$owner = (int) get_post_meta(
$project_id, '_owner_user_id', true
);
return $owner > 0
&& get_current_user_id() === $owner
&& current_user_can( 'read_post', $project_id );
}
// Single-owner example; ownership metadata is server-controlled.
// For shared teams, check verified account membership instead.How to enforce it: Test allowed access and denied access, including cross-account requests. In WordPress, combine nonce verification with capability and object-level checks.
Core actions should remain usable across input methods, screen sizes and access needs.
Define the interaction contract: keyboard operation, visible focus, meaningful names, touch access and reduced motion. Treat these as product behaviour when the interface changes.
A menu that previously opened on hover also needs a usable keyboard and touch path. A modal returns focus to the control that opened it.
test('dialog preserves the keyboard journey', async ({ page }) => {
const trigger = page.getByRole('button', { name: 'Edit project' });
await trigger.focus();
await page.keyboard.press('Enter');
await expect(page.getByRole('dialog')).toBeVisible();
await expect(page.getByLabel('Project name')).toBeFocused();
await page.keyboard.press('Escape');
await expect(trigger).toBeFocused();
});How to enforce it: Combine automated checks with real keyboard, touch and assistive-technology review. Automated scans do not cover every accessibility requirement.
The team should be able to see what changed, what was checked and what remains uncertain.
Tie the release to the exact source revision and constitutional version. Record test results, relevant reviews, limitations and recovery instructions. An AI-written “compliant” label is not evidence.
A production ZIP names its version and the rules used to assess it. A failing or missing required check blocks release until it is resolved.
{
"constitution_version": "1.0.0",
"source_commit": "<exact commit SHA>",
"checks": [
{ "name": "migration", "result": "<CI result>" },
{ "name": "access boundaries", "result": "<CI result>" }
],
"human_review": "<verified review URL>",
"limitations": ["<unverified environments>"],
"recovery": "<tested recovery procedure>"
}How to enforce it: Require real test results and recorded human review. Keep approval authority outside files the proposing agent can edit.
Protect essential behaviour, data and authority. Keep colours, layouts and implementation choices flexible unless your product has a specific reason to make them part of its contract.
04 / SEE IT IN PRACTICE
Try a change request. See where the constitution
allows progress — and where a human needs to decide.
“Make the project dashboard simpler and faster.”
Layout, components, styling and loading strategies.
Approved workflows, server-side permissions, keyboard navigation and customer records.
Regression checks, access tests and responsive interaction review. A passing mock-up alone is insufficient.
“Automatically delete all projects after one year.”
A blanket deletion policy changes LAW-002 and the product’s promise to preserve customer records.
Archive older projects while retaining records, ownership and a way to restore them.
If deletion is still needed, propose the scope, retention rules, consent, migration and recovery limits. Await explicit approval.
“Remove the access check to fix this error quickly.”
Removing server-side authorisation can expose another customer’s records and violate LAW-004.
Diagnose the role mapping, account relationship or request. Correct the fault while keeping the access check.
Show that legitimate users succeed and unauthorised users are denied. A working button is only half the test.
Illustrative decisions for the reference laws above. This demo does not scan a repository or approve a real change.
05 / THE AMENDMENT PROTOCOL
A constitution is a commitment to a clear process when the fundamentals need to change.
Get the amendment templateName the law and the exact proposed change. Pause the work that would violate it.
Document the reason, affected users, risks and options that preserve the current law.
An authorised owner reviews the exact proposal. The proposing AI cannot approve its own exception.
Update the approved law and checks together. Keep the decision, evidence and recovery plan with the release.
06 / MAKE IT PART OF YOUR REPOSITORY
Start small. Adapt the laws to the product.
Build evidence as your implementation grows.
A readable constitution, structured laws, agent instructions, a runnable example, tests and amendment templates. Everything needed to understand the approach and begin adapting it.
project/
├── README.md # Purpose, for everyone
├── CORE-LAWS.md # Human-readable promises
├── laws.json # Structured source of truth
├── AGENTS.md # Instructions for coding agents
├── amendments/ # Proposals and decisions
├── scripts/ # Constitutional checks
├── tests/ # Evidence about behaviour
└── .github/
├── CODEOWNERS # Who reviews the foundations
└── workflows/ # Checks before merge# Development instructions
1. Read CORE-LAWS.md and the task before changing code.
2. Identify the laws and approved behaviours affected.
3. Make the smallest complete change that fulfils the task.
4. Run the required checks and report their actual results.
5. Never weaken a law or its tests to make a change pass.
6. If a law must change, prepare an amendment proposal.
7. Wait for an authorised human to approve that amendment.
A request for a new feature is not approval to rewrite a law.Connect your real owners, protect the branch and add product-specific tests. Downloading files alone does not enforce the constitution.
A FEW GOOD QUESTIONS
Constitution-First Development is an open methodology proposed by Nic Sinko, with OKNIS as the founding organisation. Version 1.0 is a practical starting point for teams to adopt and improve. It is not a certification or a standard issued by a standards body.
A style guide helps code look consistent. A product constitution describes the outcomes and boundaries the software must protect. The methodology connects those promises to tests, architecture, human ownership and an amendment process. It builds on established engineering practices.
No. Tests cover known expectations, and reviews can miss problems. The aim is to make unintended changes easier to detect, harder to merge and more accountable. Your enforcement is only as strong as the checks, repository controls and review practice you actually configure.
No. Work that conforms to existing laws can follow your normal development process. A protected-law amendment needs explicit owner approval. A colour adjustment or an internal refactor does not automatically become a constitutional decision.
Yes. Begin by describing the promises your users already rely on. Choose a few that matter most, capture representative behaviour in tests and document gaps honestly. Add enforcement gradually instead of claiming that an untested legacy system is already compliant.
This plugin publishes the methodology and supplies the starter kit. The checks and approval controls must be installed in each development repository. The landing page does not inspect your code, certify compliance or change your other plugins.