Shared engineering laws for repositories at System F Software.
It sets baseline requirements for clean code: a pure functional core behind a thin imperative shell, domain types before logic, property tests, and deleting code before writing more. Principles are stack-neutral, so they apply to any language.
flowchart LR
S["<b>systemfsoftware/constitution</b><br><i>Upstream Repository</i>"] -->|git subtree| A[Consumer Repo A]
S -->|git subtree| B[Consumer Repo B]
S -->|git subtree| C[Consumer Repo C]
A -.symlink.-> S
B -.symlink.-> S
C -.symlink.-> S
The rules split into two files based on when an agent needs to see them:
constitution/
├── CONSTITUTION.md # Resident: loaded on every run
└── CONSTITUTION-ARTICLES.md # On demand: retrieved when editing source files
| File | Delivery | Contents | How to load it |
|---|---|---|---|
CONSTITUTION.md |
Always on | Preamble, rule enforcement and Conduct (Article V) | Include in agent context on every turn (@CONSTITUTION.md in AGENTS.md or CLAUDE.md) |
CONSTITUTION-ARTICLES.md |
On demand | Articles I to IV (Pure Core, Boundaries, Testing, Project Layout) | Load via tool hook or path rule when editing source code (never on read) |
Rules about conduct and rule enforcement stay resident because nothing triggers them after a mistake happens. Craft rules (like how to structure a domain model or write a test) only need to load when someone touches source code.
Vendor the repository using git subtree and symlink both files to the project root:
# 1. Fetch the remote into a local ref
git fetch https://github.com/systemfsoftware/constitution.git main:refs/remotes/vendor/constitution
# 2. Add as a squashed subtree
git subtree add --prefix=vendor/constitution refs/remotes/vendor/constitution --squash \
-m "chore: vendor shared constitution"
# 3. Symlink both files to the repo root
ln -s vendor/constitution/CONSTITUTION.md CONSTITUTION.md
ln -s vendor/constitution/CONSTITUTION-ARTICLES.md CONSTITUTION-ARTICLES.mdIf the repository is brand new, create an initial commit first (git commit --allow-empty -m "init").
- Add
@CONSTITUTION.mdtoAGENTS.mdorCLAUDE.md. - Set up a path-scoped rule (
.claude/rules/or.cursor/rules/) to provideCONSTITUTION-ARTICLES.mdwhen editing source files.
| Article | File | Mode | Core rules |
|---|---|---|---|
| I: Pure Core | CONSTITUTION-ARTICLES.md |
Retrieved | Pure decisions, explicit types, tagged error variants, no null states. |
| II: Boundaries | CONSTITUTION-ARTICLES.md |
Retrieved | Functional core / imperative shell, values for effects, decode inputs rather than casting. |
| III: Verification | CONSTITUTION-ARTICLES.md |
Retrieved | Testing Trophy, property tests over examples, mutation testing to measure coverage. |
| IV: Organization | CONSTITUTION-ARTICLES.md |
Retrieved | Organize by domain responsibility, clear naming, keep modules small. |
| V: Conduct | CONSTITUTION.md |
Always on | Fix root causes, challenge decisions before committing, remove code before adding. |
Pull upstream changes into the subtree without changing existing symlinks:
git subtree pull --prefix=vendor/constitution https://github.com/systemfsoftware/constitution.git main --squash \
-m "chore: update shared constitution"Every rule is defined in structured YAML:
- id: CONST-S4
title: Subtract Before You Add
gate: review
do: treat every line as a liability — removal is the default response to slop
dont: extend a copy-paste cluster; patch around a rotten core
harm: the codebase only grows; rot survives every patch and regrows
check: review reads the net line delta; fixes that leave root violations are rejectedRun the validator to check rule IDs, schema compliance, and references across both files:
pnpm testAmendments need a written explanation, a version bump, and updates to consuming repos. See AGENTS.md for commit standards and testing guidelines.
Apache-2.0 (c) 2026 Ryan Lee.