teaql/teaql-agent-kit

What it solves

When you use a coding agent (like Claude Code, Codex, Cursor, GitHub Copilot, or Gemini CLI) to build software, the agent often jumps straight from your request to writing code, which can lead to messy results, hidden assumptions, and hard-to-review business logic. TeaQL Agent Kit fixes that by inserting a structured, inspectable step between your idea and the code: the agent first models your business—customers, products, orders, etc.—then that model is checked, repaired, and turned into a typed contract the agent must work against. The result is less code to review, clearer intent, and an audit trail that shows what actually ran.

How it works

Instead of a simple "requirement → code" loop, TeaQL imposes a controlled pipeline:

1. Model first – The agent translates your natural-language requirement into a domain model (objects, fields, relationships).
2. Evaluate and repair – A deterministic evaluation service checks the model for errors and gives specific repair guidance; the agent fixes it until it passes.
3. Generate – The validated model is turned into a typed domain library (with Q and E APIs) backed by a reusable runtime.
4. Implement – The agent writes application-specific code in a scaffolded workspace, using the generated contract and progressive model-aware Assist (which loads only the API guidance needed for the current step).
5. Verify – The final delivery is proven by build results, tests, a runtime smoke test, and an evidence-backed completion report (work-complete.md) that you can inspect.

Two layers of reliability run through this: development-time process (the model-first order) and runtime governance (every operation carries identity and intent, reads declare purpose/comment, writes carry an audit reason, and mutations are bounded by typed entity graphs).

Who it’s for

This is for developers and teams who already use AI coding agents and want more reliable, auditable output without learning a completely new toolchain. You paste one prompt into your existing agent, give it access to the repository instructions and permission to run commands, and it walks through the workflow. It’s especially useful for projects where business logic is complex and you need to review less code while trusting that the shared plumbing (query building, data access, audit logs) is handled correctly.

Highlights

• Model-first workflow – The agent builds and repairs an executable domain model before writing application code.
• Deterministic evaluation – Errors, warnings, and suggestions come from a fixed service, not the agent’s guesswork.
• Typed Q and E APIs – Queries (Q) and expressions (E) let you compose readable, reviewable business logic; the compiler catches invalid calls early.
• Explicit audit trail – Logs tie user identity, declared intent, SQL, affected rows, and created entities together—useful for debugging and compliance.
• Context efficiency – The harness reduces irrelevant context by loading only needed API guidance, and uses explicit context lifetimes (ephemeral vs. named blocks) to keep prompts clean.
• Works with local models – Tested on NVIDIA DGX Spark; a benchmark project shows a 30-object moving-company model reaching zero evaluation errors after repair.