TeaQL Agent Kit: A Model-Mediated Harness for Coding Agents

The Problem: Agents Skip the Domain Model

Coding agents typically go from requirement to code in a single pass. The README calls this a prompt-to-code loop: requirement, agent, code, test, repair. The agent invents the domain contract, persistence surface, and business logic at the same time. That is where the trouble starts. The agent has no intermediate representation to check against. It can memorize a rule catalog, but the catalog is large and the agent may not apply it consistently. TeaQL Agent Kit addresses this by placing an executable domain model between intent and code. The model becomes an inspectable artifact that agents, tools, and people can review and revise. The target user is a developer or team building business software with coding agents, especially where the domain logic is complex enough that a wrong contract is costly.

The Harness Pattern: Five Cooperating Parts

The repository describes a harness with five parts. First, an inspectable intermediate representation: KSML turns business intent into a saved artifact. Second, a deterministic feedback oracle: model evaluation returns errors, warnings, suggestions, and repair guidance, rather than relying on the agent to remember rules. Third, a generated action boundary: typed domain APIs and model-aware assist narrow the implementation surface. Fourth, policy-bearing APIs: identity context, query purpose, query comments, and write audits travel with execution. Fifth, evidence-based completion: evaluation, guidance, policy checks, compilation, tests, and runtime results form a traceable chain. The flow diagram in the README shows the agent moving to the model, then to evaluation, then to generated contracts, then to implementation, with verification feeding back defects to either the agent or the model. Human reviewers can give asynchronous feedback to both the model and the implementation. This is a deliberate change in the agent's role: it no longer invents everything at once.

Development-Time Process: Model First, Then Evaluate, Then Generate

The development-time process is strict. The agent must follow a model-first execution order: model, evaluate and repair, generate a typed contract, request current model-aware assist, implement within that contract, and verify with evidence. The SKILL.md file defines this mandatory order. The golden-example.xml provides a compact grammar example without loading a full rule catalog. The toolchains.md binds the workflow to versioned clients, evaluation, generation, and model-aware assist. The work-complete.md defines what evidence is required before the agent reports completion. This is not a suggestion. The harness enforces the order through the Skill definition. The point is to make the agent's actions smaller and more observable. The README states that these constraints do not make an agent infallible. They make its actions easier to review.

Runtime Governance: Policy-Bearing APIs

TeaQL also governs how the resulting application behaves at runtime. Operations carry identity and intent. Reads declare purpose and comment. Writes declare an audit reason. External capabilities are explicitly granted. Typed entity graphs constrain mutation. The README is careful to say that runtime governance does not choose the correct business policy. It makes application actions contextual, bounded, observable, and auditable once that policy is chosen. This is a meaningful distinction. The harness does not replace business logic. It wraps it with metadata that travels with execution. The policy-bearing APIs are part of the generated contract, so the agent cannot skip them. This runtime layer is separate from the development-time process, but both are part of the same governance model.

Getting It Running: Workspace Configuration and Commands

The README provides concrete commands and configuration files. Generated manifests always declare published TeaQL dependencies, never local filesystem paths. A consumer workspace selects the source independently with teaql-workspace.yaml. Two examples are provided: teaql-workspace.workspace.yaml and teaql-workspace.release.yaml. These files use JSON-compatible YAML so the verifier has no third-party dependency. The commands are: ./tools/teaql_workspace.py apply --config teaql-workspace.yaml --workspace /path/to/generated-application and ./tools/teaql_workspace.py verify --config teaql-workspace.yaml. The apply command writes .teaql/runtime-source-evidence.json in the application workspace. The runtimeSource key can be either 'workspace' or 'release'. The workspace mode resolves the seven runtime repositories, records their exact commits and dirty state, and is used while changing a runtime. The release mode requires package versions and rejects path overrides, for published-package regression. The harness verifies the selected repositories before native package-manager commands run. The generator neither creates nor guesses native overrides like Maven reactor or Cargo patch.

Limitations and Failure Modes

The kit is a reference implementation, not a turnkey product. The README does not list limitations explicitly, but several are visible from the material. The model-first workflow is mandatory. If your team is not willing to invest in modeling before coding, the harness will feel like overhead. The evaluation service is deterministic, but it depends on the quality of the model. A poorly modeled domain will produce a valid but wrong contract. The README says the goal is not deterministic AI but deterministic structure. That means the agent can still make mistakes within the structure. The verification step includes compile, test, runtime, and policy checks, but it cannot catch business logic errors that pass those checks. The runtime governance requires that operations carry identity and intent. If your application does not need that level of auditability, the generated code may be more complex than necessary. Also, the live Generation Service is a separate service at api.teaql.io, so the kit depends on its availability. The README is truncated, so details on installation and dependencies beyond the workspace tool are not fully visible.

Alternatives: Prompt Engineering and Rule Catalogs

The most direct alternative is to keep the prompt-to-code loop and rely on prompt engineering to guide the agent. That approach has no intermediate representation and no deterministic evaluation. The agent must hold the entire rule catalog in its context, which is what TeaQL explicitly avoids. Another alternative is a rule-based linter or code review tool that checks the output after the agent writes it. That is reactive, not preventive. TeaQL's difference is that the model is inspectable and the evaluation happens before code generation. The generated typed contract narrows the implementation surface, so the agent does not invent APIs. A third alternative is to use a human reviewer to check the agent's code, but that does not scale and does not provide repair guidance. The README positions TeaQL as a model-mediated harness, not a code-generation Skill. That distinction matters: it is not just another template or prompt.

Maintenance and License

The project is licensed under MIT, which is permissive and allows commercial use and modification. The repository is not archived, and the last push was in July 2026, with a v2.0.0 release on the same date. The README describes the harness as a reference implementation, which implies that users may need to maintain their own integrations. The runtime source selection mechanism is designed to handle versioning: the workspace mode records exact commits and dirty state, which is useful for development, while the release mode enforces published package versions. This suggests that the maintainers expect consumers to track changes in the runtime repositories. The generated manifests always declare published dependencies, so you must update those versions as the runtime evolves. The evidence chain includes evaluation reports and runtime results, which you may need to store for audit purposes. There is no information about long-term support or migration guides in the provided material, so plan for your own upgrade testing.

Editorial conclusion

Adopt TeaQL Agent Kit if you are building business software with coding agents and need more than prompt-based guardrails. It suits teams that can commit to a model-first workflow and are willing to keep the model, evaluation service, and generated contracts in sync. Do not use it for small scripts, quick prototypes, or domains where the model overhead outweighs the benefit. Before adopting, verify that the evaluation service is available and that the runtime source selection (workspace vs. release) matches your deployment process. Check that the generated code for your target language (Java, Rust, Go, Swift, Python, C#/.NET, TypeScript) is mature enough for your needs. The kit is a reference implementation, not a turnkey product, so expect to invest in integrating it with your existing agent tooling.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes