Most coding-agent failures begin before code generation. A request is ambiguous, an unstated constraint is missed, or success is never made testable. A spec-driven workflow addresses that problem by turning intent into explicit artifacts before permitting a repository mutation.
“Intent compiler” is a design pattern, not a claim that natural language can be compiled with the guarantees of a conventional programming language. The compiler analogy is useful because it encourages stages, typed intermediate representations, validation, diagnostics, and a clear boundary between planning and execution.
The pipeline
A practical workflow has seven stages:
- Capture intent. Record the requested outcome, affected users, non-goals, constraints, risk class, and unknowns.
- Resolve ambiguity. Ask only questions whose answers materially change the design or authorization.
- Create a contract. Express behavior, acceptance criteria, invariants, interfaces, failure behavior, and evidence required for completion.
- Plan against the repository. Map the contract to current files, dependencies, tests, owners, and operational boundaries.
- Request approval where needed. Human review is mandatory when the contract changes public APIs, data, security boundaries, cost, or production behavior.
- Execute in bounded steps. Apply the smallest authorized patch, run checks, and revise only within the approved contract.
- Return evidence. Report the diff, tests, unresolved assumptions, and any divergence from the plan.
GitHub's Spec Kit presents specifications as living artifacts that guide planning, implementation, and validation. That is a useful operating model: update the specification when intent changes instead of allowing chat history to become the hidden source of truth.
Use a typed intermediate representation
Free-form prose is valuable for humans, but an agent also needs a constrained representation. A minimal contract might include:
{
"goal": "Reject expired upload tokens",
"non_goals": ["Change token issuance"],
"constraints": ["Preserve the public response shape"],
"acceptance": [
"Expired tokens return the existing unauthorized response",
"Valid tokens retain current behavior"
],
"required_checks": ["unit", "integration"],
"approval": "security-owner"
}JSON Schema can validate the structure and types of this artifact. Structured-output features can constrain a model to that schema. Neither mechanism proves that the goal is correct, the acceptance criteria are sufficient, or the repository plan is safe. Semantic review and executable checks remain necessary.
The contract should be versioned with:
- a schema version;
- the repository revision it was derived from;
- provenance for user statements and repository facts;
- explicit assumptions and unresolved questions;
- the policy version that selected approval and verification requirements.
Compile acceptance criteria into checks
An acceptance criterion is strongest when it maps to observable evidence:
- behavior maps to unit, integration, or end-to-end tests;
- API changes map to an OpenAPI document and contract tests;
- data changes map to migration checks, invariants, and rollback evidence;
- performance constraints map to a reproducible benchmark;
- security constraints map to allowlisted analysis and review gates.
OpenAPI is useful because it provides a language-agnostic description of an HTTP API that tools and people can inspect. It can support documentation, generated clients, and testing, but it does not replace domain requirements or runtime validation.
If a criterion cannot be checked automatically, name the reviewer and evidence needed. “Looks good” should not be an implicit test.
Separate planning authority from write authority
An agent may be allowed to inspect a repository and draft a plan without being allowed to edit it. The compiled artifact should carry an authorization envelope:
- allowed paths and tools;
- forbidden operations;
- time, cost, and retry budgets;
- required reviewers;
- conditions that force a stop;
- evidence needed before promotion.
This prevents a strong plan from silently expanding into unapproved execution. It also makes retries safer: a failed test can trigger a bounded repair attempt, while a changed requirement or newly discovered high-risk dependency must return to the approval stage.
Diagnostics are a product feature
A conventional compiler reports why input is invalid. An intent compiler should do the same. Useful diagnostics include:
- “acceptance criterion has no observable check”;
- “requested behavior conflicts with a stated non-goal”;
- “public schema change requires an owner”;
- “repository facts were extracted from a different revision”;
- “required test environment is unavailable”;
- “the proposed patch exceeds the approved path set.”
These messages make the system correctable without exposing internal model reasoning. They should cite the artifact or repository fact that triggered the decision.
Failure modes
- Wrong but well-formed specification: schema validation succeeds while the requirement is incomplete.
- Stale plan: the repository changes after analysis.
- Prompt injection in repository content: comments or documents attempt to override policy.
- Overfitted checks: generated tests merely encode the generated implementation.
- Approval theater: a large artifact hides the few decisions a reviewer must make.
- Unbounded recompilation: every test failure rewrites the goal instead of fixing the implementation.
Mitigations include repository-revision pinning, independent policy enforcement, changed-test review, concise decision summaries, and a strict separation between user intent, repository evidence, and untrusted content.
A practical first version
Start with one change class, such as an internal API modification. Define a small JSON Schema for goals, constraints, acceptance criteria, approval, and checks. Generate a human-readable specification from the same data. Require review before execution, pin the plan to a commit, and evaluate whether the completed change satisfies the original criteria without unapproved scope expansion.
Measure clarification rate, plan rejection rate, escaped requirements, unnecessary edits, verification failures, and reviewer time. The goal is not a longer planning document. It is a smaller, testable agreement that survives the transition from request to code.