# TeaQL Agent Kit: a model-first harness for coding agents on TEAQL business software

> TeaQL Agent Kit puts an inspectable domain model between a coding agent's intent and the code it writes. It is a reference harness, not an agent, and its value depends on whether the generated contract and runtime governance fit how your team already builds software.

**teaql/teaql-agent-kit** — Deterministic execution for non-deterministic AI. It provides tasks, prompts, guides, and reports for observing how coding agents behave when working with TEAQL-based business software.

- Repository: https://github.com/teaql/teaql-agent-kit
- Website: https://teaql.io
- Stars: 2,813 · Forks: 957
- Language: Python
- License: MIT
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/teaql-teaql-agent-kit

## The problem TeaQL Agent Kit addresses: agents that invent the domain contract

A coding agent given a business requirement typically moves straight to implementation. It picks entity names, persistence shapes and API signatures in the same pass that it writes business logic. When the result is wrong, the reviewer has to read a diff to find out which decision was bad, and the agent has no artifact to repair other than the code itself.

TeaQL Agent Kit targets that specific failure. It is aimed at teams building business software on TEAQL, where the domain model is supposed to be the source of truth. The repository describes itself as a reference implementation of a model-mediated harness, and the README frames the goal plainly: not deterministic AI, but deterministic structure around non-deterministic AI. If your agents work on TEAQL applications, the kit is written for you. If they work on anything else, it is not.

## How the harness works: KSML, a feedback oracle, and a generated contract

The README shows the control flow as a pipeline rather than a loop. A requirement goes to the agent, the agent produces an inspectable KSML model, a deterministic evaluation service returns errors and repair guidance, and only a validated model is turned into a generated typed contract. Implementation then happens inside that contract, with model-aware assist teaching the agent which API exists for the current domain.

The harness has five named parts. The inspectable intermediate representation is the KSML artifact. The deterministic feedback oracle is the evaluator, which returns errors, warnings, suggestions and current repair guidance so the agent does not have to memorize a rule catalog. The generated action boundary narrows what the agent can call. Policy-bearing APIs carry identity context, query purpose, query comments and write audits with execution instead of leaving them as prompt advice. Evidence-based completion ties evaluation, guidance, policy checks, compilation, tests and runtime results into one traceable chain.

Verification routes defects back to different places. An implementation defect goes back to the agent; a model defect goes back to the KSML model. That split is the most interesting design choice in the kit, because it means a wrong answer can be corrected at the model layer without discarding working code. The README is explicit that these constraints do not make an agent infallible. They make its actions smaller and easier to review.

## Installing TeaQL Agent Kit and running your first workspace apply

The repository does not publish a pip package or an install command. What it publishes is a skill directory plus tooling under tools/. The README points readers at skills/build-teaql-app/SKILL.md for the mandatory model-first execution order, and at references/toolchains.md for the versioned clients, evaluation, generation and model-aware assist bindings. Start there before writing any code.

A consumer workspace selects where the runtime comes from with teaql-workspace.yaml. The README says to start from examples/teaql-workspace.workspace.yaml or examples/teaql-workspace.release.yaml, and notes that these files use JSON-compatible YAML so the verifier needs no third-party dependency. The two modes are not interchangeable: workspace resolves the seven runtime repositories and records their exact commits and dirty state, while release requires package versions and rejects path overrides.

The apply command writes the selected source into a generated application workspace. The README gives this invocation:

```bash
./tools/teaql_workspace.py apply \
  --config teaql-workspace.yaml \
  --workspace /path/to/generated-application
```

After apply runs, you should see .teaql/runtime-source-evidence.json inside the application workspace. That file is the record of which repositories were selected and what state they were in.

The verify command checks the configuration without applying it:

```bash
./tools/teaql_workspace.py verify --config teaql-workspace.yaml
```

One boundary matters here. The kit does not create native package-manager overrides. Maven reactor or local repository, Cargo patch, Go workspace or replace, npm workspace, Swift package edit, .NET project reference and Python editable install all remain workspace-owned. The harness verifies the selected repositories before those native commands run, but the generator neither creates nor guesses them, so a working build still depends on overrides your workspace supplies.

## Where the model-first requirement becomes a real constraint

The mandatory execution order is the kit's biggest limitation as much as its point. If your team wants an agent to fix a one-line bug in an existing TEAQL application, the harness still routes work through model, evaluation, contract generation and constrained implementation. That is more steps than the task needs, and the README does not describe any bypass for small changes.

The runtime governance layer has a similar boundary. The README states directly that runtime governance does not choose the correct business policy. It makes actions contextual, bounded, observable and auditable once that policy has been chosen. So a team hoping the kit will decide what the right audit reason or query purpose should be is looking at the wrong layer. The kit enforces that a write declares an audit reason; it does not tell you what the reason is.

There is also a version-binding risk. The workflow is bound to versioned clients, evaluation, generation and model-aware assist through toolchains.md. Nothing in the README describes what happens when those versions drift apart, and the repository does not document rollback. Treat the toolchain file as the thing you must pin and re-check on every upgrade.

## TeaQL Agent Kit compared with a prompt-to-code agent framework

The obvious alternative is a general agent framework where the loop is requirement to agent to code to test to repair, with no intermediate artifact. The README draws that contrast itself. In that model the agent owns the domain contract, the persistence surface and the business logic simultaneously, and the reviewer's only artifact is the code.

The difference is not that one is smarter. It is where the constraint lives. A prompt-to-code framework constrains the agent through instructions and tests. TeaQL Agent Kit constrains it through a saved KSML model that a deterministic evaluator can reject, plus a generated typed contract that bounds what the agent may call. That makes the review surface a model and an evaluation report rather than a diff.

The cost is scope. A general framework can be pointed at any repository; this kit assumes TEAQL business software and a generation service that produces libraries for Java, Rust, Go, Swift, Python, C#/.NET or TypeScript. If you are not on that stack, the harness has nothing to mediate.

## Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-07-31, which is also the date of the v2.0.0 release. There is no separate release cadence visible in the README, and no changelog is described, so an upgrade path has to be inferred from the toolchain bindings rather than from release notes.

The project is MIT licensed. That is permissive and places few obligations on how you redistribute or modify the code, but it says nothing about the generated application workspaces, the live Generation Service at api.teaql.io, or the runtime repositories the workspace mode resolves. Those are separate concerns and the README does not describe their terms. Check them yourself rather than assuming the MIT grant covers the whole path from requirement to running application.

The practical upgrade cost sits in two files. teaql-workspace.yaml decides whether you resolve runtime from workspace or release, and toolchains.md decides which versions of the clients, evaluator and model-aware assist the skill expects. Changing either without re-running the verify command leaves you without evidence that the selected repositories match what the skill was written against.

## Conclusion

Adopt TeaQL Agent Kit if your team builds TEAQL-based business applications and wants the model, the evaluation report and the generated contract to be the review surface rather than the diff. Skip it if you need a general-purpose agent framework for arbitrary codebases, or if you cannot accept a model-first step before any implementation. Before committing, verify that the toolchains.md bindings match the client, evaluator and assist versions you actually run, and confirm whether runtimeSource should be workspace or release for your workflow.

## FAQ

### What is TeaQL Agent Kit and how does it work?

It is a model-mediated harness for coding agents working on TEAQL-based business software. An agent turns a requirement into an inspectable KSML model, a deterministic evaluation service returns errors and repair guidance, a validated model becomes a generated typed contract, and implementation happens inside that contract.

### Is TeaQL Agent Kit free to use?

The repository is MIT licensed, which is permissive for the code published there. The README does not describe the terms of the live Generation Service or of the runtime repositories that workspace mode resolves, so those need to be checked separately.

### How do I install TeaQL Agent Kit?

The repository does not publish an install command. It publishes a skill under skills/build-teaql-app plus tooling under tools/, and the README points readers at SKILL.md and references/toolchains.md as the starting artifacts.

## Sources

- [Official documentation](https://teaql.io)
- [Official README](https://github.com/teaql/teaql-agent-kit#readme)
- [Project repository](https://github.com/teaql/teaql-agent-kit)
- [Release notes](https://github.com/teaql/teaql-agent-kit/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/teaql-teaql-agent-kit