Skip to content
Back to search

teaql-agent-kit

A model-driven harness for AI coding agents: semantic modeling, app generation, progressive API Assist and evidence-based verification.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/teaql--teaql-agent-kit/badge.svg)](/listings/teaql--teaql-agent-kit)

HTML

<a href="/listings/teaql--teaql-agent-kit"><img src="/api/listings/teaql--teaql-agent-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For the TeaQL workflow alone:

npx skills add teaql/teaql-agent-kit --skill build-teaql-app

Then ask your agent:

Use $build-teaql-app to draft and save a complete KSML model, evaluate and
repair it, then generate, implement and verify a runnable application: ...

| Path | Responsibility | | --- | --- | | [`skills/build-teaql-app/`](skills/build-teaql-app/) | Model-first Skill, grammar example, versioned toolchains, incremental repair and completion evidence | | [`packages/agent-context-kit/`](packages/agent-context-kit/) | Independent `@teaql/agent-context-kit` package, host adapters, marker maintenance and controlled tasks | | [`integrations/pi-teaql/`](integrations/pi-teaql/) | Optional trusted Rust TeaQL tools for protected Pi | | [`tools/teaql_workspace.py`](tools/teaql_workspace.py) | Explicit workspace/release runtime-source selection and verification | | [`docs/`](docs/) | Activation guides and recorded integration evidence |

The Skill does not require the Node workspace. Runtime development uses Node.js 22.19+, pinned Pi 1.4.0 and OpenCode plugin SDK 2.1.4 development dependencies. Install or publish the explicit child package, never the private repository root. See [workspace development](docs/context-runtime.md) and [host installation](packages/agent-context-kit/docs/installation.md).

Select runtime source explicitly

Generated manifests declare published TeaQL dependencies. A consumer's `teaql-workspace.yaml` chooses `workspace` mode with exact runtime repositories and commit/dirty-state evidence, or `release` mode with package versions and no local overrides. Start from the [workspace](examples/teaql-workspace.workspace.yaml) or [release](examples/teaql-workspace.release.yaml) example.

./tools/teaql_workspace.py apply --config teaql-workspace.yaml --workspace /path/to/application
./tools/teaql_workspace.py verify --config teaql-workspace.yaml

Overrides stay application-owned; the generator does not insert a maintainer's local paths. `apply` records `.teaql/runtime-source-evidence.json`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "teaql",
  3. "description": "TeaQL plugins for coding-agent workflows",
  4. "owner": {
  5. "name": "TeaQL"
  6. },
  7. "plugins": [
  8. {
  9. "name": "agent-context-kit",
  10. "source": "./packages/agent-context-kit",
  11. "description": "Protocol guidance for deterministic agent context lifecycles"
  12. }
  13. ]
  14. }
README.md · README · 580 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # TeaQL Agent Kit
  2. > Already have a coding agent? Give it one prompt to start building with TeaQL.
  3. <table>
  4. <tr>
  5. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/claude-code.svg" width="56" height="56" alt="Claude Code"><br>Claude Code</a></td>
  6. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/codex.svg" width="56" height="56" alt="Codex"><br>Codex</a></td>
  7. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/cursor.svg" width="56" height="56" alt="Cursor"><br>Cursor</a></td>
  8. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/github-copilot.svg" width="56" height="56" alt="GitHub Copilot"><br>GitHub Copilot</a></td>
  9. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/gemini-cli.svg" width="56" height="56" alt="Gemini CLI"><br>Gemini CLI</a></td>
  10. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/pi.svg" width="56" height="56" alt="Pi"><br>Pi</a></td>
  11. </tr>
  12. <tr>
  13. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/qoder.svg" width="56" height="56" alt="Qoder"><br>Qoder</a></td>
  14. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/deepseek-harness.svg" width="56" height="56" alt="DeepSeek Harness"><br>DeepSeek Harness</a></td>
  15. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/zcode.png" width="56" height="56" alt="ZCode"><br>ZCode</a></td>
  16. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/trae.svg" width="56" height="56" alt="TRAE"><br>TRAE</a></td>
  17. <td align="center"><a href="#start-with-a-prompt"><img src="assets/coding-agents/opencode.svg" width="56" height="56" alt="OpenCode"><br>OpenCode</a></td>
  18. <td align="center"><a href="packages/agent-context-kit/docs/octop-adapter.md"><img src="packages/agent-context-kit/assets/coding-agents/octop.svg" width="56" height="56" alt="Octop"><br>Octop</a></td>
  19. </tr>
  20. </table>
  21. **Your coding agent + one prompt → start building with TeaQL.**
  22. TeaQL Agent Kit combines a model-first application workflow with tools that
  23. govern an agent's context, file access and verification. The two components
  24. can be used separately:
  25. | Component | What it provides | Entry point |
  26. | --- | --- | --- |
  27. | **Build TeaQL App Skill** | Model → evaluate → generate → implement → verify, using current model-aware Assist | [`build-teaql-app`](skills/build-teaql-app/SKILL.md) |
  28. | **Agent Context Kit** | Context lifetimes, marker-aware file policy, controlled tools and host adapters | [`@teaql/agent-context-kit`](packages/agent-context-kit/) |
  29. A coding agent that can read Skill instructions can follow the TeaQL workflow.
  30. Runtime enforcement depends on its specific adapter and entry point; the agent
  31. logos above do not imply that every governance feature is active.
  32. [Quick start](#start-with-a-prompt) · [Workflow](#how-the-workflow-fits-together) ·
  33. [Governance](#governance-engineering) · [Agent support](#agent-feature-activation) ·
  34. [Verification](#verification-and-evidence) · [Installation](#installation-and-repository-layout)
  35. ## Start with a prompt
  36. Open a project folder in your coding agent and paste this into its chat—not
  37. your terminal:
  38. ```text
  39. Follow the instructions from https://github.com/teaql/teaql-agent-kit
  40. Build a small order-management application with customers, products, and
  41. orders, using Rust and SQLite. Evaluate and repair the business model,
  42. generate a runnable console application, and exercise Q queries and E
  43. expressions in tests and a runtime smoke test. Report the actual results and
  44. any remaining problems.
  45. Finish with a short, evidence-backed development report in work-complete.md:
  46. - Evaluate from a 2026-and-beyond, AI-assisted development perspective using
  47. the tools and model actually tested, not an assumption that humans must
  48. manually learn every modeling rule and generated API. Assess what the agent
  49. can learn from instructions and Assist, and what human effort remains.
  50. Judge runnable results, correctness, change effort, and operational costs;
  51. do not treat novelty or unfamiliar syntax alone as reasons to avoid trying
  52. the framework. Record demonstrated friction and risks, not generic warnings
  53. or assumptions that AI eliminates every learning cost.
  54. - Show Q query and E expression examples from the application you actually
  55. ran, explaining how their typed APIs helped express the business logic.
  56. - Inspect the evaluation, generation, build/test, and runtime logs. Cite
  57. relevant excerpts, including query purpose/comment and write audit context
  58. where present; report missing evidence and unresolved failures.
  59. - Explain what work the model, generated library, runtime, and progressive
  60. Assist handled, and what application code and human decisions remained.
  61. - Report actual token/context usage if available. Claim token savings only
  62. with a comparable measured baseline; otherwise mark savings not measured
  63. and explain the potential benefit of loading only relevant API guidance.
  64. - Explain how model validation, consistent typed APIs, and regeneration may
  65. help larger projects. Separate observations from this run from expectations
  66. that this small example has not tested. Include costs and limitations.
  67. ```
  68. The final report should help you judge what TeaQL contributed to your own
  69. development task, with runnable code and log evidence you can inspect.
  70. Replace the example requirement with your own. The agent needs access to the
  71. repository instructions, permission to work in your project folder, and the
  72. ability to run development commands.
  73. **What to expect:** the agent may need to install or update TeaQL clients and
  74. language build tools, download dependencies, and call TeaQL services for model
  75. evaluation, generation, and API guidance. Network access is required for this
  76. default workflow, and model content is sent to the configured service. Review
  77. your agent's permission requests and your organization's data-sharing policy
  78. before using private business requirements. One prompt starts the workflow;
  79. it does not mean zero setup, no follow-up questions, or guaranteed success.
  80. If you already have a local checkout, replace the first line with its path:
  81. ```text
  82. Follow the instructions from ~/teaql-agent-kit
  83. ```
  84. Use the actual checkout path on the machine where your agent runs. A local
  85. checkout changes where instructions are read; it does not by itself make
  86. evaluation and generation offline.
  87. ## How the workflow fits together
  88. ```mermaid
  89. flowchart LR
  90. R[Business requirement] --> M[Saved KSML model]
  91. M --> E[Evaluate and repair]
  92. E -->|Zero errors| G[Generated typed contract]
  93. G --> A[Assist and application code]
  94. A --> V[Compile, test and runtime evidence]
  95. V -->|Diagnostic| A
  96. ```
  97. The model defines the domain. The generated library supplies domain-specific
  98. typed APIs; the language runtime handles shared execution and persistence.
  99. Application-owned source holds business rules, integrations and UI.
  100. | Stage | Agent work | Governance and review surface |
  101. | --- | --- | --- |
  102. | Model and evaluate | Save complete KSML, evaluate, repair errors | Inspect the model and service findings before generation |
  103. | Generate | Generate only advertised targets after zero errors | Keep generated implementation separate from editable application source |
  104. | Implement | Read the generated guide and current entity/action and field Assist | Review focused business code; preserve query purpose/comment and write audit reasons |
  105. | Verify | Compile, test, repair locally, exercise the requested runtime behavior | Record actual results, counts and blockers before claiming completion |
  106. A zero-error model triggers **Model Ready** with the saved model path and
  107. evaluation counts. The agent continues working while a person reviews the
  108. model or application. Feedback that changes the domain contract returns through
  109. evaluation and regeneration. Human review can run in parallel.
  110. ## What you get
  111. See the benefits in a real application: the **Robot Task Board** showcase.
  112. **Review less code to judge whether the business logic is correct.** Typed
  113. queries and expressions keep business intent in a small, readable surface,
  114. while the generated library and runtime handle shared mechanics. You still
  115. review business rules and verify results; you do not have to reconstruct the
  116. same query-building and data-access plumbing in every application method.
  117. ### Q API — compose queries you can review
  118. Q describes what to load: filters, selected fields, related objects, ordering,
  119. limits, and facets. Requests are composable: extract a child query or facet
  120. into a named helper, then reuse it inside another query. Review each piece
  121. and its composition instead of tracing scattered SQL construction and manual
  122. result assembly. Typed field methods also let the compiler catch invalid API
  123. calls before execution.
  124. ```rust
  125. let task = Q::tasks()
  126. .with_id_is(id)
  127. .comment("Load task for status transition")
  128. .purpose("Move a task on the board")
  129. .execute_for_one(&ctx)
  130. .await?;
  131. ```
  132. Adapted from the demo's [task service](https://github.com/teaql/robot-task-board/blob/main/rust-app-console/src/service.rs).
  133. ### E API — access business data with explicit safety
  134. E provides typed paths through fields and related objects. It distinguishes
  135. an absent value from data that was never loaded: optional values can have an
  136. explicit fallback, while access to unloaded data produces a diagnostic rather
  137. than silently treating it as missing. That reduces hand-written casts,
  138. string-key lookups, and nested null checks. A reviewer can focus on the access
  139. path, whether the query loaded it, and how absence is handled.
  140. ```rust
  141. // Read the name from an already-loaded status object.
  142. let name = E::task_status(status)
  143. .get_name()
  144. .eval()
  145. .unwrap_or(raw_str);
  146. ```
  147. From the [showcase's E API example](https://teaql.io/blog/robot-task-board-showcase/),
  148. where `raw_str` supplies the display fallback.
  149. ### Execution and audit trail
  150. Follow a task transition through SQL, recorded changes, events, and the
  151. refreshed board to debug behavior and investigate operations.
  152. An excerpt from the demo's [recorded log](https://github.com/teaql/robot-task-board/blob/2560f9b73961eb1b26542d0ec91d5826b48421e5/actual-log.txt)
  153. shows a task creation:
  154. ```text
  155. [TIME]-[philip]-[DURATION]-[DEBUG]-SqlLogEntry - [Create task 'Review Mission Timeline'] - [1 rows affected]
  156. INSERT INTO task_data (id, name, version, status, platform) VALUES (1, 'Review Mission Timeline', 1, 1001, 1)
  157. [TIME]-[philip]-[AUDIT]-Entity [Task] CREATED. [Create task 'Review Mission Timeline'] {id: U64(1), name: Text("Review Mission Timeline"), platform_id: U64(1), status: U64(1001), version: I64(1)}
  158. ```
  159. The recorded file already normalizes timestamps and durations to `[TIME]`
  160. and `[DURATION]`; these are not measured timings from a new run. The excerpt
  161. ties the user identifier and declared intent to the SQL, affected-row count,
  162. and created entity values—evidence you can inspect without tracing every
  163. internal function call.
  164. Developers supply intent and audit context; the runtime records execution and
  165. changes through its configured logging and audit facilities. That makes the
  166. trail useful for everyday debugging and observability, not just compliance.
  167. **[Explore the source on GitHub](https://github.com/teaql/robot-task-board)**
  168. · **[Read the illustrated walkthrough](https://teaql.io/blog/robot-task-board-showcase/)**
  169. The walkthrough documents the demo's API version. For a newly generated
  170. application, use its current model-aware Assist for exact API calls.
  171. ## Governance engineering
  172. Instructions explain the workflow. Supporting host tools enforce what can be
  173. read, changed, executed and carried into the next model request. TeaQL's
  174. language runtimes separately govern the resulting application's data operations.
  175. | Capability | Mechanism | Where it is enforced |
  176. | --- | --- | --- |
  177. | **Model-first delivery** | Saved KSML, semantic evaluation, zero-error generation gate | Skill workflow; the trusted Pi Rust tool also gates generation against the unchanged evaluated model |
  178. | **Focused API discovery** | Entity/action Assist, then field-specific Assist; no generated-source discovery | Skill rules and the configured read boundary |
  179. | **Context lifetimes** | Consume-once messages, named blocks and trusted discard | Supporting lifecycle adapters; the transcript remains intact |
  180. | **Read and write policy** | `.agent-no-read.md`, pruned traversal, explicit write roots and read-only paths | Protected Pi and OpenCode entry points |
  181. | **Actionable failures** | Non-retryable error codes, scoped denial reminders, bounded structured diagnostics | Pi policy tools and the optional Rust integration |
  182. | **Completion verification** | Successful edits invalidate checks; premature stops trigger missing build/test checks | Protected Pi with both host-approved verification tools registered |
  183. | **Stalled-conversation recovery** | Detect repeated action promises without tools; rebuild the request view while preserving user instructions and the transcript | Protected Pi, including resumed old sessions; one automatic recovery per request |
  184. | **Runtime governance** | Identity, query purpose/comment, audited writes and explicitly granted capabilities | The selected TeaQL language runtime |
  185. ### Keep generated implementation out of context
  186. Keep KSML, application guides and editable business source readable. Put an
  187. English `.agent-no-read.md` inside each generated implementation directory:
  188. ```text
  189. project/
  190. models/
  191. rust-lib-core/lib/
  192. .agent-no-read.md
  193. rust-app-console/
  194. AGENTS.md
  195. src/
  196. context-markers.json
  197. ```
  198. ```markdown
  199. # Generated Code
  200. This directory contains generated implementation files.
  201. Use TeaQL Assist to discover APIs and edit application source outside this directory.
  202. Do not retry excluded files with different paths, line ranges or tools.
  203. Update the KSML model and regenerate through the authorized workflow.
  204. ```
  205. The file's existence activates exclusion in a marker-aware adapter. Its body is
  206. bounded project guidance, not permission to bypass policy. Reads, searches and
  207. listings check policy before exposing excluded source or traversing its subtree.
  208. A [durable marker manifest and maintenance CLI](packages/agent-context-kit/docs/context-marker-maintenance.md)
  209. restore and check markers after generation replaces directories.
  210. Read exclusion and write permission are independent. The shared
  211. [file policy](packages/agent-context-kit/docs/file-policy.md) defaults to no writes
  212. and supports explicit `writeRoots` and `readOnlyPaths`. There is no
  213. `.agent-no-write.md` protocol. Protected Pi permits checked `write`/`edit`;
  214. OpenCode strict mode adds controlled create/overwrite/edit/delete/move. Parent
  215. directories must exist. These controls are not an operating-system sandbox.
  216. ### Load guidance for its useful lifetime
  217. Keep stable principles, load the required Assist when needed, and retire
  218. temporary guidance after use. This avoids API discovery through a large
  219. generated library and reduces stale material carried between requests.
  220. **Consume once (“burn after reading”)** — mark temporary guidance or a large
  221. tool result for one response:
  222. ```markdown
  223. <!--ephemeral-->
  224. Task-specific API guidance needed for the next implementation step.
  225. ```
  226. The marker applies to the entire containing message or tool result. After the
  227. assistant responds, the adapter replaces that content with a small tombstone
  228. in subsequent model requests. The original remains in the transcript for
  229. inspection; “burn” does not mean secure erasure.
  230. **Named block** — keep a phase's instructions active across requests:
  231. ```markdown
  232. <!--BLOCK_ID:phase_modeling-->
  233. Evaluate and repair the business model before generating application code.
  234. <!--/BLOCK_ID:phase_modeling-->
  235. ```
  236. Once that phase is complete, a trusted workflow explicitly discards it:
  237. ```markdown
  238. <!--DISCARD_BLOCK:phase_modeling-->
  239. ```
  240. The block is then absent from the next model request. Blocks come from trusted
  241. context sources; ordinary tool output cannot revoke instructions. This lets
  242. the harness retain the rules needed now without carrying every earlier phase's
  243. instructions forever. See the [lifecycle protocol](packages/agent-context-kit/docs/protocol-v1.md)
  244. and [Pi adapter](packages/agent-context-kit/docs/pi-adapter.md)
  245. for enforcement and integration details.
  246. ### Return errors that support recovery
  247. Protected Pi returns a policy denial as an actual tool error with explicit
  248. feedback, rather than a successful empty result:
  249. ```json
  250. {
  251. "status": "excluded",
  252. "blocked": true,
  253. "retryable": false,
  254. "code": "CONTEXT_ACCESS_DENIED"
  255. }
  256. ```
  257. Canonical directory counters connect repeated attempts across aliases and tools.
  258. Every call rechecks current policy; permitted work continues. Binary executables,
  259. oversized files, missing files and permission failures also return explicit
  260. errors. Pi probes at most 512 header bytes before loading a body.
  261. With the [trusted TeaQL Rust tools](integrations/pi-teaql/README.md), use `teaql`
  262. for evaluation, progressive Assist and gated library regeneration, `app_build`
  263. for policy-filtered Rust diagnostics, and `app_test` for real test counts.
  264. Executables in `target/debug/` are not compiler logs. The diagnostic adapter
  265. recognizes `PurposedQuery<T>` stage errors: filters, projection, ordering and
  266. paging belong before `purpose(...)`. Raw compiler output and excluded source
  267. are suppressed.
  268. ### Recover a conversation that repeats without tools
  269. Protected Pi detects repeated action promises without intervening tool calls.
  270. It automatically rebuilds the request view, keeping system/tool instructions,
  271. active policy and all user instructions while retiring old assistant/tool
  272. narratives before the recovery marker. The transcript and session ID remain
  273. intact. Recovery is bounded to one attempt per user request, with an explicit
  274. blocker if promise-only replies continue. See the
  275. [actual old-session recovery](docs/pi-old-session-recovery-verification.md).
  276. ### Verify edits before accepting completion
  277. When both `app_build` and `app_test` are registered, protected Pi tracks
  278. successful file mutations. If the model stops before running required checks,
  279. the host invokes the missing fixed tools and returns their actual results to
  280. the model for continuation. Another edit invalidates previous checks again.
  281. An assistant's promise to compile is not verification.
  282. User cancellation stops the checks. Automatic verification is bounded to three
  283. rounds per user request; exhausted work is reported as `VERIFICATION_INCOMPLETE`.
  284. Failed checks remain failures, and zero executed tests do not establish coverage.
  285. See the [completion contract](packages/agent-context-kit/docs/pi-cli-policy.md#completion-verification-after-mutations).
  286. ## Agent feature activation
  287. **Repository implementation snapshot: 2026-10-25 (Asia/Shanghai).** Choose an
  288. entry point explicitly. Installing a lifecycle plugin does not also activate
  289. marker-aware filesystem policy, TeaQL tools or completion verification.
  290. | Agent / entry point | Context lifetimes | Read / write control | TeaQL tools and completion | Verification level |
  291. | --- | --- | --- | --- | --- |
  292. | **Pi protected native CLI** | Inline lifecycle; trusted phase-source wiring remains separate | Marker-aware reads/search/list and checked `write`/`edit` | Optional Rust `teaql`, `app_build`, `app_test`; automatic completion checks when both verification tools are registered | Native CLI tests plus real-model Linux recovery, completion and t003 repair runs |
  293. | **OpenCode V2 strict plugin** | Optional trusted lifecycle file | Marker-aware reads/search/list; explicit write roots and controlled mutations | Configurable fixed diagnostics; no TeaQL tool module or Pi completion integration | Pinned SDK/bridge plus OpenCode CLI 2.1.4 real-model t003 read/write and fixed build/test validation |
  294. | **Pi / OpenCode ordinary lifecycle plugins** | Named blocks, trusted discard, consume-once | Optional configured ReadGuard; no shared write-policy integration | Separate from protected modes | Adapter tests |
  295. | **Pi dedicated SDK harness** | No lifecycle adapter composed by default | Marker-aware, read-only | Optional fixed checks; no native-CLI completion integration | Real Pi SDK with deterministic provider |
  296. | **Cline / Kilo / MiMo / DeepSeek / Gemini** | Full or host-limited lifecycle views | Varies; some expose configured ReadGuard, without the strict marker-aware filesystem | No completion integration claimed | Host-specific adapter tests and documented API limits |
  297. | **Hermes / Kimi / Qwen / Kiro** | Active blocks/current-request context; no consume-once history rewriting | Configured ReadGuard; no shared write policy | No completion integration claimed | Python or command-hook tests |
  298. | **Octop** | Named blocks, trusted discard and consume-once on main-agent requests | Opt-in marker-aware local `read_file` | No completion integration claimed | [Harness graph test](packages/agent-context-kit/docs/octop-adapter.md#verify) |
  299. | **Copilot CLI / Crush** | No lifecycle rewriting | Configured ReadGuard; Crush covers top-level calls only | No completion integration claimed | Command-hook tests |
  300. | **Codex / Claude Code / Cursor and other Skill-capable hosts** | Protocol guidance where packaged | No Context Kit runtime enforcement claimed | Follow the Skill with the host's available tools | Guidance or packaging is separate from enforcement |
  301. **ReadGuard** is configured path/tool blocking. **Marker policy** additionally
  302. controls traversal and checked automatic context. They are different boundaries.
  303. See the [full per-agent activation matrix and setup](docs/agent-feature-activation.md)
  304. and [adapter compatibility details](packages/agent-context-kit/docs/compatibility.md).
  305. ### Runtime identity in models
  306. The modeling Skill now runs its bundled [runtime provenance helper](skills/build-teaql-app/references/runtime-provenance.md) before model-derived operations. It reads the current Codex session or an explicit host runtime bundle, preserves the lifecycle UUID, and writes actual Agent/version/provider/model on the entry root. Remote execution captures on the Agent host first. Missing facts remain unknown; default configuration is not treated as the active model.
  307. ### Use protected Pi
  308. The host must wire the native bootstrap behind ordinary `pi` and explicitly
  309. configure any trusted TeaQL tools. Start a fresh session after installation or
  310. updates:
  311. ```sh
  312. cd /path/to/project
  313. pi
  314. ```
  315. A separate `pi-context` command is unnecessary once that launcher is configured.
  316. Existing sessions retain imported code until restarted. See
  317. [Pi bootstrap setup](packages/agent-context-kit/docs/pi-cli-policy.md) and
  318. [TeaQL Rust tool configuration](integrations/pi-teaql/README.md).
  319. ### Use OpenCode V2 strict mode
  320. Opt in with `createOpenCodeContextPolicyPlugin` in an isolated V2 profile, set
  321. host-approved write roots and context paths, and use a fresh session. Do not
  322. combine it with the ordinary lifecycle plugin. V1 strict mode is unsupported.
  323. The [setup example](docs/agent-feature-activation.md#activate-opencode-v2-strict-mode)
  324. and [policy guide](packages/agent-context-kit/docs/opencode-context-policy.md)
  325. explain its tool catalog, prompt admission and trusted-host limits.
  326. Both protected modes disable arbitrary shell, unguarded MCP/delegation and
  327. automatic external resource loading at their controlled entry points. Protected
  328. Pi restores selected development operations through host-approved capability
  329. modules; it does not restore an unrestricted terminal.
  330. ## Verification and evidence
  331. | Evidence | Observed result | What it establishes |
  332. | --- | --- | --- |
  333. | Repository checks | **154 passed**: 118 package unit, 21 integration, 8 root contract and 7 Python tests | Parser, policy, filesystem, lifecycle, packaging, diagnostics and completion contracts; deterministic providers are used in local Pi integration tests |
  334. | Ordinary Pi, real-model failure recovery | Four failure paths each read once, followed by build/test diagnostics | Explicit denial, binary, oversized-file and missing-file recovery in the recorded run |
  335. | Ordinary Pi, real-model premature completion | A standalone Rust edit followed by model `stop`; host build/test passed with **1 test** | The completion hook can resume after an early stop without a follow-up user prompt |
  336. | [Pi old-session recovery](docs/pi-old-session-recovery-verification.md) | Resumed the actual stuck session, restored file reads and analysis, retained its ID/history, then answered a follow-up | Read-only conversation recovery; no `/new`, no manual continuation prompt, no new business correctness claim |
  337. | [Actual t003 business repair](docs/t003-business-repair-verification.md) | Real-model localized repair, build passed, test command exited 0 with **0 cases**, no continuation prompt | Existing application compilation and verification flow; no business-test coverage or database runtime proof |
  338. | [OpenCode strict mode on t003](docs/opencode-t003-verification.md) | Real-model denied read/write probes, one permitted comment edit, build/test exit 0 with **0 cases**, no continuation prompt | Installed CLI 2.1.4 profile and SDK/bridge validation; Pi automatic completion guard and TeaQL capability module remain separate |
  339. The t003 record includes the failed first attempt: completion checks ran, but
  340. generic diagnostics did not lead to the right repair. The subsequent typed
  341. query-stage diagnostic enabled the successful run. Completion checks catch
  342. missing verification; they do not guarantee that every model repairs every bug.
  343. The [DGX Spark benchmark](https://github.com/teaql/nvidia-dgx-spark-model-benchmark)
  344. provides separate model-evaluation experiments, including a
  345. [30-object repair run](https://github.com/teaql/nvidia-dgx-spark-model-benchmark/blob/main/reports/moving-company-30-pipeline.md).
  346. That evidence does not establish full application correctness. Token/context
  347. savings remain unmeasured without a comparable baseline.
  348. Reproduce repository checks from the private workspace root:
  349. ```sh
  350. npm ci
  351. npm run check
  352. npm pack --workspace @teaql/agent-context-kit
  353. ```
  354. ## Installation and repository layout
  355. For the TeaQL workflow alone:
  356. ```sh
  357. npx skills add teaql/teaql-agent-kit --skill build-teaql-app
  358. ```
  359. Then ask your agent:
  360. ```text
  361. Use $build-teaql-app to draft and save a complete KSML model, evaluate and
  362. repair it, then generate, implement and verify a runnable application: ...
  363. ```
  364. | Path | Responsibility |
  365. | --- | --- |
  366. | [`skills/build-teaql-app/`](skills/build-teaql-app/) | Model-first Skill, grammar example, versioned toolchains, incremental repair and completion evidence |
  367. | [`packages/agent-context-kit/`](packages/agent-context-kit/) | Independent `@teaql/agent-context-kit` package, host adapters, marker maintenance and controlled tasks |
  368. | [`integrations/pi-teaql/`](integrations/pi-teaql/) | Optional trusted Rust TeaQL tools for protected Pi |
  369. | [`tools/teaql_workspace.py`](tools/teaql_workspace.py) | Explicit workspace/release runtime-source selection and verification |
  370. | [`docs/`](docs/) | Activation guides and recorded integration evidence |
  371. The Skill does not require the Node workspace. Runtime development uses Node.js
  372. 22.19+, pinned Pi 1.4.0 and OpenCode plugin SDK 2.1.4 development dependencies.
  373. Install or publish the explicit child package, never the private repository root.
  374. See [workspace development](docs/context-runtime.md) and
  375. [host installation](packages/agent-context-kit/docs/installation.md).
  376. ### Select runtime source explicitly
  377. Generated manifests declare published TeaQL dependencies. A consumer's
  378. `teaql-workspace.yaml` chooses `workspace` mode with exact runtime repositories
  379. and commit/dirty-state evidence, or `release` mode with package versions and no
  380. local overrides. Start from the
  381. [workspace](examples/teaql-workspace.workspace.yaml) or
  382. [release](examples/teaql-workspace.release.yaml) example.
  383. ```sh
  384. ./tools/teaql_workspace.py apply --config teaql-workspace.yaml --workspace /path/to/application
  385. ./tools/teaql_workspace.py verify --config teaql-workspace.yaml
  386. ```
  387. Overrides stay application-owned; the generator does not insert a maintainer's
  388. local paths. `apply` records `.teaql/runtime-source-evidence.json`.
  389. ## Supported languages and runtime evidence
  390. TeaQL application generation supports **Java, Rust, Go, Swift, Python, C#/.NET
  391. and TypeScript**. Kotlin/JVM applications consume generated Java libraries and
  392. the Java runtime; there is no eighth generator/runtime. Swift provides a
  393. local-first SQLite runtime and TFP client, with no separate editable application
  394. target or TFP server. C++, Dart, Ruby and other unlisted ecosystems are unsupported.
  395. This seven-language generation support is separate from the current protected
  396. Pi tool integration, which handles the Rust workflow subset described above.
  397. Use the service's current target catalog and model-aware Assist for exact APIs.
  398. The [historical runtime/database matrix](docs/runtime-feature-snapshot.md) records
  399. its **2026-08-12** evidence; it has not been reverified as part of this README
  400. reorganization.
  401. ## Runnable Examples and Harness Evidence
  402. The Agent Kit defines the shared harness pattern. Runnable applications remain
  403. in language-specific repositories so their toolchains, dependencies, and
  404. release cycles can evolve independently:
  405. - [TeaQL Java App Examples](https://github.com/teaql/teaql-java-app-examples)
  406. - [TeaQL Rust App Examples](https://github.com/teaql/teaql-rust-app-examples)
  407. | Example | Application surface | Harness behavior demonstrated |
  408. | --- | --- | --- |
  409. | [Java Robot Task Board](https://github.com/teaql/teaql-java-app-examples/tree/main/001-robot-task-board-android) | Local Android application | Model-derived typed CRUD, query purpose and comment, audited writes, and visible SQL execution logs |
  410. | [Java Vending Machine Desktop](https://github.com/teaql/teaql-java-app-examples/tree/main/002-vending-machine-compose-desktop) | Compose Desktop and SQLite | A generated domain library embedded in a local desktop application |
  411. | [Java World Cup CLI](https://github.com/teaql/teaql-java-app-examples/tree/main/003-world-cpu-2006-cli) | Interactive CLI and SQLite | Declarative domain modeling, generated query and entity APIs, relational queries, and audited persistence |
  412. | [Java Vending Machine](https://github.com/teaql/teaql-java-app-examples/tree/main/005-vending-machine-web-spring-boot) | Spring Boot, [Quarkus](https://github.com/teaql/teaql-java-app-examples/tree/main/006-vending-machine-web-quarkus), and [Micronaut](https://github.com/teaql/teaql-java-app-examples/tree/main/007-vending-machine-web-micronaut) | One modeled domain hosted across multiple Java application frameworks |
  413. | [Rust World Cup CLI](https://github.com/teaql/teaql-rust-app-examples/tree/main/001-world-cpu-2006-cli) and [TUI](https://github.com/teaql/teaql-rust-app-examples/tree/main/002-world-cup-2006-tui) | Interactive CLI, TUI, and SQLite | Model-to-generated-library separation, typed `Q` and `E` APIs, and audited graph persistence |
  414. | [Rust Linux System Info](https://github.com/teaql/teaql-rust-app-examples/tree/main/003-linux-sysinfo-using-teaql) | Linux `/proc` provider and console UI | A generated typed query boundary applied to an operating-system capability rather than a conventional database |
  415. These examples provide runnable application and code evidence. An end-to-end
  416. recording can complement them with agent-execution evidence: the initial model,
  417. evaluation and repair rounds, generated assist, policy checks, compilation,
  418. tests, and runtime results.
  419. ## TeaQL Generation Service
  420. [Explore the live model-to-application walkthrough](https://api.teaql.io/latest/).
  421. The Generation Service provides the most complete model-derived output set:
  422. - Java, Rust, Go, Swift, Python, C#/.NET, and TypeScript typed domain libraries
  423. - Editable application workspaces
  424. - Model evaluation and repair guidance
  425. - Progressive query assist: request `language-assist-query/entity` for the
  426. executable base query and field index, then
  427. `language-assist-query/entity.field` for exact select/filter/order/group/
  428. facet/aggregate methods. Assist locations always use canonical KSML names.
  429. - Object-specific create, update, delete, and expression assist
  430. - Runtime and tool guides generated for the current domain
  431. - Data-design, model-view, and frontend model outputs
  432. Kotlin/JVM application code is supported through the generated Java library
  433. and TeaQL Java runtime, as demonstrated by the
  434. [Compose Desktop vending-machine example](https://github.com/teaql/teaql-java-app-examples/tree/main/002-vending-machine-compose-desktop).
  435. It is application-language interoperability, not a separate eighth runtime or
  436. generation target.
  437. Swift is a current `swift-lib-core` generation target with a local-first SQLite
  438. runtime for iOS and macOS and a TFP client. It does not currently provide a
  439. Swift TFP server or a separate editable application-workspace target. C++,
  440. Dart, Ruby, and other unlisted smaller language ecosystems are not currently
  441. supported.
  442. ### Open-source Rust generation
  443. Developers who want to inspect or extend an open-source generation service
  444. written in Rust can explore
  445. [teaql-forge-rs](https://github.com/teaql/teaql-forge-rs). Forge is a small open
  446. implementation and does not claim full feature parity with the TeaQL Generation
  447. Service.
  448. ## Explore the Kit
  449. - [Build TeaQL App Skill](skills/build-teaql-app/SKILL.md)
  450. - [TeaQL Java runtime](https://github.com/teaql/teaql-java)
  451. - [TeaQL Rust runtime](https://github.com/teaql/teaql-rs)
  452. - [Open-source Rust generator](https://github.com/teaql/teaql-forge-rs)
  453. - [TeaQL](https://teaql.io)
  454. ## License
  455. The TeaQL Skill and repository-root material use the [MIT License](LICENSE).
  456. The independently publishable `packages/agent-context-kit/` package retains its
  457. [Apache-2.0 License](packages/agent-context-kit/LICENSE); bundled assets retain
  458. their accompanying licenses.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.