Abstract: The contract-style-comments (CSC) methodology has matured from a function-level annotation practice into a deployable governance scaffold. The official CSC GitHub Template encodes the Agentic Trivium — CONTRACT.md, WHY.md, and QUICKSTART.md — as the structural foundation of every new project, providing a deterministic cold-start protocol for stateless AI agents. This guide defines the template’s architecture and presents a formal implementation protocol for human developers and AI agents alike.
:::tip
This is Part 6 of my contract-style-comments (CSC) series.
Part 5: Rethinking Design by Contract for the Age of Stateless AI Agents
:::
The CONTRACT‑Style‑Comments (CSC) methodology began as a way to prevent architectural drift — first for me, then for the AI agents I work with. Today, CSC has evolved into a portable governance scaffold that any developer or AI agent can use to start a new project with clear constraints, explicit invariants, and a shared understanding of the system’s rules.
This article explains how to use the official CSC GitHub Template to start new projects — whether you’re a human developer, an AI coding agent, or a hybrid team of both.
I. The CSC Template
The CSC Template is a GitHub repository configured as a template repo, meaning you can generate a clean, ready‑to‑use project with one click:
GitHub Template: https://github.com/ajaxstardust/contract-style-comments
This template encodes the Agentic Trivium — the three documents that define the rules, reasoning, and navigation of a project:
- CONTRACT.md — the present‑tense truth of the system
- WHY.md — the architectural reasoning and intent
- QUICKSTART.md — the navigation layer for humans and AI agents
Together, these documents form the governance layer that prevents drift, protects invariants, and gives stateless agents a stable interface.
II. The Agentic Trivium
CONTRACT.md — The Rules of the World
- invariants
- preconditions
- postconditions
- prohibitions
- boundaries the system must never violate
AI agents read this file at the start of every session. Humans read it whenever they return to the project after time away.
WHY.md — The Architectural Reasoning
- why the system exists
- why certain decisions were made
- what tradeoffs were accepted
- what the system must optimize for
It prevents hallucinated architecture and protects long‑term intent.
QUICKSTART.md — The Navigation Layer
- where things live
- how to run the project
- how to extend it safely
- how to follow the invariants
It is the operational map of the project.
III. Implementation: A Step‑By‑Step Protocol
Step 1 — Click “Use this template”
On the GitHub repo, click: Use this template → Create a new repository
This generates a clean project with no commit history, the Agentic Trivium in place, and a ready‑to‑use governance scaffold.
Step 2 — Define Your Project’s Invariants
Open CONTRACT.md and customize what must always be true, what must never be changed, and what the system guarantees.
INVARIANT: All user IDs must be UUIDv4.
INVARIANT: No function may write directly to the database without going through the Repository layer.
Step 3 — Add Project‑Specific Preconditions & Postconditions
These describe the safe operating boundaries of your system.
PRECONDITION: A session must exist before generating a recommendation.
POSTCONDITION: All generated files must be placed in /src/modules/.
Step 4 — Update WHY.md With Your Architectural Intent
Explain the “why” behind your decisions. Agents rely on this to avoid hallucinating new architectures.
Step 5 — Update QUICKSTART.md
Document how to run the project, how to extend it, where to put new files, naming conventions, and module boundaries. This is the first file AI agents read after CONTRACT.md.
Step 6 — Instruct Your AI Agent
When starting work, tell your agent:
“Before writing any code, read CONTRACT.md, WHY.md, and QUICKSTART.md. n Follow all invariants and prohibitions. Ask before modifying any invariant.”
This single instruction dramatically reduces drift.
IV. Agentic Alignment: Why Stateless Agents Excel With This Structure
AI agents are stateless. They forget everything between sessions. But they always re‑read the repository.
This means:
CONTRACT.mdbecomes the rules of the worldWHY.mdbecomes the architectural memoryQUICKSTART.mdbecomes the operational map
The CSC Template gives agents explicit constraints, explicit boundaries, explicit reasoning, and explicit file‑placement rules — eliminating the most common failure modes:
- architectural drift
- silent breakage
- misplaced files
- hallucinated abstractions
- reinvented modules
Structure given before the first line of code is written is the highest-leverage contract of all.
V. In Practice: A Worked Example
Here’s what the workflow looks like in practice:
- You say: “Clone this template and start a new project.”
- The agent clones the repo, reads CONTRACT.md, reads WHY.md, reads QUICKSTART.md, and builds an internal model of the constraints.
- The agent begins generating code within the boundaries you defined.
This is the missing interface between humans and AI coding agents.
VI. Scope: When to Apply CSC
Apply CSC when:
- the project has multiple files
- the architecture matters
- multiple agents will touch the code
- you need invariants to protect the system
- you want long‑term maintainability
- you want AI agents to behave consistently
Not necessary when:
- writing a one‑off script
- doing a quick experiment
- prototyping something disposable
CSC shines in real projects with real constraints.
VII. The Official Template Repository
GitHub Template: https://github.com/ajaxstardust/contract-style-comments
Use it as the starting point for new apps, services, agentic workflows, multi‑agent systems, and long‑running projects.
VIII. Conclusion
The CSC Template is more than a starter kit — it’s a governance layer for human‑AI collaboration. By making invariants explicit and architectural intent visible, you give both humans and agents the clarity they need to build safely, consistently, and predictably.
If you use the template in your own projects, I’d love to hear how it works for you — and what invariants you discover along the way.
This guide defines the sixth installment of the contract-style-comments series.