Overview & Conformance
This specification is a public, normative declaration of the coding and working-style preferences that govern collaboration with an AI coding agent. It states, in plain and testable terms, how the agent should communicate, plan, verify, and ship work — so that the same expectations apply across every project, language, and session. The document is written for both humans and machines: a reader can adopt it as a style charter, and an agent can load it as operating context.
This specification covers the durable, generic posture of the collaboration. It describes communication norms, the working loop, verification discipline, code-level conventions, and the safety boundaries around secrets, version control, and automation.
It deliberately does NOT cover the internal wiring behind those preferences. Tooling names, private workflows, enforcement configuration, and project-specific paths are out of scope. What is published here is the stance; the machinery that implements the stance stays private.
How to Read This Specification
Section titled “How to Read This Specification”Each chapter declares a load-art — when it applies during a session. There are two kinds:
| Load-art | Meaning |
|---|---|
| always-on | The chapter applies to every interaction, regardless of context. It is part of the baseline and is never skipped. |
| conditional | The chapter applies only when its trigger context is present — for example, when files of a given kind are in play, when error codes are being defined, or at push time. Outside that context the chapter is dormant. |
Some chapters are mixed: a discipline part is always-on while a setup part is conditional. Each chapter states which part is which in its own metadata and intro.
Readers SHOULD treat always-on chapters as the permanent contract and conditional chapters as context-activated extensions. An agent loading this specification MUST honor every always-on chapter and MUST honor a conditional chapter whenever its trigger context applies.
Conformance
Section titled “Conformance”The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 (BCP 14) when, and only when, they appear in all capitals, as shown here.
A chapter marked Status: Normative carries binding requirements. A chapter or note explicitly marked Informative is explanatory only and imposes no requirements. An implementation conforms to this specification when it satisfies every applicable MUST and MUST NOT, and does not violate any applicable SHOULD without a stated, justified reason.
Chapter Index
Section titled “Chapter Index”| Chapter | Title | Load-art |
|---|---|---|
| 00 | Overview & Conformance | — |
| 01 | Communication & Language | always-on |
| 02 | Working Method & Autonomy | always-on |
| 03 | Verification & Testing | always-on (discipline) / conditional (setup) |
| 04 | Stack & Forbidden Constructs | conditional |
| 05 | Code Formatting | conditional |
| 06 | Class Architecture & Returns | conditional |
| 07 | Validation | conditional |
| 08 | Error Handling & Debugging | conditional (codes) / always-on (discipline) |
| 09 | Environment & Config | conditional (env) / always-on (no-auto-destroy) |
| 10 | Secrets & Privacy | always-on |
| 11 | Version Control & Commits | always-on |
| 12 | CI & Pre-Push Gates | conditional |
| 13 | Agent Safety Harness | always-on |