Agent-First Canonical Code

• Agent-First Canonical Code is a paradigm that assigns canonical authority to high-level, machine-actionable representations rather than solely relying on hand-maintained code.
• It externalizes control flow, domain norms, and verification obligations into durable artifacts such as natural-language specifications and executable blueprints.
• This approach enables reproducible, auditable agent behavior by embedding structured executable logic in artifacts like prompt-encoded doctrines and workflow graphs.

Searching arXiv for the cited papers to ground the article in current records. Agent-First Canonical Code is a software and agent-design paradigm in which the durable, authoritative artifact is no longer assumed to be a hand-maintained implementation alone. Instead, canonicality is assigned to one or more higher-level, machine-actionable representations—such as an auditable natural-language specification, an executable workflow blueprint, a canonical prompt-encoded modeling playbook, a codified context constitution, a typed tool contract, or a governed proof-carrying change object—from which executable behavior is generated, constrained, verified, or regenerated. Across recent work, the shared thesis is that control flow, domain norms, verification obligations, and interface semantics should be externalized into stable artifacts that agents can execute against, rather than left implicit in long conversations or in unconstrained model sampling (Monperrus, 18 Mar 2026).

1. Definition and conceptual scope

The phrase “Agent-First Canonical Code” denotes a family of positions rather than a single standardized formalism. In one line of work, the canonical artifact is a compact natural-language specification from which an agent can be implemented and re-implemented; the core thesis is stated explicitly as “the specification is the program” (Monperrus, 18 Mar 2026). In another, canonicality is assigned to executable workflow code: a domain expert writes or curates an “Execution Blueprint,” and the LLM is invoked only for bounded subtasks while “never to decide the workflow’s path” (Qiu et al., 1 Aug 2025). In a third, canonicality resides in prompt-encoded doctrine plus stateful execution: a generic coding agent is given a rich project prompt and a persistent kernel, then iteratively constructs, tests, debugs, and verifies a final executable artifact (Szeider, 10 Aug 2025).

A common denominator is the relocation of semantic authority away from transient chat trajectories. In the bootstrap formulation, the enduring object is the specification; implementations are “ephemeral, disposable, and reproducible” so long as they satisfy the same behavioral contract, denoted by $\models s$ (Monperrus, 18 Mar 2026). In deterministic workflow systems, the enduring object is source-code procedure. In prompt-centered agent systems, the enduring object may be a project prompt, a workflow graph, or a codified context layer that carries conventions, failure modes, and retrieval hooks across sessions (Vasilopoulos, 24 Feb 2026). This suggests that “canonical code” is best understood as a governed representation layer that agents can reliably execute, regenerate, or audit, rather than as a claim that a single source file or intermediate language has become universally canonical.

The paradigm is also defined negatively, by contrast with architectures in which the LLM remains the orchestrator. “LLM-as-Code Agentic Programming” argues that “looping, branching, sequencing, variable binding, error handling” are deterministic work that should stay in the program, while the LLM should be invoked only where reasoning or generation is needed (Qi et al., 14 Jun 2026). “Blueprint First, Model Second” makes the same separation in operational environments, attributing non-determinism to systems that conflate “probabilistic, high-level planning” with “low-level action execution” (Qiu et al., 1 Aug 2025). These formulations place canonicality in the control substrate: the program, blueprint, or typed protocol defines admissible trajectories, while the model fills bounded semantic gaps.

2. Historical and methodological antecedents

One explicit genealogy comes from compiler bootstrapping and meta-circularity. “Bootstrapping Coding Agents: The Specification Is the Program” formalizes a two-step self-reproduction sequence:

$$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$

where $s$ is a 926-word specification, $\mathrm{agent}_0$ is generated by Claude Code with Sonnet 4.6, and $\mathrm{agent}_1$ is generated by $\mathrm{agent}_0$ from the same specification (Monperrus, 18 Mar 2026). Correctness is not byte identity but specification satisfaction, and both implementations are treated as valid because both satisfy $s$. The paper directly analogizes this to self-hosting compilers and meta-circular Lisp.

A second lineage comes from code-first agent frameworks. TaskWeaver described itself as “a code-first framework for building LLM-powered autonomous agents,” with a Planner, Code Generator, and Code Executor operating inside a stateful per-session Python/Jupyter process (Qiao et al., 2023). There, generated Python is the dominant execution artifact, while plans, posts, plugin schemas, and session memory function as upstream control representations. This established a practical precedent for treating code as the principal action language in agent systems, particularly for rich data structures and domain-specific analytics (Qiao et al., 2023).

A third antecedent is canonical representation in optimization and distributed systems, where “canonical form” denotes a minimal, unique parameterization of a class of behaviors. The distributed optimization paper defines a five-parameter canonical form for first-order distributed algorithms with one communication and one gradient evaluation per iteration, proving uniqueness and minimality under the stated assumptions (Sundararajan et al., 2018). Although that work is not about LLM agents, it contributes a relevant methodological idea: canonicality can mean a representation that is both sufficiently expressive and minimally redundant. A plausible implication is that recent agent-first work imports this intuition into software and workflow design, seeking representations that preserve behavior while removing accidental variation.

Recent papers extend the historical arc from code-first execution to code-governed orchestration. “Blueprint First, Model Second” treats the workflow logic as source code and reports a new state-of-the-art on $\tau$-bench, surpassing the strongest baseline by 10.1 percentage points on average Pass$^1$ while reducing conversational turns and tool calls in case studies (Qiu et al., 1 Aug 2025). “LLM-as-Code” generalizes the thesis: the program owns the control flow, and the model is a typed callable embedded inside it (Qi et al., 14 Jun 2026). Together, these works shift the conceptual center of gravity from “agent as prompt-driven policy” to “agent as executable, inspectable, code-governed process.”

3. Canonical artifacts and architectural patterns

Recent work proposes several distinct canonical artifacts.

First, the specification-first variant treats a compact behavioral specification as the stable artifact of record. The specification defines “the agent’s interface,” “its behavioral constraints,” and “the tool loop,” and is short enough that “it can be read and audited by a single engineer in under five minutes” (Monperrus, 18 Mar 2026). The implementation becomes a regenerable manifestation. This model favors version control around specifications, audit around behavioral completeness, and reproducibility via pinned models, logged trajectories, and controlled generation environments (Monperrus, 18 Mar 2026).

Second, the blueprint-first variant treats executable source code as canonical workflow logic. In the Source Code Agent framework, an expert-defined operational procedure is codified into an Execution Blueprint realized as source code, then run by a deterministic engine; the LLM is strategically invoked only for bounded subtasks such as intent understanding or analysis (Qiu et al., 1 Aug 2025). Control structures—step order, branching, retries, policy gates, and validation checks—are owned by code. The paper’s architectural layers include User-Defined Configuration, a Componentized Agent SDK, a Control Layer, a Source Code Executor, and a Sandbox Runtime Environment (Qiu et al., 1 Aug 2025).

Third, prompt-governed coding agents assign canonicality to domain doctrine encoded in prompts plus stateful tools. CP-Agent exemplifies this strongly. The generic agent is only a few hundred lines of code, but it is given a roughly 700-line project prompt cpmpy.md containing CP-specific requirements, modeling patterns, debugging advice, “The Playbook,” and a required four-step workflow (Szeider, 10 Aug 2025). The agent combines that prompt with file operations and python_exec(code: str) over a persistent IPython kernel, usually building and testing solutions in memory before writing the final script. The result is a clean final CPMpy model, but the canonicality is rooted in the prompt-encoded doctrine and independent verification discipline (Szeider, 10 Aug 2025).

Fourth, code-first workflow systems propose graph-plus-code as a de facto canonical representation. Skele-Code uses a workflow JSON graph, one node folder per graph node, one main Python script per node, a required node interface with preprocess(), compute(), and save(), and a mandatory pickle-based output contract (Gopalakrishnan, 18 Mar 2026). Agents are “invoked only for code generation and error recovery, not orchestration or task execution,” so runtime behavior is deterministic and graph-driven (Gopalakrishnan, 18 Mar 2026). This makes the generated workflow code and graph definition the durable artifact.

Fifth, enterprise tool semantics can themselves be canonicalized. The Agent-First Tool API paper defines a Six-Verb Semantic Protocol—search, resolve, preview, execute, verify, and recover—and a Normalized Tool Contract (NTC) carrying confidence, evidence, result_refs, next_actions, and requires_confirmation (Pan, 11 May 2026). The protocol is formalized as a finite-state machine with states such as $q_{\mathrm{init}}$, $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$0, $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$1, and $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$2, and with recovery as an explicit transition out of failure (Pan, 11 May 2026). Here canonicality is located in the semantic application layer above transport.

Sixth, large-project agent engineering treats project memory as canonical infrastructure. “Codified Context” describes a three-tier system: a hot-memory constitution, 19 specialized domain-expert agents, and a cold-memory knowledge base of 34 specification documents, developed during construction of a 108,000-line C# distributed system (Vasilopoulos, 24 Feb 2026). The constitution encodes conventions, build commands, routing triggers, architectural summaries, and known failure modes. This system turns project intent into durable machine-consumable context rather than repeated human explanation (Vasilopoulos, 24 Feb 2026).

4. Representative systems and empirical demonstrations

Several systems instantiate the paradigm in distinct domains.

CP-Agent addresses natural-language-to-constraint-model translation. It uses a pure ReAct loop, a persistent IPython kernel, a deliberately small tool suite, and domain expertise injected solely through the project prompt (Szeider, 10 Aug 2025). On CP-Bench, a 101-problem benchmark of natural-language-to-constraint-model tasks, it achieved 100% accuracy—“solving every problem correctly”—after minor clarifications to output schemas and two problem statements (Szeider, 10 Aug 2025). The agent used python_exec between 4 and 23 times per problem, and todo_write in 59 of 101 problems, indicating that success depended on iterative executable refinement rather than one-shot generation (Szeider, 10 Aug 2025). A standard inferred formalization of the target model is:

$$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$3

with decision variables $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$4, domains $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$5, constraints $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$6, and optional objective $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$7 (Szeider, 10 Aug 2025).

“Bootstrapping Coding Agents” demonstrates self-reproduction from a compact specification. Starting from a 926-word specification and the prompt “implement the spec in a single python file,” Claude Code generated a working agent.py; that generated agent was then given the same specification and succeeded in generating another agent.py satisfying the same specification (Monperrus, 18 Mar 2026). The practical implication is stated directly: “the specification, not the implementation, is the stable artifact of record” (Monperrus, 18 Mar 2026).

“Blueprint First, Model Second” demonstrates deterministic workflow execution in structured operational domains. On $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$8-bench, the Source Code Agent with Claude-3.5-Sonnet achieved 77.0 on $$\begin{align} \mathrm{agent}_0 &= F(s,\ \text{Claude Code}) \ \mathrm{agent}_1 &= F(s,\ \mathrm{agent}_0) \end{align}$$9-retail, 56.0 on $s$0-airline, and 67.7 on the domain-weighted average, compared with 57.6 for the strongest Function Call baseline (Qiu et al., 1 Aug 2025). In case studies, one retail task reduced tool calls from 11 to 2 and assistant turns from 20 to 6, while an airline task reduced tool calls from 9 to 7 (Qiu et al., 1 Aug 2025). The paper attributes the gains to explicit workflow logic, codified policy checks, and the Double-Check node.

“LLM-as-Code” reports a case study of computer-use agents on OSWorld. Under the proposed architecture, the full execution history becomes a call DAG rather than a flat transcript, and each call sees the full ancestor chain but only summaries of returned children (Qi et al., 14 Jun 2026). The paper states that context length is bounded by current call depth:

$s$1

rather than by total number of steps:

$s$2

(Qi et al., 14 Jun 2026). In the reported results, the method achieved 86.8 overall with 15 max steps, surpassing listed baselines such as 80.4 and 78.3 that used 100 steps (Qi et al., 14 Jun 2026).

DeepCode addresses paper-to-repository synthesis at full repository scale. It formulates document-to-codebase generation as learning a mapping

$s$3

where a repository is

$s$4

with directory structure $s$5, source files $s$6, and dependency/environment metadata $s$7 (Li et al., 8 Dec 2025). Its architecture is organized around four information operations: blueprint distillation, stateful code memory, conditional retrieval augmentation, and closed-loop error correction (Li et al., 8 Dec 2025). On PaperBench Code-Dev, it reported 73.5 ± 2.8 on the full benchmark versus 51.1 ± 1.4 for PaperCoder and 43.3 ± 1.1 for the best LLM agent baseline, and on a five-paper commercial subset it reported 0.8541 versus 0.5871 for Claude Code (Li et al., 8 Dec 2025). The paper treats the Implementation Blueprint as a “source of truth” for downstream generation (Li et al., 8 Dec 2025).

ResearchCodeAgent targets paper-to-repository codification in machine learning with starter code. It uses a planner, research logs with short- and long-term memory, and a mixed action suite of programmatic and LLM-backed workers (Gandhi et al., 28 Apr 2025). Evaluated on OGSCL, YONA, and FLAG, it reported that 46.88% of generated code fell into S1 high-quality code, 25% of outputs were error-free with performance improvement over baseline, and empirical analysis showed an average reduction of 57.86% in coding time relative to manual repair effort (Gandhi et al., 28 Apr 2025). This demonstrates the repository-refinement variant of agent-first canonical code: the durable artifact is a repository-level implementation aligned with methodological subparts, not merely a generated snippet.

5. Competing design interpretations and adjacent paradigms

Not all relevant work is agent-first at runtime. Skele-Code is explicitly positioned on the opposite side: “Agents are invoked only for code generation and error recovery, not orchestration or task execution” (Gopalakrishnan, 18 Mar 2026). The generated workflow is modular, shareable, and reusable as a skill or as a step in another workflow, but execution is deterministic and topological over a DAG (Gopalakrishnan, 18 Mar 2026). This places Skele-Code closer to agent-assisted canonicalization than to agent-first runtime architecture.

A related but distinct strand concerns custom agents as application-native software artifacts. “Agents All the Way Down” describes a methodology for building custom AI agents from substrate to production, centered on two preconditions—Substrate and Building blocks—and three recurring practices: prototype with a general-purpose agent, harvest/fold/ship as a CLI, and agent-tests-agent (Forment et al., 10 Jun 2026). The paper’s Turtle pattern packages the custom agent as a CLI with session continuation, replay, and parseable output, and its corollary is that multi-agent orchestration is “just CLI composition” (Forment et al., 10 Jun 2026). This extends canonicality from internal workflow logic to deployment interface: the CLI becomes the stable ABI for both humans and other agents.

Another adjacent strand emphasizes semantic standardization at the tool layer. The Agent-First Tool API paper argues that CRUD-style APIs are mismatched to agent requirements because they assume exact identifiers, rendering-oriented responses, single-shot interaction, user-equivalent authorization, and opaque errors (Pan, 11 May 2026). Its contribution is not workflow code but a semantic tool interface above transport standards such as MCP. This suggests that canonical code can reside not only in executable workflows or specifications, but also in tool contracts that normalize search, resolution, preview, verification, and recovery.

Finally, “CodeAgents” codifies multi-agent reasoning into modular pseudocode with control structures, boolean logic, and typed variables (Yang et al., 4 Jul 2025). It does not provide a formal programming language, but it turns Task, Plan, Feedback, roles, and tool invocations into structured artifacts. Across GAIA, HotpotQA, and VirtualHome, it reports input-token reductions of 55–87% and output-token reductions of 41–70%, with a new state-of-the-art success rate of 56% on VirtualHome (Yang et al., 4 Jul 2025). This points to a representational interpretation of canonicality: a compact pseudocode IR for multi-agent interaction, even when the system remains prompt-mediated.

6. Limits, controversies, and open directions

A recurring limitation is that canonicality often depends on substantial upstream engineering. CP-Agent’s architecture is generic, but its CP expertise is “injected solely through a carefully crafted project prompt,” about 700 lines long, and average token usage is about 180k input tokens and 6k output tokens (Szeider, 10 Aug 2025). This makes prompt engineering a major hidden component of the system’s success. Similarly, Codified Context required approximately 26,200 lines of context infrastructure—about 24.2% of the codebase size—across constitution, specialist agents, and subsystem documents, with maintenance overhead of about 1–2 hours per week (Vasilopoulos, 24 Feb 2026).

A second limitation is dependence on strong models and specific environments. The self-bootstrap result relies on “recent state-of-the-art models,” and smaller or earlier models often produced syntactically invalid or behaviorally incorrect implementations (Monperrus, 18 Mar 2026). CP-Agent’s reported success is demonstrated with Claude 4 Sonnet and CPMpy, not across weaker models or alternative solver APIs (Szeider, 10 Aug 2025). DeepCode likewise attributes its strongest results to top proprietary models and notes that smaller models benefit less from retrieval and may dilute retrieved information (Li et al., 8 Dec 2025).

A third issue is representational incompleteness. “Canonical path” analysis of long-horizon tool-use failures defines the canonical structure only as an unordered majority-consensus set of tool names:

$s$8

with adherence measured by Jaccard similarity

$s$9

(Lee, 22 Feb 2026). The paper shows that within mixed-outcome model-task units, successful runs are more adherent to the canonical set than failed runs by +0.060 Jaccard under cross-family leave-one-out, with $\mathrm{agent}_0$0 and $\mathrm{agent}_0$1, and that each off-canonical tool call raises the probability that the next call is also off-canonical by 22.7 percentage points (Lee, 22 Feb 2026). Yet this “canonical path” omits ordering, multiplicity, arguments, and state transitions. The authors explicitly note that richer representations would be needed for a full canonical-code framework (Lee, 22 Feb 2026).

A fourth controversy concerns what should be canonical: source code, specification, workflow graph, tool protocol, or proof-carrying substrate. The strongest inversion appears in “No Accidental Software,” which proposes “agent-first canonical code” as a proof-carrying substrate containing canonical behavior profiles, typed change algebra, proof lanes, constrained edit grammars, semantic patch cells, runtime negative memory, and proof-carrying change objects (Taylor, 12 Jun 2026). It defines a behavior-equivalence relation

$\mathrm{agent}_0$2

under a declared oracle, and a canonicalization map

$\mathrm{agent}_0$3

from an equivalence class to a shortest accepted specification $\mathrm{agent}_0$4, evidence bundle $\mathrm{agent}_0$5, renderer $\mathrm{agent}_0$6, and disposition ledger $\mathrm{agent}_0$7 (Taylor, 12 Jun 2026). The paper’s reduction claims—such as a defensible planning target near 100-fold all-in cost reduction for routine product software—are explicitly hypotheses rather than measured frontier results (Taylor, 12 Jun 2026). This marks the current boundary of the field: the most ambitious formulations remain research programs rather than settled engineering practice.

Open directions follow directly from these limits. One is richer formalization: several papers rely on strong architectural claims without giving full semantics, typed state models, or correctness proofs (Qiu et al., 1 Aug 2025). Another is ambiguity management: natural-language specifications can remain underspecified, and larger specifications may become hard to audit or verify (Monperrus, 18 Mar 2026). A third is portability: many results are single-domain or single-project, and broader cross-domain validation remains open (Vasilopoulos, 24 Feb 2026). A fourth is economic validation: multiple papers argue that canonicalization should reduce reasoning cost, tool retries, and review burden, but few yet report paired same-model, same-task raw-versus-canonical field trials on cost per verified correct change (Taylor, 12 Jun 2026). Across the literature, the strongest stable conclusion is therefore methodological rather than universal: if a convention, workflow, or failure lesson matters repeatedly, recent work increasingly recommends encoding it into a durable agent-facing artifact instead of re-deriving it in each conversation.