Principles
Twenty non-negotiables the rate limiter — and every feature in the project — answers to.
These aren't authored per feature — they're inherited. spectastic init --profile enterprise composes this floor before a word of spec is written, and it's the strictest of the four profiles. The rate-limiter's spec, design, and tasks are all checked against it — §1 of the design re-walks the relevant ones.
§1 Purpose & scope
Project-wide rules, not feature rules. Every spec in this project inherits them; a design opens by re-walking each relevant one and must clear it or record an accepted risk. The enterprise profile turns them from advice into an enforced floor — the difference the walkthrough is really about.
§2 The twenty principles
Prefer the simplest code the next reader — human or agent — can follow. Clever indirection is a cost, not a flex.
Ship in slices. Every change should be easy to revert; a large irreversible batch is a design smell.
Name things. No hidden magic, no action-at-a-distance an agent can't see from the code in front of it.
A single formatter and lint config, applied automatically. Style is decided once and enforced by the toolchain, not debated per PR.
Decisions carry their rationale. Code says what; a decision log or comment says why it had to be this way.
Code that ships carries a test for the behavior it adds. The demoable path is covered before it merges.
Every level of testing is produced — unit, integration, and a behavioral check on the running code. Presence is never accepted as proof.
A change to a working system ships behind a toggle, off by default, reaching users by a deliberate, reversible flip.
A claim without a cited source is not yet a decision. Every design-bearing choice records the evidence it rests on.
When a gate tool fails, fix the gate before removing it. Disabling a gate is a last resort — explicit and recorded, never a silent convenience.
A component that exposes an interface ships a checked-in contract before the code behind it — the agent's target and the consumer's guarantee.
Keep the reusable core separate from its entry point. Logic lives in a testable library; the endpoint or UI is a thin adapter.
Safe defaults are the floor: no hardcoded credentials, secrets from the environment, authorization on by default. Every insecurity is a reviewed exception.
Grant the narrowest capability that does the job — to a service, a token, and an autonomous agent alike. Bound the blast radius first.
The running system emits the golden signals (latency, traffic, errors, saturation) through a standard exporter — health observed in production, not guessed from logs.
Each production-facing reliability target is an SLO with an explicit SLI and error budget. The remaining budget, not opinion, sets the pace of change.
Versions are MAJOR.MINOR.PATCH — a compatibility contract dependents and agents can reason about mechanically before an upgrade.
Pin, audit, and prune dependencies; adding one is a reviewed decision, not a reflex. Bound the blast radius at the manifest.
Publish an SBOM and a build attestation for every release, so a consumer can verify what went into an artifact and where it came from.
A user-facing product meets audited WCAG 2.x AA. A service or CLI with no user-facing surface satisfies this trivially.
§3 Governance
Principles change only by proposal, and the set carries a semantic version. The enterprise profile also declares the enforcement policy — the tool categories the rigor requires — which spectastic enforce checks and the design resolves to concrete tools.
§4 Change log
One file. Renders anywhere. Degrades to readable static HTML.