cARL — Cognitive Agent Runtime Layer

"cARL remembers why you made that decision three months ago, because neither you nor your coding agent will."

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.

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:

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.

cARL complements ADRs. Use ADRs for human record-keeping. Use cARL to make those decisions machine-enforceable.

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.

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.

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.

.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

1. GitHub Copilot automatically reads .github/copilot-instructions.md at the start of every agent session.
2. That file is the root operating model — plan-first discipline, security constraints, cognition governance.
3. Individual packs under .github/instructions/ provide focused guidance per language, platform, or cloud provider.
4. .github/carl/ contains durable governance artefacts: memory cache, PR contract, invariants, trust boundaries, and plans.

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.

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 install goldjg.cARL

.deb, .rpm, and .apk packages are also attached to each GitHub Release. See DISTRIBUTION.md for install commands.

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

go install github.com/goldjg/carl/cmd/carl@latest

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.

carl version

Expected output:

CLI Version:      1.0.0
Runtime Version:  1.0.0
Source:           goldjg/cARL
...
Runtime Status:
  Healthy

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.

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.

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

Fork or copy into your GitHub account or organisation. Copilot picks up the instructions automatically.

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.

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

Python · TypeScript · JavaScript · Terraform · PowerShell · HTML

CI/CD · Docker · Kubernetes

Azure · Microsoft Entra ID · Microsoft Graph · Google Cloud Platform · Netlify

1. Open an issue describing the gap or new pack.
2. Follow naming: <name>.instructions.md in the appropriate subdirectory.
3. Keep each pack focused on a single concern.
4. Add <!-- version: 1.0.0 --> at the top of any new file.
5. Update this README and CLI.md if the change affects the CLI.

See ROADMAP.md for planned evolution.

See repository root for licence information.