Philosophy
The concepts that shape the system.
The Pillars
The four principles the system rests on.
- Specs & Checks
- Layering
- Harmony
- Shepherding
Specs & Checks
Specs & Checks is a claim paired with its proof. What is wanted gets documented and specified first. What is built gets shown, and checked against what was written. Done means demonstrated.
The writing lives with the work. The docs sit beside the code, and the standards sit beside the project. A wiki shows all of it as one readable whole.
- Write before building
- Every case verified
- Demos over status reports
- Knowledge filed where it belongs
Layering
Layering is structure in small, dedicated pieces. Layering starts from single responsibility: one piece, one job. A small piece is easier to check and harder to get wrong, and a small piece gives focus.
Every layer rests on the layer below, and is made solid before the next layer goes on top. The same shape repeats at every scale, from a whole project down to a single page.
Two layers can be held against each other. A gap between the two shows what is missing.
- One purpose per file
- One step per change
- Prerequisites before features
- Layers checked against each other
- Converge only once proven
Harmony
Harmony is tension held in balance. Two forces pull in opposite directions, and neither wins. A suspension bridge stands because of tension, and so does a project.
The tension lives between standards and inside them: brevity pulls at completeness, and strictness pulls at pragmatism. Creative humans pull toward change, and rigid systems pull toward what was written. Agents do the work in between, held by both.
Keep both sides of a tension. Fine-tune the balance between them, and weigh how far the tuning goes. Dropping one side breaks the bridge, and averaging the two produces mush.
- Conflicts surfaced and settled
- Deliberate trade-offs
Shepherding
Shepherding is guidance built into the environment. Work takes the shape of its environment, so guardrails in the way of working make the right move the obvious move.
The strongest guardrail is an example. An agent repeats what the agent reads, so every page follows the rules the page states. The docs of the system are written by the system's own standards.
A rule followed everywhere stops needing attention. The rule becomes a habit, and the habit becomes character.
Strictness is a kindness: every removed choice removes a debate, and then a mistake. An agent wants to produce, and a guardrail makes the agent wait until the director knows what is wanted. A fence that lives in one head fades, so every fence is written down.
A rule can still be broken. A rule is called a rule because a suggestion was skipped too easily, so breaking the rule stays possible and gets harder. As agents grow, the strictness can fade. The strictness of a rule is a tension too, held in balance like every other.
- Lead by example
- Conventions enforced by tooling
- Written ways of working
- Strict defaults
- One obvious path per task
- Sweeps that bring old work in line with a new rule
The Pillars Together
The four pillars work through each other.
Specs layered on docs can be verified against each other. The difference between the two layers is the tension and the harmony in one.
- Layering gives Specs & Checks small pieces to check.
- Harmony keeps Shepherding kind, because the strictness of a rule is a tension too.
- Shepherding holds the other three in place.
The Chair Test
A pillar earns its place by removal, the way a chair shows which legs it needs.
- Without Specs & Checks there is no shared truth.
- Without Layering the work arrives big, late and unverifiable.
- Without Harmony the rules tear each other apart.
- Without Shepherding the other three need enforcing forever.
Four legs, no spares.
The Benefits
- The project has one shared truth, and the checks keep that truth honest.
- A conflict between two rules is settled once, in the open.
- A caught mistake strengthens the harness, so the system heals itself and keeps learning.
- The director is free for judgment, taste and creation.
Will AI Replace You?
The expected answer is no. The better answer is yes: you replace the parts of your own work that bore you. What stays is the part you wanted all along, to direct and to create.