Decision infrastructure for coding agents

What should the repository answer before an agent writes code?

The useful question is not whether an agent has seen a large amount of documentation. It is whether the repository can answer which decisions apply to this task, why they apply, what the agent must do or avoid, and how the result will be checked. A decision registry supplies stable identity, status, ownership, scope and relationships. A scope resolver combines deterministic signals such as repository, path, language and dependency edges with semantic signals from the task description. Deterministic scope should win when the repository has enough information to make the match exact.

That combination changes the review conversation. Instead of asking whether the model appears to have remembered a convention, a reviewer can inspect the records returned, the citations in the plan and the checks attached to the changed files. The system is valuable even when no enforcement rule exists: the absence of a rule is recorded as a boundary rather than hidden behind an overconfident green check.

• Record the decision and its lifecycle before building a retrieval shortcut.
• Return a small, ranked set of applicable records with reasons for each match.
• Require stable citations in plans and pull requests.
• Link only objective consequences to blocking checks.

How does a small first implementation become a control plane?

Start with a boundary that already creates repeated review work: a forbidden dependency, a data-residency rule or a required event-publication pattern. Add one accepted record, expose it through the read-only query path, and link one deterministic check. The first loop should be observable from task to merge: record, retrieve, cite and verify. Once the evidence is reliable, add supersession, exception expiry, health monitoring and cross-repository scope rather than trying to model every architectural conversation on day one.

This sequencing keeps the product honest. A control plane is not a new documentation portal and it is not an agent proxy. It coordinates the source record, agent context, source-control workflow and existing enforcement tools while leaving each system responsible for the capability it already performs well.

How should a team model its first decision?

Choose a decision whose absence is already expensive. It might be the rule that domain code cannot import infrastructure, the requirement that events use a transactional outbox, or the policy that customer data remains in a particular region. Write the context in terms a future maintainer can recognise, state the decision in one sentence, and list the consequences that should be visible in code. Then add scope: repository, paths, capabilities, languages or environments. Scope is what turns an interesting document into an applicable record.

Next, decide what the agent should receive. The retrieval response should contain the ID, status, title, concise instructions, prohibited patterns, required checks and a link to the full rationale. It should also explain why the record matched. If no check exists, say that the record is guidance only. That small distinction stops the first implementation from creating a catalogue of promises that CI cannot support.

• One accepted record with a stable ID and owner.
• One deterministic query that returns it for a known task.
• One citation visible in the resulting plan or pull request.
• One check, or an explicit statement that the consequence is not yet machine-checkable.

Why agents expose the missing layer

Software teams have always depended on decisions that are not visible in the source tree: why deletion is reversible, why one library was rejected, which boundary owns authentication, or which compatibility promise cannot be broken. A human who has worked on the system for years may remember these constraints. A coding agent beginning a fresh task does not.

Instruction files help an agent behave consistently, and ADRs preserve architectural rationale. Neither automatically provides the complete path from a question to a cited, current decision and then to an objective merge check. Decision infrastructure connects those stages without asking a model to invent the connection.

The three jobs of decision infrastructure

A useful system has three separate responsibilities. Recording establishes human-reviewed authority. Retrieval gives an agent the smallest relevant set of records with stable citations. Enforcement checks the constraints that can be expressed mechanically while leaving judgement-based decisions visible but explicitly unclassified.

• Record: typed, validated Markdown reviewed in the same workflow as code.
• Retrieve: deterministic queries that return the same cited records for the same repository state.
• Enforce: explicit checks for constraints that can be proved without an LLM judge.

What belongs in the record

The useful unit is not every conversation or every implementation detail. Record decisions whose loss would cause expensive rework, a safety failure, an incompatible interface, or repeated debate. Include the context, the chosen position, rejected alternatives when they matter, consequences, lifecycle state and relationships to other records.

Negative decisions are especially valuable. An agent can usually infer what the current code does; it cannot infer that the team evaluated hard deletion and deliberately rejected it. The rejected path is often the part most likely to be rediscovered and reintroduced.

A minimal implementation

Start with one real decision in the repository. Validate its structure, expose read-only discovery to the agent, and add enforcement only if the constraint has an objective test. This creates value without attempting to reconstruct the entire history of the project.

brew install asdecided/tap/asdecided-core
decided quickstart
decided validate decisions/