CONCEPTS
Design principles
The rules these workflows enforce are not new inventions. This page states each classical design principle, then shows exactly which rule in the project encodes it — and where the project deliberately qualifies or omits one.
How to read this page
Each principle below carries a status. Encoded directly means a rule states it as an obligation. Adopted with a condition means the principle applies only once a stated trigger is observed — the project treats unconditional application as a cost with no buyer. No dedicated rule means the project does not legislate it; the reason and the nearest related constraint are given instead.
Object-oriented design principles
Seven principles, in the order they matter to this project.
| Principle | Standard definition | Status |
|---|---|---|
SRP Single Responsibility Principle | A module should have one, and only one, reason to change. | Encoded directly |
LoD Law of Demeter | A unit should know as little as possible about the internals of other units. | Encoded directly |
OCP Open-Closed Principle | Software entities should be open for extension but closed for modification. | Adopted with a condition |
DIP Dependency Inversion Principle | High-level modules should not depend on low-level modules; both should depend on abstractions. | Adopted with a condition |
CRP Composite Reuse Principle | Prefer object composition over class inheritance to achieve reuse. | Adopted with a condition |
ISP Interface Segregation Principle | No client should be forced to depend on methods it does not use. | No dedicated rule |
LSP Liskov Substitution Principle | Objects of a subtype must be substitutable for their base type without breaking correctness. | No dedicated rule |
SRP
Single Responsibility Principle
A module should have one, and only one, reason to change.
This is the principle the project enforces hardest. The maintainability standard requires that one rule have one authoritative owner, and "scattered ownership of one invariant" is listed as a legitimate design pressure. When placing a change, business behavior belongs in the module that owns the relevant data and invariant; entry points stay thin. When several callers break because of one faulty rule beneath them, the shared owner is fixed rather than each symptom.
- CODE-02
- CODE-04
- DESIGN-04
- DOC-01
LoD
Law of Demeter
A unit should know as little as possible about the internals of other units.
Present as the local-reasoning requirement, which is part of the always-on rules rather than any single workflow. A maintainer must be able to understand control flow, state changes, external effects, and failure behavior without mentally executing dense expressions or tracing unrelated modules. The same wording appears in the design workflow’s maintainability standard, so it constrains proposed boundaries as well as written code.
- READ-02
- READ-03
- DESIGN-04
OCP
Open-Closed Principle
Software entities should be open for extension but closed for modification.
Adopted only after the variation axis exists. "Repeated conditionals along one real variation axis" and "multiple real algorithms or policies" are named as legitimate signals — the latter is where Strategy becomes justified. The inverse is refused just as explicitly: interfaces with one implementation, factories with one product, configuration nobody changes, and extension points created for hypothetical needs are all rejected by name. An extension point built before the second implementation exists is indirection with no buyer.
- DESIGN-01
- DESIGN-02
- DESIGN-03
DIP
Dependency Inversion Principle
High-level modules should not depend on low-level modules; both should depend on abstractions.
Dependency direction is a required section of every design proposal, alongside boundaries, responsibilities, contracts, and data ownership — so the question is always asked. Inversion itself is triggered by instability: "an unstable external dependency" is a named pressure, and an unstable third-party interface is the stated case where an Adapter is justified. Dependency isolation is also one of the targets of maintainability hardening. What the project does not require is an abstraction layer over a stable dependency; that falls back under the rejected speculative extension point.
- DESIGN-02
- DESIGN-03
- DESIGN-04
CRP
Composite Reuse Principle
Prefer object composition over class inheritance to achieve reuse.
The project does not rank composition against inheritance — enforcing a universal style guide is an explicit non-goal, and the repository’s own idiom wins. What it does legislate is the test that must pass before anything is shared at all: does it implement the same domain rule, should every caller change together when that rule changes, and does the proposed owner hold the relevant data and invariant? Code that merely looks alike stays duplicated. In practice this lands on the same side as composite reuse, because it forbids the coupling that inheritance-for-reuse creates.
- CODE-01
- CODE-03
- DESIGN-03
ISP
Interface Segregation Principle
No client should be forced to depend on methods it does not use.
There is no rule that legislates interface granularity, because granularity is a design decision the proposal is supposed to make, not a rule that can be checked from the outside. Two constraints reach it indirectly: "a missing stable public seam" counts as design pressure, and entry points are required to stay thin with behavior placed on the module that owns the invariant. Interface shape is therefore decided inside Code Design, under the same complexity budget as everything else.
- DESIGN-02
- CODE-04
LSP
Liskov Substitution Principle
Objects of a subtype must be substitutable for their base type without breaking correctness.
The project states no rule about type hierarchies, and this page will not pretend otherwise. Contract conformance is nevertheless checked, just at a different level: Review inspects correctness, failure behavior, and compatibility as separate axes, and completion requires every accepted behavior to be reconciled against fresh verification rather than assumed. A substitution that breaks a caller shows up there as a compatibility or correctness finding.
- REVIEW-01
- DONE-01
- DONE-02
The complexity budget
Three of the principles above are conditional for the same reason. The project’s stated objective is minimum necessary complexity — not minimum syntax, not maximum principle coverage. Three mechanisms enforce that.
No observed pressure, no new abstraction
Pressure must be nameable: hard-to-follow control flow, hidden mutation or I/O, semantic duplication that must change together, repeated conditionals along one real axis, an unstable external dependency, scattered ownership of an invariant, real construction combinations, or a missing stable public seam.
The novelty tax
An uncommon construct, reflection, metaprogramming, implicit runtime behavior, a new dependency, or a design pattern must deliver a concrete benefit in correctness, measured performance, framework alignment, or total maintenance cost. When justified, it is localized behind a clear boundary, named for intent, and explained by why it exists rather than how it works.
Patterns are priced, not scored
A design pattern is accepted only when the complexity and coupling it removes exceed the interfaces, classes, files, and indirection it introduces. A pattern name is not evidence of quality.
Constraints the classical principles do not cover
Object-oriented principles govern the shape of code. They say nothing about how an agent should behave around your repository, which is where the remaining failure modes live.
Ambiguity is resolved before implementation
A question is only allowed to block when different answers materially change user-visible behavior, interfaces, data semantics, permissions, security, compatibility, destructive effects, or acceptance criteria. Independent questions are batched; reversible internal details are inferred from the repository instead of asked.
- REQ-01
- REQ-02
- REQ-04
Approval is a separate, explicit act
The checkpoint carries five fixed items: goal, acceptance behavior, out of scope, assumptions, and solution boundary. Only action language sent after that checkpoint authorizes implementation. The initial request, answers to clarification questions, and a reading acknowledgement do not.
- REQ-03
- REQ-05
- REQ-06
Evidence precedes the claim
Where a stable automated seam exists, the first write after repair authorization is the regression test, and its failure must be observed before production code changes. Completion is not claimed without fresh, scope-appropriate command output, and each accepted behavior is either supported by that evidence or reported as incomplete.
- TEST-01
- TEST-03
- DONE-01
- DONE-02
Authority does not expand with invocation
Invoking a workflow grants no permission to commit, push, merge, publish, open issues, install dependencies, or modify global configuration. Repository state is inspected without disturbing unrelated changes, and work the agent did not do is never reverted, overwritten, or absorbed.
- SAFE-01
- SAFE-02
Which workflow owns which activity
A compact set of rules applies to every session automatically. The five workflows each deepen one segment of the loop, which is why they are invoked by name rather than loaded together.
| Activity | Owner | Guarantee |
|---|---|---|
| Requirement alignment and change control | Develop | Nothing is written before you approve a stated boundary. |
| Defect analysis and regression prevention | Diagnose | The root cause is evidenced; the test is red before the fix is green. |
| Boundary and complexity decisions | Code Design | Materially different options compared; lowest necessary complexity recommended; no production code written. |
| Independent quality inspection | Review | Eight axes checked from a fixed comparison point; the repository is never modified. |
| Cross-session continuity | Handoff | Eight required items, re-read from the repository rather than recalled. |
| Everyday discipline: reuse, readability, fresh verification | Engineering Core | Applies to every request with no command, and stays deliberately small. |
The trade-off is measured
The same discipline applies to the tooling. Controlled runs showed that loading a full workflow automatically for an ordinary task cost roughly a third more tool calls and input tokens while changing no outcome. The workflows were therefore made user-invoked and the always-on core was reduced rather than extended. A rule that cannot show a failure behind it does not get added; a rule that buys nothing gets removed.