Sign in Subscribe

The Library of Intent (LOI): A Deterministic Routing Framework for Human Cognition and AI Execution

Micael Malta

• 6 min read

Abstract In French, Loi means Law. For decades, software engineering has operated under the premise that source code is the definitive artifact. The integration of Large Language Models (LLMs) has accelerated code generation, but early industry experience suggests that optimizing primarily for syntax output introduces maintainability risks. At the same time, probabilistic AI retrieval methods can impose significant verification overhead on developers working in large systems. This paper proposes a structural inversion via the Library of Intent (LOI). By implementing a spatial, hierarchical variation of Specification-Driven Development (SDD), the LOI serves as a dual-purpose architecture: it acts as a cognitive aid for human developers and a deterministic routing protocol for AI agents. In this paradigm, code becomes a transient implementation artifact, while the specification becomes the governing Law (Loi).

1. Introduction: The Limits of Probabilistic Generation

The current trajectory of AI coding assistants optimizes for local syntax generation more effectively than for global architectural integrity. Tools relying on probabilistic inference—even advanced systems—can misalign with how developers understand and maintain large codebases.

Early industry observations suggest a recurring failure mode: when an AI lacks a deterministic map of the system, it tends to reproduce local patterns rather than consolidate shared abstractions. The result is often duplication, inconsistent conventions, and increased verification burden. Simultaneously, this probabilistic approach taxes human operators, who must expend substantial effort validating AI-generated changes across poorly bounded contexts.

2. The Shared Bottleneck: Bounded Context and Scaffolding

To optimize human-AI collaboration, it is useful to note that both Transformer-based LLMs and human developers operate under bounded-context constraints and benefit from explicit scaffolding:

  1. Working Memory vs. Context Window: An LLM has a finite context window; forcing large, unmapped portions of a repository into it dilutes attention and increases the likelihood of error. Human working memory is similarly limited. Both systems perform better when complexity is partitioned into explicit, navigable chunks.
  2. The Need for Scaffolding: An LLM has no intrinsic executive model of a codebase; it requires clear prompts, boundaries, and routing cues to behave reliably. Human developers likewise benefit from strong external structure that reduces search cost, initiation friction, and decision fatigue.

The practical implication is the same in both cases: large systems become more tractable when organized into deterministic entry points and bounded execution contexts.

3. Architectural Comparisons: Execution Routing vs. Content Retrieval

The LOI differs fundamentally from existing paradigms in its approach to infrastructure, state, and retrieval.

  • LOI vs. Retrieval-Augmented Generation (RAG): Modern RAG pipelines reduce noise through AST parsing, semantic chunking, and re-ranking. However, they remain fundamentally probabilistic content retrieval systems: they attempt to retrieve relevance based on similarity. LOI is an execution routing protocol. It uses Markdown files committed directly to Git as routing contracts. Rather than inferring what might be relevant, the system bounds execution context through an explicit master index and linked domain contracts.
  • LOI vs. Knowledge Graphs: Knowledge graphs model dependencies effectively for machines, exposing broad adjacency across a system. But for humans, the result can be visually and cognitively unbounded. LOI combines graph-like connectivity with a spatial tree. It provides a hierarchical entry point for navigation while preserving bounded local adjacency through metadata such as see_also.
  • LOI vs. Pure Specification-Driven Development (SDD): Existing SDD approaches often isolate intent into flat, machine-oriented artifacts. LOI organizes intent spatially (Campus → Building → Room). This turns passive documentation into an active routing layer, versioned directly alongside the code it governs.

Boundary Condition: LOI is not a universal replacement for search, RAG, or graphs. It is most effective in large, long-lived systems with relatively stable domains, clear interfaces, and recurring maintenance or extension work. In smaller or highly fluid codebases, the overhead of maintaining explicit routing contracts may outweigh the benefit.

4. System Mechanics: The LOI Engine in Practice

The LOI operates as a bidirectional control plane designed to address the central systems problem of SDD: drift between intent and implementation.

A. The Topology and the Routing Example

The hierarchy ensures the AI is not merely searching but being routed through bounded execution contexts.

  • Campus (_root.md): The master routing matrix.
  • Building (<subdomain>/_root.md): Functional groupings, such as identity/.
  • Room (<room>.md): The terminal execution contract.

Worked Example: “Add rate limiting to login”

Under a standard RAG approach, the system embeds the prompt and retrieves files associated with terms like “rate,” “limit,” and “login,” often surfacing unrelated middleware or infrastructure concerns.

Under LOI:

  1. The agent parses _root.md and maps “login” to the identity/ Building.
  2. The agent loads identity/_root.md, which routes it to login.md (the Room).
  3. The agent reads login.md:
    • DOES: Handles the OAuth and credential authentication flow.
    • SYMBOLS: login(), validateCredentials()
    • see_also: ["../infra/rate_limit.md"]
  4. The agent then loads only the login contract and the explicitly linked rate-limiting contract.

Result: The system operates within a narrowly bounded context window defined by architectural intent, rather than by semantic proximity alone. This reduces irrelevant context loading and makes both human review and AI execution more precise.

B. The Consensus Loop (Arbitration and Drift Resolution)

To prevent the LOI from devolving into stale documentation, authoring and maintenance are automated through a Consensus Loop.

  • Trigger: A background watcher detects divergence between source code paths and their governing .md contracts using Git diffs, file hashes, or equivalent change signals.
  • Arbitration Model: The system supports bidirectional arbitration.
    • Code-to-Intent (Indexing): If a human changes the source code directly, the code represents immediate implementation reality. Worker agents parse the modified code, regenerate the SYMBOLS and DOES blocks, and propose or commit corresponding Markdown updates.
    • Intent-to-Code (Execution): If a human changes the .md contract, the intent becomes the governing Law. The watcher dispatches an agent to update the underlying source code and run the test suite against the new contract.
  • Conflict Resolution: If tests fail during Intent-to-Code execution, the system does not silently revert or overwrite. Instead, it marks the Room as architectural_health: conflicted, records the failed reconciliation attempt, and pauses for human arbitration.

This loop is the enforcement mechanism that turns the LOI from a navigation artifact into a living control plane.

5. A 10-Level Taxonomy of AI Autonomy

Phase I: Probabilistic Syntax Generation

  • Level 1: The Autocompleter Local predictive text within a narrow scope.
  • Level 2: The Conversational Interface Isolated chat-based execution without persistent architectural grounding.
  • Level 3: The Context-Aware Explorer IDE assistants that use search, embeddings, or repository context to improve local relevance.

Phase II: Deterministic Routing (The Practical Roadmap)

  • Level 4: Spatial Anchoring The codebase is recursively indexed into explicit domains. A TASK → LOAD matrix routes both humans and AI to the correct entry point.
  • Level 5: Predictive Context Domain contracts declare adjacency through metadata such as see_also, allowing the system to pre-load bounded supporting context.
  • Level 6: Multi-Agent Governance Parallel AI personas—such as Architect, Security, or Reliability—evaluate changes during indexing and reconciliation.
  • Level 7: Intent-Driven Execution The specification becomes the executable contract that governs implementation updates.

Phase III: The Speculative Horizon

As tooling matures, decoupling intent from implementation may enable more autonomous behaviors:

  • Level 8: Telemetry-Driven Autonomy LOI integrates with observability systems to trace production failures to intent domains and draft candidate patches.
  • Level 9: Metric-Driven Development AI systems propose contract-level changes in response to product or operational metrics, subject to human review or controlled experimentation.
  • Level 10: Dynamic Synthesis In the most speculative form, some implementations may become increasingly ephemeral, generated on demand from stable intent contracts rather than maintained as fully static artifacts.

These upper levels are not claims about current capability. They represent a possible trajectory enabled by separating durable intent from mutable implementation.

6. Incremental Adoption Path

LOI does not require a repository-wide rewrite. It is designed for progressive adoption.

  1. Phase 1: Read-Only Map Use LLMs to generate an initial _root.md and domain-level contracts. Treat the result as a navigable spatial index for humans and assistants.
  2. Phase 2: Metadata and Governance Introduce YAML frontmatter and structured fields such as see_also, ownership, architectural health, and dependency hints. Allow agents to populate links and run background audits.
  3. Phase 3: The Consensus Loop Activate bidirectional reconciliation. Permit controlled updates to the DOES field to trigger branch creation, code synthesis, and validation workflows.

This staged path allows teams to capture navigational value first, governance value second, and execution value third.

Conclusion: The ROI of Intent

By shifting from probabilistic content retrieval toward deterministic execution routing, the LOI framework aims to improve context precision, navigability, and architectural consistency.

For AI systems, LOI can materially reduce context window footprint by replacing open-ended retrieval with bounded execution paths. For human developers, it reduces the cost of global file-search and restores a stable spatial model of the system. Architecturally, it keeps the routing layer inside the same versioned repository as the code, reducing dependence on external indexing infrastructure for core execution context.

In this model, the specification is no longer passive documentation. It becomes the operational map: the durable layer that governs how humans navigate, how AI agents load context, and how implementation remains accountable to intent.

GitHub: github.com/micaelmalta/loi