pa

Core principles

These bind every spec, design, and task in this project. Deviations require an amendment to this document and a version bump.

P-1 · Clarity over cleverness

Prefer the simplest code the next reader — human or agent — can follow. Clever indirection is a cost, not a flex.

P-2 · Small, reversible changes

Ship in slices. Every change SHOULD be easy to revert; a large irreversible batch is a design smell.

P-3 · Explicit over implicit

Name things. No hidden magic, no action-at-a-distance an agent can't see from the code in front of it.

P-4 · One set of conventions, enforced

A single formatter and lint config, applied automatically. Style is decided once and enforced by the toolchain, not debated per PR.

P-5 · Record the why

Decisions carry their rationale. Code says what; a decision log or comment says why it had to be this way.

P-6 · Tests accompany behavior

Code that ships carries a test for the behavior it adds. The demoable path is covered before it merges.

P-7 · Done means verified

Every level of testing is produced — unit, integration, and a behavioral check that exercises the running code. Where no framework exists, build a minimal tool to self-verify. Presence is never accepted as proof.

P-8 · Ship dark by default

A change to a working system ships behind a toggle, off by default — it reaches users by a deliberate, reversible flip. Standing the system up the first time is not a change to gate.

P-9 · Decisions are grounded

A claim without a cited source is not yet a decision. Every design-bearing choice records the evidence it rests on.

P-10 · The enforcement floor holds

When a gate tool fails — a version incompatibility, a new toolchain, a false positive — fix the gate (bump the tool, adjust its config, pin a known-good version) before removing it. Disabling or loosening a gate is a last resort that is explicit and recorded, never a silent convenience.

P-11 · Contract-first interfaces

A component that exposes an interface ships a checked-in contract (OpenAPI, JSON Schema, or a typed signature) before the code behind it. The contract is the agent's target and the consumer's guarantee.

P-12 · Library-first boundaries

Keep the reusable core separate from its entry point. Logic lives in a testable, importable library; the CLI, endpoint, or UI is a thin adapter over it.

P-13 · Secure by default

Safe defaults are the floor: no hardcoded credentials, secrets from the environment, authorization on by default. Every insecurity is an explicit, reviewed exception, never an accident.

P-14 · Least privilege

Grant the narrowest capability that does the job — to a service, a token, and an autonomous agent alike. Bound the blast radius before you widen the access.

P-15 · Structured observability

The running system emits the golden signals (latency, traffic, errors, saturation) through a standard metrics registry or exporter, so its health is observed in production, not guessed at from logs.

P-16 · Service level objectives

Each production-facing reliability target is written as an SLO with an explicit SLI and error budget. The remaining budget, not opinion, sets the pace of change.

P-17 · Semantic versioning

Release versions are MAJOR.MINOR.PATCH, a compatibility contract: a breaking change bumps MAJOR, a backward-compatible feature MINOR, a fix PATCH. Dependents and agents then reason mechanically about whether an upgrade is safe.

P-18 · Supply-chain hygiene

Pin, audit, and prune dependencies; adding one is a reviewed decision, not a reflex. Agents pull transitive forests, so bound the blast radius at the manifest.

P-19 · Supply-chain provenance

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.

P-20 · Accessibility conformance

A user-facing product meets formal, audited WCAG 2.x AA — for such a product a regulated obligation, not a finishing touch. A service or CLI with no user-facing surface satisfies this trivially.

Scope

Governance

Owners

Project owner — fill in.

Decision style

Owner decides; propose changes by PR.

Amendment process

PR to this file with a version bump and a Sync Impact Report.

Versioning

Semver. MAJOR = principle removed/redefined. MINOR = principle added. PATCH = wording.

Change log