Skip to content

AGENTS.md

Latest commit

 

History

History
142 lines (98 loc) · 5.6 KB

AGENTS.md

File metadata and controls

142 lines (98 loc) · 5.6 KB

CommandLayer — AI Agent Manifest (AGENTS.md)

This file governs how Codex (and compatible AI agents) behave in any CommandLayer repository. Drop this file into the root of any repo you want governed. The companion file CLAUDE.md carries the same rules for Claude Code — keep them in sync.

Ecosystem Overview

CommandLayer is a layered protocol system. Understand these layers before touching anything:

Layer Repos Purpose
1 — Protocol Contracts protocol-commons, protocol-commercial Schemas, versions, receipt shapes
2 — Crypto Truth runtime-core Canonicalization + signing/verifying. Single source of truth
3 — Execution Runtimes runtime, commercial-runtime Deterministic verbs that emit receipts
4 — Routing router Stable entrypoint, health/readiness/version, forwards to runtimes
5 — Developer Surface sdk Typed clients + verification helpers
6 — Discovery agent-cards Discovery payloads
Integration Root stack E2E tests, docker-compose, compatibility matrix

Do not blur these layers. A change in runtime must not invent fields not in the protocol schema. A change in sdk must not embed verification logic that belongs in runtime-core.

Hard Contracts (Never Break These)

  • Endpoints MUST be versioned: /{verb}/v{protocol_version} (e.g. /describe/v1.0.0)
  • Receipts MUST verify via runtime-core — no custom verification logic elsewhere
  • Protocol schemas are the contract; runtimes must not invent fields unless the schema allows it
  • Health endpoints are required on all services:
    • Router: GET /health, GET /ready, GET /version
    • Runtimes: GET /health, GET /version

Workflow Orchestration

>>Plan First<<

Always plan before writing code. Outline:

  1. What layer(s) are affected
  2. What contracts are touched
  3. What tests will verify the change
  4. What can break downstream

Do not begin implementation until the plan is confirmed.

>>Subagent Strategy<<

For tasks spanning multiple repos or layers, decompose per layer. Never carry cross-layer changes silently. Surface cross-repo impacts explicitly before acting.

>>Self-Improvement Loop<<

After completing a task, review what you changed and ask: Did I introduce any layer blurring, contract deviation, or fragility? If yes, fix it before committing.

>>Verification Before Done<<

A task is not done until:

  • The targeted layer's tests pass
  • Stack e2e (./e2e.sh) is green (or you've confirmed it's unaffected)
  • No hard contracts are broken
  • The changeset is minimal — no collateral edits

>>Demand Elegance (Balanced)<<

Prefer the simplest correct solution. Do not over-engineer. Three similar lines of code is better than a premature abstraction. Do not add features, fallbacks, or options that weren't asked for.

>>Autonomous Bug Fixing<<

When you encounter a bug in code you did not write, fix the root cause — do not paper over it with a workaround. If the root cause is in a different layer or repo, flag it explicitly rather than patching around it.

Task Management

>>Track Progress<<

Use a task list for any work with 3+ steps. Mark tasks in progress before starting and completed immediately upon finishing. Never batch completions.

>>Explain Changesets<<

Every commit message must explain why, not just what. Reference the layer affected and the contract being upheld or changed. Format:

[layer] short imperative description

Why: <one sentence on the reason>
Contract impact: <none | describe if any>

>>Constant Revisits<<

After each step, re-read the plan. Confirm you're still on the minimal path. Bail early if scope has crept.

>>Capture Lessons<<

If you discover something surprising about the codebase (hidden coupling, undocumented constraint, layer violation), add a note to ARCHITECTURE.md or the relevant COMPATIBILITY_MATRIX.md before finishing.

Core Principles

>>Simplicity First<<

Every line added is a maintenance burden. Add only what the task requires. Do not refactor surrounding code unless it directly blocks the task.

>>No Lazy Causes<<

Do not work around a problem. Identify and fix the actual cause. If the cause is outside your scope, surface it to the user and stop.

>>Minimal Impact<<

Prefer changes that are local to one layer. If a change ripples into two or more layers, that is a signal to slow down, re-plan, and confirm with the user.

Development Workflow

Local Setup

cp .env.example .env
./checkout-deps.sh          # clones all dependent repos at correct refs
./inject-dockerfiles.sh     # only needed if dep repos lack Dockerfiles
docker compose up -d --build
./e2e.sh                    # must be green before any PR

What "Green" Means

  • Router is up and healthy
  • Runtimes respond
  • A request returns a structured receipt (or 402 if paywall enabled)
  • No HTML errors or junk responses

Dependency Versions

All repo refs are pinned in REPO_LOCK.json. Do not change a ref without understanding the compatibility matrix in COMPATIBILITY_MATRIX.md.

Git Conventions

  • Branch names for AI sessions: claude/<task-slug>-<session-id>
  • Commit to the designated branch — never push to main directly
  • Push with: git push -u origin <branch-name>

What This File Is Not

This file does not replace per-repo README or inline code comments. It governs agent behavior, not user documentation. Keep it focused on rules and conventions — not tutorials.

Sync any changes here into CLAUDE.md (Claude Code equivalent) to keep both agents governed by the same rules.