LOGIC.md: The Audit and Governance Layer for AI Agent Reasoning

The problem

Your agent reasoning is locked inside prose prompts.

That has three consequences.

01, UNAUDITABLE

You cannot audit it

When a regulator, security team, or user asks "why did the agent take that action?", the answer is buried in the model's hidden reasoning trace. Replaying the exact same input rarely produces the exact same output. The audit trail is whatever logs you remembered to add.

02, UNSAFE TO EDIT

You cannot modify it safely

Updating a multi-step workflow means editing prose. There are no contracts, no types, no validate(). A six-word change can quietly break four downstream consumers. The diff doesn't tell you what changed semantically.

03, INCONSISTENT

You cannot trust the consistency

Two runs of the same workflow on the same input produce different structured outputs at non-trivial rates. On reasoning tasks where the model has multiple plausible paths, prose prompts under-constrain the output enough that variance becomes a real problem downstream.

This isn't a prompt-engineering problem you fix with better prompts. It's a missing-contracts problem. Every agent framework gives you identity (CLAUDE.md), tools (SKILL.md), and memory. None of them give you a portable format for reasoning contracts that validate at compile time and produce structured audit trails. LOGIC.md fills that gap.

What it is

The reasoning layer sitting between identity and capability.

A markdown file with YAML frontmatter declaring step DAGs, output contracts, and quality gates. When a node has output contracts, the runtime compiles a structured prompt segment listing every required field, with type and description, and emits the compiled prompt plus schema as part of the workflow event trace.

spec_version: "1.0"
name: security-auditor
reasoning:
  strategy: plan-execute
steps:
  - name: audit
    instructions: "Produce the actual audit report"
    contracts:
      outputs:
        findings: array
        severity: string
    quality_gates:
      post_output:
        - check: "outputs.findings.length > 0"
          action: retry

The contract is enforceable, diffable, and auditable. The compiled prompt is deterministic given the spec: same spec, same plan, every time.

What it controls

Seven control surfaces, from reasoning strategy down to fallback policy.

Reasoning strategy

per-agent

Declare cot, react, tot, plan-execute, or got per agent. Not hardcoded in imperative Python. Portable across runtimes.

Step DAGs

structure

Named reasoning stages with needs dependencies, parallel execution groups, typed inputs and outputs, confidence thresholds, retry policies, and per-step timeouts.

Contracts

A2A pattern

Typed inputs and outputs following the A2A protocol pattern. When one agent's output becomes another agent's input, LOGIC.md defines exactly what that handoff looks like and enforces it.

Animated pipeline showing three reasoning steps linked by typed output contracts, with a quality gate firing a retry loop and a fallback escalation path.

Quality gates

pre / post / continuous

pre_output and post_output checks, continuous invariants, and self_verification loops using reflection, rubric, checklist, or critic strategies.

Quality gate loop: a step evaluates its own output and branches to pass, retry, or escalate, declarative adaptive computation.

Per-step tool control

allowed / denied

allowed_tools and denied_tools per step. A research step allows web_search but denies file_write. An output step allows file_write but denies web_search. Agents cannot exceed what the step permits.

Multi-agent DAGs

global / nodes / edges

Per-edge contracts and join modes (wait_all, first, any). Parallel agents converge cleanly with defined merge behaviour.

Fallback and escalation

graceful degradation

Escalation chains and graceful degradation rules when steps fail, confidence thresholds are not met, or retries are exhausted.

Before and after

Agents that describe intent, versus agents that emit structured artifacts.

Case study

Structural consistency under LOGIC.md, measured against Archon.

Validated in May 2026 against Archon, an open-source AI workflow engine, in a 60-trial controlled experiment. Identical PR-review task, two configurations on the same Archon node: stock prose prompt with a Zod schema (Case A) versus the same node with reasoning delegated to LOGIC.md's MCP server (Case B). Same model, same fixtures, same harness, zero patches to Archon.

	Case A (prose)	Case B (LOGIC.md)
Verdict agreement (auth-sql-injection)	5/10 different tuples	10/10 identical
Structural hash agreement (overall)	70%	87%
Audit trail	Manual reconstruction	Workflow event JSONL out of the box
Modifiability (add a new rule)	8-line prose edit, no validation	9-line structured rule + validate()
Runtime overhead	1×	2.6×

On the auth-sql-injection fixture, Case A produced 5 different (verdict, critical_count, high_count) tuples across 10 identical runs, essentially a coin flip on the supporting metadata. Case B produced 1 unique tuple, 10/10 identical. LOGIC.md doesn't change the verdict (both cases reach REQUEST_CHANGES); it eliminates the structural variance in the metadata downstream consumers depend on.

The honest cost The 2.6× runtime cost is real. LOGIC.md is not free. The trade is consistency, auditability, and safe modifiability against execution speed. For regulated domains, multi-agent pipelines, or workflows where agent decisions need to be defensible, the trade is worth making. For one-shot prototypes or fast classification gates, it is not.

Full report with methodology, traces, and per-fixture analysis →

When to use it, and when not to

Structural value, not generative value.

✓ Use LOGIC.md when

You need agent decisions to be auditable, regulated domains, security teams, internal compliance.
You have multi-step pipelines where one agent's output feeds another and the contract needs to be enforceable.
You need consistent verdicts across runs, not a different paraphrase each time.
Your workflow needs to be safely modifiable by people who didn't author it.
You need per-step tool permissions, confidence thresholds, or governed fallback policies.
You want reasoning configuration portable across LangGraph, CrewAI, AutoGen, or your own runtime.

You probably don't need it when

Your agent is a single LLM call with no downstream consumers.
You're prototyping and don't yet know the shape of your reasoning steps.
Your workflow is fully covered by a DSPy signature or a single LangGraph node.
You're optimising for raw output quality on a frontier model, LOGIC.md adds structure, not quality.
You have no quality gates, no contracts between stages, no multi-agent handoffs.

Honest disclosure on quality lift Cross-model benchmarks (Claude Sonnet 4.6 and Llama 3.1 70B at n=10 per condition) show no measurable quality lift from LOGIC.md on these tasks. The value is structural, consistency, auditability, modifiability, not generative. Pitch and adopt accordingly. LOGIC.md is a reasoning contract format: if you don't have anything to contract between, you don't need it yet.

How it compares

Adjacent tools solve adjacent problems. Here's the actual boundary.

vs. DSPy

DSPy is Python-bound, optimizer-driven, tightly coupled to its own runtime. Signatures are Python classes; the killer feature is automatic prompt optimization.

LOGIC.md is a portable file format, contracts-first, runtime-agnostic. No optimizer, it declares the contract, doesn't tune the prompt. Not mutually exclusive: a DSPy module could ship with a LOGIC.md file describing its contracts.

vs. BAML

The closest project in spirit: file-based, declarative, contracts-first. BAML defines individual LLM function signatures with cross-language codegen.

LOGIC.md defines reasoning architecture: step DAGs, multi-agent contracts, quality gates. A BAML function could be the implementation behind a LOGIC.md step, they compose naturally.

vs. Instructor / Outlines

Handle structured output validation at the generation layer, ensuring individual calls match a Pydantic model or constrained grammar.

LOGIC.md operates one level up: step ordering, dependencies, quality gates across a pipeline. Use Instructor or Outlines within a LOGIC.md step; LOGIC.md orchestrates how steps relate.

What exists today vs. LOGIC.md

	Handles	Portable
CLAUDE.md / AGENTS.md	Identity, project context, code style	Markdown
OpenClaw SOUL.md	Personality, behavioural rules	Markdown
Cursor .mdc rules	Coding conventions with activation modes	Markdown
MCP	Agent ↔ tool connectivity	Protocol
A2A Protocol	Agent ↔ agent communication	Protocol
BAML	Typed output schemas, cross-language codegen	Custom DSL
LangGraph	Reasoning as imperative StateGraph code	Python
DSPy	Composable signatures + prompt optimization	Python
LOGIC.md	Step DAGs, contracts, quality gates, multi-agent	Markdown / YAML

Theoretical grounding

Pipeline-level adaptive computation.

A declarative way to allocate extra reasoning effort, retry, self-verification, fallback, where it's needed, without modifying the underlying model. This connects to three active research threads.

Adaptive computation and learned halting

Universal Transformers and PonderNet show iterative, variable-depth computation improves reasoning reliability over fixed-depth forward passes. LOGIC.md's quality gates and retry policies implement the same primitive, "compute more when the output isn't good enough", at the orchestration layer, where any model can benefit without retraining.

Reasoning reliability beyond the base model

If RL post-training sharpens capabilities already present rather than adding new reasoning capacity (Yue et al. 2025), reliability gains at the application layer must come from structured inference-time scaffolding: contracts, verification, orchestrated retry. LOGIC.md is a portable format for exactly that.

Scaling limits and the case for inference-time structure

As pretraining returns diminish and human-generated training data approaches its limit, reliability increasingly depends on how inference is orchestrated. A portable, declarative format for multi-step reasoning contracts becomes more valuable, not less, in that regime.

Format, packages, status

Twelve sections. Three packages. 29 conformance fixtures.

imports reasoning steps contracts quality_gates decision_trees fallback global nodes edges visual spec_version (required) name (required)

Canonical JSON Schema at spec/schema.json, 29 conformance test fixtures, three conformance tiers (Parser, Runtime, Full Adapter). Developed alongside and validated in production through Modular9, a visual node-based agent builder by the same author.

3packages, core, cli, mcp

9CLI commands, 16 templates

7MCP tools exposed

520tests, 91.6% branch coverage

A feel for the CLI

# Validate a LOGIC.md file
logic-md validate my-agent.logic.md

# Lint for best practices, unused steps, missing fallbacks
logic-md lint my-agent.logic.md

# Scaffold from one of 16 templates
logic-md init --template researcher

# Compile a single step to see its runtime prompt segment
logic-md compile my-agent.logic.md --step gather_sources

# Semantic diff between two specs
logic-md diff v1.logic.md v2.logic.md

# Watch mode for development
logic-md watch my-agent.logic.md

Claude Code plugin ships five slash commands (/logic:status, /logic:apply, /logic:validate, /logic:init, /logic:compile) and four reasoning workflow templates: code-review, debug-workflow, refactor, architecture.

Full demo

Watch the LOGIC.md demo

Watch now →

Get the contract

Declare the reasoning contract once. Audit every run by default.

Published on npm and PyPI. MIT licensed. Sibling of COVENANT.md and MARCHESE.md.

View on GitHub → npm install -g @logic-md/cli

Evidence stamp

Evidence: compiled from the logic-md repository on 2026-08-03. Every number on this page traces to a file path or command output in the source tree. Last updated: 2026-08-03.

The audit and governance layer for AI agent reasoning.