
cARL — Cognitive Agent Runtime Layer
"cARL remembers why you made that decision three months ago, because neither you nor your coding agent will."
What is cARL?
cARL (Cognitive Agent Runtime Layer) is a version-controlled governance and instruction layer that sits inside your repository and shapes how AI coding agents behave — every session, every task, without re-prompting.
It is not a framework. It is not a library. It is a set of committed files that give your agent persistent memory, engineering discipline, and bounded execution contracts.
The Problem cARL Solves
AI coding agents are powerful but amnesiac. Every session starts from scratch. Each new task re-discovers the same architectural decisions, security constraints, and engineering conventions — or ignores them entirely.
The result is inconsistent behaviour, security regressions, dependency sprawl, and agents that confidently do the wrong thing because nobody told them otherwise — again.
cARL solves this by providing:
| Problem |
cARL solution |
| Agent forgets architecture decisions |
Durable truth cache in .github/carl/memory.md |
| Agent ignores engineering standards |
Modular instruction packs loaded every session |
| Agent drifts out of scope mid-task |
PR contracts constrain execution to approved scope |
| Agent uses wrong tools recklessly |
Tiered tool-permission governance |
| Agent over-reasons or under-reasons |
Cognition governance: minimum sufficient depth |
| Session is lost, work is lost |
Prompt-as-code plans in .github/carl/plans/ |
How cARL Differs from ADRs
Architecture Decision Records (ADRs) are documents written for humans. They record decisions after the fact and are read by developers during onboarding or code review.
cARL is agent-readable, partly structured governance written for agents. It is loaded before every task, not consulted after the fact. Where an ADR records why a decision was made, cARL enforces what the agent should and should not do as a result.
|
ADR |
cARL |
| Audience |
Human developers |
AI coding agents |
| When used |
After decision, during review |
Before every task |
| Format |
Prose narrative |
Structured instruction packs + YAML |
| Enforcement |
None (human discipline) |
Loaded into agent context every session |
| Scope |
Single decision |
Entire operating model |
cARL complements ADRs. Use ADRs for human record-keeping. Use cARL to make those decisions machine-enforceable.
How cARL Differs from Prompt Engineering
Prompt engineering is per-task. You write a prompt, get a result, and the instruction vanishes when the session ends.
cARL is persistent. Instructions live in committed files. They are version-controlled, diffable, auditable, and always in scope. They survive model upgrades, session resets, and team member turnover.
|
Prompt Engineering |
cARL |
| Persistence |
Per-session |
Version-controlled |
| Discoverability |
Lost when session ends |
Always in the repository |
| Consistency |
Re-typed or forgotten |
Loaded automatically every session |
| Auditability |
None |
Full git history |
| Team sharing |
Copy-paste |
Committed and shared via version control |
How cARL Differs from Agent Frameworks
Agent frameworks (LangChain, AutoGen, CrewAI, etc.) are code. They orchestrate agents programmatically, define tool schemas, and wire up models in code.
cARL is behavioural governance. It does not execute code. It shapes how an agent reasons, plans, and acts inside an existing tool (GitHub Copilot). No new runtime dependencies. No code to run.
|
Agent Frameworks |
cARL |
| Nature |
Code libraries |
Committed governance files |
| Deployment |
Runtime dependency |
Repository files |
| Target |
New agent applications |
Existing coding agents (Copilot) |
| Concern |
Orchestration and tooling |
Behavioural governance and discipline |
| Language coupling |
Yes |
Language-agnostic |
How cARL Evolved from AADLC
cARL is the productised form of AADLC (Autonomous Agent Development Lifecycle), an internal governance model developed through practitioner experience with GitHub Copilot coding agents.
AADLC established the core concepts:
- Phase separation (shaping → planning → execution → validation → reset)
- Durable memory caches
- PR contracts
- Tool permission tiers
- Prompt-as-code
cARL takes these concepts, renames them for clarity, organises them into a coherent product, and adds the documentation and positioning needed for broader adoption.
The runtime semantics are unchanged. This is a rename and productisation, not a redesign. The aadlc.instructions.md file is now carl.instructions.md. The .github/aadlc/ directory is now .github/carl/. All governance behaviour is preserved.
Repositories already running AADLC can migrate their accumulated durable knowledge (invariants, lessons, and governance rules) into canonical cARL artefacts with carl convert aadlc — see the Quick Start.
Repository Structure
.github/
├── copilot-instructions.md # Root operating model — loaded by Copilot automatically
├── carl/
│ ├── memory.md # Durable architectural truth cache
│ ├── current-pr-contract.md # Active PR contract (populate before each PR)
│ ├── current-pr-contract.template.md # Blank template — copy to current-pr-contract.md
│ ├── invariants.yml # Machine-readable governance invariants
│ ├── trust-boundaries.md # Trust boundary definitions and crossing rules
│ ├── tool-policy.yml # Tool permission tier policy (Tier 0/1/2)
│ ├── plans/
│ │ ├── README.md # Prompt-as-code guidance for substantial tasks
│ │ └── plan-template.md # Reusable cARL planning contract template
│ └── repo-map.example.json # Example cognitive repo map for fast orientation
└── instructions/
├── core/
│ ├── baseline.instructions.md
│ ├── security.instructions.md
│ ├── dependency.instructions.md
│ ├── identity.instructions.md
│ ├── carl.instructions.md # cARLv2 cognition governance phase model
│ ├── cognition-governance.instructions.md
│ ├── tool-permission-tiers.instructions.md
│ ├── memory-cache.instructions.md
│ └── pr-contract.instructions.md
├── languages/
│ ├── python.instructions.md
│ ├── typescript.instructions.md
│ ├── javascript.instructions.md
│ ├── terraform.instructions.md
│ ├── powershell.instructions.md
│ └── html.instructions.md
├── platform/
│ ├── cicd.instructions.md
│ ├── docker.instructions.md
│ └── kubernetes.instructions.md
└── cloud/
├── azure.instructions.md
├── entra.instructions.md
├── microsoft-graph.instructions.md
├── gcp.instructions.md
└── netlify.instructions.md
README.md
VISION.md
ARCHITECTURE.md
ROADMAP.md
GLOSSARY.md
CLI.md
How It Works
- GitHub Copilot automatically reads
.github/copilot-instructions.md at the start of every agent session.
- That file is the root operating model — plan-first discipline, security constraints, cognition governance.
- Individual packs under
.github/instructions/ provide focused guidance per language, platform, or cloud provider.
.github/carl/ contains durable governance artefacts: memory cache, PR contract, invariants, trust boundaries, and plans.
Quick Start (CLI)
The carl CLI installs and manages the cARL runtime in any repository.
It is a single self-contained binary — no dependencies, no network required after download.
1. Install the CLI
Download a release archive (Linux / macOS)
Download the latest archive for your platform from the
releases page.
Replace v1.0.0 and 1.0.0 in the commands below with the desired release tag:
# Linux (amd64)
curl -L https://github.com/goldjg/cARL/releases/download/v1.0.0/carl_1.0.0_linux_amd64.tar.gz \
| tar xz && sudo mv carl /usr/local/bin/carl
# macOS (Apple Silicon)
curl -L https://github.com/goldjg/cARL/releases/download/v1.0.0/carl_1.0.0_darwin_arm64.tar.gz \
| tar xz && sudo mv carl /usr/local/bin/carl
# macOS (Intel)
curl -L https://github.com/goldjg/cARL/releases/download/v1.0.0/carl_1.0.0_darwin_amd64.tar.gz \
| tar xz && sudo mv carl /usr/local/bin/carl
Windows users: download carl_1.0.0_windows_amd64.zip from the releases page,
extract carl.exe, and add it to your PATH.
WinGet (Windows)
winget install goldjg.cARL
Native Linux packages (deb / rpm / apk)
.deb, .rpm, and .apk packages are also attached to each GitHub Release.
See DISTRIBUTION.md for install commands.
Homebrew (macOS / Linux)
macOS release artefacts are configured to be Developer ID codesigned from v0.4.2
onward (hardened runtime). Full notarisation is not yet enabled; see
DISTRIBUTION.md for the current macOS signing status,
Gatekeeper implications, and the App Store Connect API-key path required for
notarisation.
brew tap goldjg/carl
brew trust goldjg/carl
brew install --cask carl
brew uninstall --cask carl
brew untrust goldjg/carl
brew untap goldjg/carl
Build from source (requires Go 1.24+)
go install github.com/goldjg/carl/cmd/carl@latest
2. Install the runtime into your repository
Navigate to the root of any repository and run:
cd /path/to/your-repo
carl init
This writes all governance artefacts into .github/ and creates
.github/carl/runtime.json as the authoritative runtime manifest.
3. Verify the installation
carl version
Expected output:
cARL CLI:
Version: 1.2.0
Bundled Runtime:
Version: 1.1.0
Source: goldjg/cARL
Tag: v1.2.0
Commit: 98f680b3...
Repository Runtime:
Version: 1.0.0
Source: goldjg/cARL
Tag: v1.0.0
Commit: 742ac661...
Status: Upgrade available
Version semantics:
- CLI version identifies the executable and command implementation.
- Bundled runtime version identifies the canonical governance payload embedded in the executable.
- Repository runtime version identifies the runtime currently installed in the repository (
.github/carl/runtime.json).
To inspect bundled vs installed pack/shim component versions directly:
carl version --components
4. Restore drift
If any managed artefacts are modified and you want to restore them to their
canonical state:
carl repair
memory.md and runtime.json are protected and are never overwritten by repair.
5. Diagnose issues
Run a health check with actionable guidance for any issues found:
carl doctor
Expected output when healthy:
INFO runtime is healthy — all managed artefacts are present and canonical
See CLI.md for the full command reference.
6. Explore available packs
List every discoverable instruction pack (bundled in the binary, present in
the repository, or selected in runtime.json), or inspect one pack's
versioned metadata:
carl pack list
carl pack show core/security
Both subcommands support --json for machine-readable output and work outside
an initialised repository (bundled packs only). Ordering is deterministic
(sorted by pack ID), never filesystem order.
7. Migrate from AADLC (existing repositories)
If your repository already contains governance knowledge under legacy AADLC
artefacts (.aadlc/, .github/aadlc/, AADLC.md, ...), migrate that durable
knowledge into canonical cARL artefacts so adoption does not lose accumulated
context:
carl convert aadlc --dry-run # analyse and report; makes no changes
carl convert aadlc --apply # perform the migration
carl convert discovers AADLC artefacts, classifies their content into
invariants, durable memory, and governance rules, and migrates them into
.github/carl/invariants.yml and .github/carl/memory.md. It never deletes or
modifies AADLC artefacts, never overwrites existing cARL knowledge (duplicates
are skipped and conflicts are reported for human review), and is idempotent.
The typical end-to-end adoption workflow is:
carl init
carl map
carl reconcile
carl convert aadlc
carl harness sync
Usage
Using this repository directly
Fork or copy into your GitHub account or organisation. Copilot picks up the instructions automatically.
Copying packs into another repository
Copy any individual pack from .github/instructions/ into the same path in your target repository. For full cARLv2 usage, also copy .github/carl/ and populate the artefacts for your project.
Versioning
Each file carries a <!-- version: X.Y.Z --> comment. Increment using Semantic Versioning:
- MAJOR — breaking change to conventions
- MINOR — new guidance added compatibly
- PATCH — clarifications or corrections
Pack Summary
Core Packs
| Pack |
Purpose |
baseline |
Engineering operating model, plan-first, test discipline |
security |
No secrets, input validation, SSRF prevention |
dependency |
CVE management, native-first, justification required |
identity |
Token validation, trust boundary discipline |
carl |
cARLv2 phase model and cognition governance |
cognition-governance |
Minimum sufficient reasoning depth |
tool-permission-tiers |
Tier 0/1/2 tool classification and escalation |
memory-cache |
Durable truth cache governance |
pr-contract |
Scoped implementation contract lifecycle |
Language Packs
Python · TypeScript · JavaScript · Terraform · PowerShell · HTML
CI/CD · Docker · Kubernetes
Cloud Packs
Azure · Microsoft Entra ID · Microsoft Graph · Google Cloud Platform · Netlify
Contributing
- Open an issue describing the gap or new pack.
- Follow naming:
<name>.instructions.md in the appropriate subdirectory.
- Keep each pack focused on a single concern.
- Add
<!-- version: 1.0.0 --> at the top of any new file.
- Update this README and CLI.md if the change affects the CLI.
Roadmap
See ROADMAP.md for planned evolution.
License
See repository root for licence information.