Skip to content

[01] AN OPEN FRAMEWORK FOR AI DEVELOPMENT

Build faster.
Keep your
foundations.

Code evolves. Your product’s promises should endure. Give people and AI a shared constitution for what must stay true.

VERSION 1.0OPEN SOURCEBY OKNIS
SYSTEM / FIRST PRINCIPLES+
CORE-LAWS.mdTHE PRODUCT CONSTITUTIONPROTECTED

The promise stays.
The code evolves.

01Human-approved foundations
02Customer data is preserved
03Approved behaviour endures
GOVERNS
</>ImplementationFree to improve. Required to conform.
v1 → v2 → v3
REFERENCE ARCHITECTURECFD — 001

Shared intent.Protected principles.Verifiable change.

HUMAN DIRECTION × AI CAPABILITY

01 / THE METHODOLOGY

Start with what
must stay true.

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.

01 — DEFINE

Make the intent clear.

Write the purpose, users and non-negotiable outcomes in language the whole team understands.

02 — PROTECT

Give promises a structure.

Connect each law to code boundaries, tests and named human owners who review amendments.

03 — VERIFY

Bring evidence to change.

Check the affected promises before a release, and record what was tested and what remains unknown.

02 / A SHARED SOURCE OF TRUTH

One constitution.
Understood by everyone.

From the boardroom to the pull request.
Choose your perspective.

PURPOSE BEFORE IMPLEMENTATION

What does the product
actually stand for?

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 laws
M↓ README.mdEXAMPLE / TEAM WORKSPACE
OUR PRODUCT, IN PLAIN ENGLISH

A dependable home
for a team’s work.

We help teams manage projects, invoices and shared responsibilities without losing control of their information.

We protect

Your records. Your access boundaries.
The workflows you already rely on.

We can improve

The layout, the performance and the way features are built — while those promises hold.

A law changes only through an explained, human-approved amendment.
PROMISES BECOME CONTRACTS

Give each law
something to enforce.

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.

IMPLEMENTATION NOTEThis is a schema illustration. The download includes the full schema, validator and runnable examples.
laws.json / excerpt
{
  "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"
  }
}
{ } Human intent → a testable contract
DECISIONS WITH A RECORD

Show your working.
Protect the decision.

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.

THE APPROVAL BOUNDARYA text file saying “approved” is not proof of approval. Use protected repository reviews with real human owners.
CHANGE REVIEWILLUSTRATIVE RECORD

Archive completed projects

An ordinary feature change, assessed against the constitution.

Affected law
LAW-002 · Preserve customer data
Expected behaviour
Hide archived projects from the active view; keep records and relationships.
Evidence needed
Migration, restore and permission tests on the proposed revision.
Decision owner
The authorised project maintainer
REVIEW STATUSAwaiting actual evidence

03 / THE FOUNDATION LAWS

Six promises.
A stronger starting point.

A reference constitution you can adapt to your product.
Select a law to see the intent, the example and the check.

LAW-001REFERENCE LAW / v1.0

Humans approve the foundations.

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.

IN THE REAL WORLD

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.

</> See the developer example
.github/CODEOWNERS
# 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.

LAW-002REFERENCE LAW / v1.0

An upgrade keeps your data.

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.

IN THE REAL WORLD

Adding a project archive field preserves every existing project, its owner and its invoices. Removing customer records is a separate, explicitly authorised operation.

</> See the developer example
test_migration.py · illustrative excerpt
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) == upgraded

How to enforce it: Run migration fixtures against realistic old data. Check values and relationships, not just the number of rows.

LAW-003REFERENCE LAW / v1.0

New features respect existing ones.

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.

IN THE REAL WORLD

A redesigned invoice screen still exports the approved totals, tax and customer details. A new layout does not authorise deleting the export feature.

</> See the developer example
invoice-export.spec.ts · illustrative excerpt
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.

LAW-004REFERENCE LAW / v1.0

Private stays private.

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.

IN THE REAL WORLD

A member changing an invoice ID in a request must not gain access to another organisation’s invoice.

</> See the developer example
permissions.php · illustrative excerpt
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.

LAW-005REFERENCE LAW / v1.0

Everyone gets a usable interface.

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.

IN THE REAL WORLD

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.

</> See the developer example
dialog.spec.ts · illustrative excerpt
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.

LAW-006REFERENCE LAW / v1.0

Every release brings its evidence.

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.

IN THE REAL WORLD

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.

</> See the developer example
release-evidence.json · illustrative excerpt
{
  "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.

LAWS ≠ PREFERENCES

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

Same request.
A more deliberate response.

Try a change request. See where the constitution
allows progress — and where a human needs to decide.

WITHIN THE EXISTING LAWS

Proceed.
Keep the promises intact.

“Make the project dashboard simpler and faster.”

WHAT AI CAN CHANGE

Layout, components, styling and loading strategies.

WHAT IT MUST PRESERVE

Approved workflows, server-side permissions, keyboard navigation and customer records.

EVIDENCE BEFORE RELEASE

Regression checks, access tests and responsive interaction review. A passing mock-up alone is insufficient.

AMENDMENT REVIEW REQUIRED

Pause the conflicting change.
Explain the trade-off.

“Automatically delete all projects after one year.”

THE CONFLICT

A blanket deletion policy changes LAW-002 and the product’s promise to preserve customer records.

A SAFER ALTERNATIVE

Archive older projects while retaining records, ownership and a way to restore them.

THE HUMAN DECISION

If deletion is still needed, propose the scope, retention rules, consent, migration and recovery limits. Await explicit approval.

BLOCK THE CONFLICTING APPROACH

Keep the boundary.
Find a conforming fix.

“Remove the access check to fix this error quickly.”

THE CONFLICT

Removing server-side authorisation can expose another customer’s records and violate LAW-004.

A CONFORMING APPROACH

Diagnose the role mapping, account relationship or request. Correct the fault while keeping the access check.

EVIDENCE BEFORE RELEASE

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

Foundations can evolve.
Deliberately.

A constitution is a commitment to a clear process when the fundamentals need to change.

Get the amendment template
  1. 01

    Identify the conflict.

    Name the law and the exact proposed change. Pause the work that would violate it.

  2. 02

    Explain the alternatives.

    Document the reason, affected users, risks and options that preserve the current law.

  3. 03

    Get a human decision.

    An authorised owner reviews the exact proposal. The proposing AI cannot approve its own exception.

  4. 04

    Version, verify, record.

    Update the approved law and checks together. Keep the decision, evidence and recovery plan with the release.

06 / MAKE IT PART OF YOUR REPOSITORY

Your next commit
can start here.

Start small. Adapt the laws to the product.
Build evidence as your implementation grows.

A practical, open starter kit.

A readable constitution, structured laws, agent instructions, a runnable example, tests and amendment templates. Everything needed to understand the approach and begin adapting it.

  • Human and developer documentation
  • Python examples and executable checks
  • Repository review and release guidance
  • Amendment and evidence templates
Download the starter kit

ZIP ARCHIVE · v1.0 · GPL-2.0-OR-LATER

constitution-first-starter/
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
AGENTS.md · example
# 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.
SETUP REQUIRED

Connect your real owners, protect the branch and add product-specific tests. Downloading files alone does not enforce the constitution.

A FEW GOOD QUESTIONS

Clear principles.
Honest boundaries.

Is this an official industry standard?

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.

How is this different from a coding style guide?

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.

Can this guarantee that AI never introduces a bug?

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.

Does every small change need permission?

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.

Can an existing product adopt this?

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.

Does the WordPress plugin enforce other projects?

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.

HUMANS SET THE DIRECTION. AI HELPS BUILD IT.

Build something
you can stand behind.

Start with the constitution