Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (98 loc) · 5.85 KB

AGENTS.md

File metadata and controls

146 lines (98 loc) · 5.85 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
  • In this repository, the implemented runtime health surface is GET /health plus the alias GET /healthz. Do not document repo-local routes that are not actually present here.

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
  • Repo-local checks are green, or you have explicitly confirmed why a broader stack check is unavailable or 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), document it in an actually present repo doc instead of referencing files that are not checked in here.

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

For this repository, use the files that are actually checked in:

npm ci
cp .env.example .env
npm test

Optional local helpers that exist in this repo:

scripts/dev.sh
node scripts/smoke.mjs

What "Green" Means

For changes scoped to this runtime repo, "green" means the repo-local checks you touched are passing, especially npm test and any directly relevant smoke or workflow-covered checks.

If a task depends on cross-repo or stack behavior, say so explicitly rather than sending users or agents to scripts that are not present in this repository.

Dependency Versions

This repo currently pins npm dependencies through package-lock.json. Do not assume stack-level lockfiles or compatibility files exist here unless they are actually present.

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.