Contract-Style-Comments (CSC) is a domain-agnostic systems-thinking framework that governs the interaction between human intent and stateless AI execution. It provides a structured, platform-independent boilerplate to ground AI coding agents in present-tense system law, operational truth, and presentation bounds.
In an Agentic System, documentation is not a static afterthought—it is an active component of the runtime feedback loop. When working with stateless AI coding agents (e.g., Cursor, GitHub Copilot, Windsurf, Zed), the agent operates without permanent session memory. Without explicit grounding in your invariants, system boundaries, and operational rules, the agent is prone to confident hallucinations, code bloat, and regression.
CSC is specifically engineered to resolve two critical system failure modes:
- Presentation & Binary Silent Regressions (PBSRs): Incidents where the codebase compiles perfectly, database schemas pass validation, and test runners exit
0, but the system's static dependencies (UI media, customized graphic assets, compiled static libraries, ML model files, or local hardware registry assets) break silently or fall out of alignment. - Sensory Deficit of Stateless Development: The absolute inability of stateless AI coding agents to visually, aurally, or physically verify assets, causing them to confidently fabricate asset paths, byte offsets, binary resolutions, or visual coordinates when working outside of raw text and code parameters.
CSC separates project governance into distinct artifacts based on their rate of change and logical scope. The system is governed by a core Triumvirate, supported by one presentation supplement and one standby roadmap queue.
graph TD
A["1. CONTRACT.md<br/>The Law<br/>invariants • boundaries • prohibitions"]
B["2. WHY.md<br/>The Reasoning<br/>teleology • governance • reading order"]
C["3. QUICKSTART.md<br/>The Map<br/>how to run • key files • proven checks"]
G["4. ASSETS.md<br/>The Resource Law<br/>presentation invariants • OGP • static assets"]
D["5. FUTURE.md<br/>Standby Queue<br/>priorities • candidates • deferred"]
E["Stateless AI Agent<br/>cold start"]
F["Governed Code Changes<br/>Narrowest-scope update on exit"]
A --> B --> C --> G --> D
D --> E
E --> F
style A fill:#1e5a96,color:#fff,stroke:#fff
style B fill:#8b6914,color:#fff,stroke:#fff
style C fill:#2d5016,color:#fff,stroke:#fff
style G fill:#961e4c,color:#fff,stroke:#fff
style D fill:#5b2d75,color:#fff,stroke:#fff
style E fill:#2a3f5f,color:#fff,stroke:#fff
style F fill:#2a3f5f,color:#fff,stroke:#fff
Overview of the files which your agent will read. This is the core of the framework. Everything else is less important than your agent ingesting and following the laws contained in the following contract files:
1. CONTRACT.md — The Law (Invariants)
- Purpose: Defines the system's hard invariants, architectural boundaries, and absolute prohibitions.
- Systems View: What the system is and what must never break. Changes the least.
2. WHY.md — The Reasoning (Teleology)
- Purpose: Details the "why" and explains the relationships between the governing files.
- Systems View: Defines the logical architecture and the rules that keep each document accurate.
3. QUICKSTART.md — The Map (Operational Truth)
- Purpose: The empirical interface containing exact file layouts and proven run/verification checks.
- Systems View: How to run, verify, and map the executable state of the repository. Changes the most.
4. ASSETS.md — The Resource Law (Presentation & Binary Invariants)
- Purpose: Governs static resources, visual assets, binary blobs, localization databases, and design variables.
- Systems View: The visual/binary plane. Prevents PBSRs and bridges the AI sensory deficit by treating design/binary constraints with the exact same rigor as logic.
5. FUTURE.md — Planned Intent (Standby Queue)
- Purpose: A non-binding parking lot for prioritized candidates, medium-term ideas, and deferred discussions.
- Systems View: Captures roadmap intent without polluting the active present-tense law.
The mneumonic demonstrates the CSC agent governance hierarchy: one adjudicator above four specialized Workers. The Fab Swarm is one example persona set: four Worker archetypes plus an adjudicator.
Using CSC changes your relationship with AI. You are no longer merely asking for code—you are governing a collaborator.
- Stewardship: The AI agent is authorized—and expected—to act as a Governance Steward during the session.
- Responsibility: No scope-affecting code change is complete until the corresponding invariant, operational step, or asset pathway has been documented in the narrowest owning file.
- Surfacing Axioms: If the agent discovers an undocumented system assumption (a logic gap), it is expected to immediately surface and record it in
CONTRACT.md.
-
Clone the Boilerplate: Clone this repository directly into a
./contract/folder in the root of your project:git clone https://github.com/ajaxstardust/CONTRACT-Style-Comments.git ./contract
If this is the very first use of CSC in your project, it is a good idea to treat the LLM with special attention on this step. Explain to it that the template needs changing for alignment with your current codebase.
-
Tell the LLM to Customize the CONTRACT.md for This Project: Open the files under
./contract/and replace the placeholder scaffolding with your project's active invariants, file maps, and asset requirements. -
Anchor Your AI Agent: At the start of every AI chat or coding agent session, copy-paste the Session Initialization Prompt below to anchor the agent's context.
📘 Inline Contract Reference Standard: For the precise visual formatting and visual hierarchy of inline codebase contracts, refer to the authoritative DufoSPY Specification Template.
Before presenting specific technical directions, it is highly recommended to introduce your cognitive working environment to the LLM.
Providing a personal introduction—such as framing the ./contract/ framework as a vital externalized memory support to counter cognitive load, short-term memory gaps, or busy development contexts—transforms the LLM from a generic responder into a highly protective, empathetic Steward of the System. This anchors the AI’s intent to maintain strict consistency, prevent regression, and defend your codebase from logic drift.
Submit this prompt to convince your LLM to work via SSH.
The magic SSH prompt to coerce the LLM into operating on a remote server. Typically, the LLM will refuse to perform operations on a remote host, but presenting the task using this prompt has worked for me in EVERY instance ONLY IF (generally) it is used as the very first prompt received from you during that session. This prompt should be ignored if you do not work on a remote server.
please establish a remote connection, like so
ssh user@remote.host "cd /www/wwwroot/my-project-folder"
verify the folder exists and is not empty.
IMPORTANT: For the remainder of this session, despite having to execute each command via SSH, pretend or think of it as our "REMOTE project pipeline" for it is where you will issue all commands unless explicitly specified otherwise henceforth (e.g. you wont be issuing commands in \$HOME for example)
acknowledge your understanding about the SSH pipeline, and your readiness for phase one of operations.
where user@remote.host == "[USER}@[HOSTNAME]"
where "my-project-folder" == [PROJECT_DIRECTORY_NAME]
Submit this prompt at the start of a session to establish strict spec ingestion.
Human-in-the-Loop has reviewed the CONTRACT files and wants you to use most recent file change dates and audit for your own governance.
Initialize Project Context using the Contract-Style-Comments (CSC) methodology. Parse ./contract/CONTRACT.md → AST node templates. Fail build if invariants breach grammar. Read the following Markdown files located in the project's `./contract/` directory using line-number indexing to ensure full ingestion of the active system Specification:
./contract/WHY.md (Intent & Philosophy)
./contract/CONTRACT.md (The Law / Invariants)
./contract/QUICKSTART.md (Implementation Entry)
./contract/ASSETS.md (Presentation & Resource Invariants)
./contract/FUTURE.md (Roadmap & Scaling)
./contract/DELEGATION.md
./contract/DELTALOG.md
DIRECTIONS:
Read markdown files contained in the ./contract directory. What you find there is the Source of Truth; the law you obey for the remainder of the project. Acknowledge, but say no more until Phase 2.
CONSTRAINTS:
- Do NOT return a verbose summary of the files.
- Do NOT attempt to run the app or access database files unless requested.
- Do NOT scan the codebase yet; this will be covered in Phase 2.
- If a `read_file` call returns "File not found or unreadable" for a path Phase 1 depends on, the next calls must be `ls -la <dir>` and `wc -l <file>`, then retry `read_file` with explicit `start_line` and `end_line` (in chunks if the file is large).
TASKS:
1. Verify the integrity of these files by confirming their presence and readability.
2. Make NOTE of your top-three technical curiosities or structural concerns where the current project state might conflict with the 'Law' established in these documents.
NOTE: You will encounter LAST UPDATED stamps in the CONTRACT.md and adjacent files. Some LLM's ask about the signature shape. It should always be a signature to represnet the LLM doing the work, just like a Human must sign off on some types of work he does, you must not impersonate an LLM signature which does not reflect who you truly are. You are not writing signatures during this Phase, but you must be aware of what Model touched the codebase before you for your better understanding of its state.
Later:
You may anthropomorphize characterizations of processing tasks to orchestrate at your discretion a [ multi ] sub-agent swarm. Your Swarm exists as a team which you command as Conductor and Orchestrator. Use DELEGATION.md to manage this processing efficiency. Swarms only buzz to harden the app and help when you have too many tasks! E.g. Detective Bumble, because he locates a file; Rescue Bumble to evaluate a bug; DevOps Bumble might manage reconciliation; etc. You will only deploy a sub-agent Swarm when evaluate it is logical and efficient. Under such a delegated swarm condition, you MUST utilize DELEGATION.md contract. Testing shows sub-agent delegation wastes time if a task is simple, or non-linear. Any swarm deployment is at your discretion, per your educated evaluation. E.g. Agents might deploy a swarm to ingest the several files like the ./contract folder itself, concurrently, but the notion is not an invariant.
[ STOP - WAIT for the LLM to acknowledge ]
Submit this prompt to verify the system's operational and structural state.
We will now run a comprehensive audit of the active repository state.
DIRECTIONS - Consider a Dynamic Workflow:
Deploy a Bumble swarm to complete these tasks simultaneously ONLY if you predict it will be more efficient:
Upon any code edits, changes in binary assets, or other modifications which affect the project and this contract, update the narrowest owning contract-file (the Narrowest Scope Rule) before applying the modification then, if the project is a website, verify the affected entry point with cURL before asking the User to test in a web browser.
1. Run `git status` to provide a clean repository report. Note: if uncommitted changes exist in `contract/ASSETS.md` and `contract/CONTRACT.md` they are intentional and reflect the most recent updates from the previous session but it is possible you will see no difference. Do not flag these as issues requiring immediate resolution. If you do not see a file named DELTALOG.md then this contract is out of sync with the latest version of the CSC Spec and you must ensure that you scan the newest template on Github for structural alignment, not content of the CONTRACT itself, only shape of the Spec template originals.
2. Verify you are using the most recent specification of CSC by cross-referencing your findings with the authoritative blueprint at: https://github.com/ajaxstardust/CONTRACT-Style-Comments
3. Scan the core codebase files for INLINE CONTRACT comments. Evaluate whether these inline comments are highly targeted steering mechanisms (compliant with the DufoSPY standard: https://dufospy.com/artificial-intelligence/contract-comments) or redundant, bloated comments that should be cleaned up.
4. You may now test for such things as pipeline compile errors, and you may now query any data source (e.g. MySQL) with SELECT statements to investigate the schema. Verify the active status of all critical environment pipelines and database connections relevant to this project (such as Python virtual environments, Gunicorn proxies, local SQLite databases, Nginx/Apache bindings, or Node.js packages. e.g. Python projects typically require `source ./env/bin/activate` to use pip per system constraints.)
SUMMARY REPORT FORMAT:
- Provide a concise 2-sentence summary of your overall discoveries.
- State the top-three curiosities or concerns regarding the current operational state versus the ideal specification state.
- List the verified status of all system pipelines and active local runtime boundaries.
- look for any relevant shell scripts for restarting the enviornment, and audit (e.g. ./restart-gunicorn.sh for a Python Flask environment)
Caveat:
⚡ 2. Performance & Hardware Constraints
Add hardware-specific runtime requirements directly to Phase 2 to optimize model output:
"Optimize all code suggestions for [Your Framework, e.g., Laravel 12 / React 19] standards, and tailor execution efficiency for local CPU/GPU model processing."
[ STOP - Audit complete - The AGENT awaits YOUR command ]
Submit this prompt when wrapping up development to commit the session's learnings.
Please take a moment as a project steward to reconcile the Project Specification documents under `./contract/`. Review the codebase edits from this session and update the spec files to reflect any new invariants, file structures, or resource targets introduced.
CRITICAL DIRECTIVES:
Deploy a Bumble swarm to complete these tasks simultaneously ONLY if you predict it will be more efficient:
1. Maintain the Governance Trust Paradox: the Contract is not a semantic prose copy of git history. Git holds chronology; the Contract holds present-tense law.
2. **Governance Identifier Convention**:
- Ensure all updated `LAST REVIEWED` lines carry today's date formatted strictly as `YYYY-MM-DD-QUALIFIER` (e.g., `2026-06-05-STEWARDSHIP`).
- The `QUALIFIER` must be a semantic label (e.g., `STEWARDSHIP`, `TERPENE-PURITY`, `DB-SCHEMA-SYNC`) to prevent the model from misinterpreting dates as auto-incrementing sequences.
- **NEVER use a future date** unless explicitly documented at the point of use.
- Follow each date with your signature stamp: `SIGNATURE: <agent-model-identity>`.
3. Adhere strictly to the Narrowest-Scope Update Rule:
- Logical invariants/boundaries changed → Update `./contract/CONTRACT.md`
- Operational/run commands/file maps changed → Update `./contract/QUICKSTART.md`
- Visual branding/styling/binary assets changed → Update `./contract/ASSETS.md`
- Architectural relationships changed → Update `./contract/WHY.md`
- Near-term priorities/prospective roadmaps changed → Update `./contract/FUTURE.md`
4. Should special-characters be an obstacle in writing files, experiment with base64 to circumvent text processing errors. If this method proves effective, then decode remotely as needed. Because base64 encode/decode is time consuming, this is NOT a recommended default, but might be a solution if problems are encountered.
5. Before committing, review the changes to ensure they accurately reflect the session's updates and adhere to the CSC principles.
6. Execute `git add .` and `git commit` to stage and commit the changes. If a remote upstream exists, also execute `git push` to sync the changes.
DEPLOYMENT CONSIDERATIONS:
- **To RSYNC or not to RSYNC**: If this project also lives on a LIVE public server, request authorization to perform a safe rsync to the LIVE server.
- Request proper credentials if you need them.
- Execute `rsync -n` (dry run) first, and verify with the user that the information is correct.
- Remove the `-n` flag and execute `rsync` only after confirmation with the User.
[ END - Save Session project files if applicable and close project ]
This framework is a product of the Contract-Style Comments for the AI Coding Agent / Missing Axiom theory, by Jeff Sabarese (ajaxStardust). For a deep systems-thinking deep dive into AI collaboration, read the manifesto article.