"Intelligence isn't controlled by making it weaker. It's controlled by giving it boundaries."
Most developers interact with LLMs by "casting spells"—tweaking words, adding "please," and hoping for a good result. It is fragile, non-deterministic, and impossible to scale.
Prompt Contracts treat LLM interactions as System Architecture. We do not ask the model to "be smart." We define a Contract that governs:
- Who it is (Role).
- What it knows (Scope).
- How it thinks (Reasoning).
- What it delivers (Objective).
- How it speaks (Language).
This repository is a collection of governance protocols and contract templates to turn stochastic models into reliable software components.
The Philosophy. Understand why models hallucinate and how "Intelligence Containment Theory" fixes it.
1_What_is_Prompt_Contract.md- The shift from "Prompt Engineering" to "Cognitive Architecture."2_Why_Models_Hallucinate.md- The "Infinite Space" theory.3_Intelligence_Containment_Theory.md- The physics of containment.
The Syntax. The 5 immutable layers of a valid prompt contract.
Scope_Contract.md- Safety: Defining the "Context Window" and "Negative Constraints."Role_Contract.md- Identity: Defining the expertise and authority.Objective_Contract.md- Goal: Defining the "Definition of Done."Reasoning_Contract.md- Logic: Defining the step-by-step thought process.Language_Contract.md- Interface: Defining the output schema (JSON/XML).
The Workflow. How to orchestrate the AI across the Software Development Life Cycle (SDLC).
Spec_Driven_Development.md- Architecture: Write the Spec before the Code.Task_Decomposition.md- Planning: Break big features into atomic prompts.Test_Driven_Protocol.md- Verification: The "Red-Green-Refactor" loop.Review_Before_Act.md- Safety: Force the model to audit itself.Context_Reset_Protocol.md- Maintenance: When and how to kill the context.
The Team. How to assign the right Cognitive Profile to the right task.
Role_Assignment_Framework.md- The "Planner" (High-IQ), "Engineer" (High-Context), and "Processor" (High-Speed) archetypes.Model_Selection_Matrix.md- A guide to choosing models based on reasoning density.
The Tools. Copy-pasteable templates for daily engineering tasks.
Spec_Generation.md- Create a rigorous RFC from a vague idea.Feature_Development.md- The Master Template for writing code.Debugging.md- A forensic protocol for Root Cause Analysis (RCA).PR_Review.md- A strict security and logic auditor.Task_Decomposition.md- A prompt to break large specs into small tasks.
- Select a Template: Go to
/5_Examplesand pick the contract that matches your task (e.g.,Feature_Development.md). - Fill the Brackets: Replace the
[ ]placeholders with your specific context (file paths, requirements). - Select the Model: Refer to
/4_Model_Mappingto choose the right Archetype (e.g., use The Planner for Specs, The Engineer for Code). - Execute: Paste the contract into the chat.
- Audit: Use the
Review_Before_Actprotocol to verify the output.
"The model did not fail. The space was infinite."
If you get a bad result, do not blame the model. blame the contract.
- Did you define the Scope? (Or did it hallucinate files?)
- Did you define the Role? (Or did it act like a junior dev?)
- Did you define the Reasoning? (Or did it guess the answer?)
Always place your Role and Language contracts at the very top of your prompt. This ensures they are prioritized by the model's attention mechanism and allows for Prompt Caching, significantly reducing your per-task cost.
Suhail T
This framework was born from a simple realization: as AI models grow in complexity, our methods for governing them must evolve from "casting spells" to "engineering systems." My goal is to provide a standardized map for the infinite space of LLM reasoning.
Connect with me on LinkedIn to follow the evolution of Context Engineering.
This framework is MIT License. Use it, fork it, and build reliable systems.