@andreprado/agentkit 0.1.0-alpha.21 → 0.1.0-alpha.22

package/src/providers/pi.ts

@@ -17,7 +17,7 @@ import type { AgentProviderName, AgentTool } from "../index";
 import { AgentKitError } from "../runtime/errors";
 import type { ProviderAdapter, ProviderRunInput, ProviderRunResult } from "./types";
 
-const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter"] as const satisfies AgentProviderName[];
+const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter", "opencode", "opencode-go"] as const satisfies AgentProviderName[];
 const MAX_TOOL_TURNS = 8;
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 const UNKNOWN_OPENROUTER_CONTEXT_WINDOW = 128000;
@@ -159,7 +159,13 @@ async function runPiTurn(
 }
 
 function toPiProvider(provider: string): Provider {
-  if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
+  if (
+    provider === "openai" ||
+    provider === "anthropic" ||
+    provider === "openrouter" ||
+    provider === "opencode" ||
+    provider === "opencode-go"
+  ) {
     return provider;
   }
 
@@ -181,6 +187,10 @@ function requireProviderApiKey(provider: Provider, env: Record<string, string |
 }
 
 function defaultProviderSecretNames(provider: Provider): string[] {
+  if (provider === "opencode" || provider === "opencode-go") {
+    return ["OPENCODE_API_KEY"];
+  }
+
   return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
 }
 

package/src/runtime/chat.ts

@@ -20,6 +20,7 @@ export type RunAgentMessageOptions = {
   signal?: AbortSignal;
   runtime?: Partial<ToolRuntimeContext>;
   now?: Date;
+  localStoragePath?: string;
 };
 
 export type AgentRunResult = ProviderRunResult & PersistedChatRun;
@@ -28,7 +29,8 @@ export async function runAgentMessageFromCwd(
   cwd: string,
   options: RunAgentMessageOptions,
 ): Promise<AgentRunResult> {
-  return runAgentMessage(await loadAgentCapsule(cwd), options);
+  const capsule = await loadAgentCapsule(cwd);
+  return runAgentMessage(withLocalStoragePath(capsule, options.localStoragePath), options);
 }
 
 export async function runAgentMessage(
@@ -208,6 +210,10 @@ function normalizeConversationId(value: string | undefined): string | undefined
   return conversationId;
 }
 
+function withLocalStoragePath(capsule: LoadedAgentCapsule, storagePath?: string): LoadedAgentCapsule {
+  return storagePath ? { ...capsule, storagePath } : capsule;
+}
+
 function withToolVisibilityInstructions(instructions: string, tools: LoadedAgentCapsule["config"]["tools"] = []): string {
   const internalTools = tools.filter((tool) => tool.visibility === "internal").map((tool) => tool.name).sort();
 

package/src/runtime/config.ts

@@ -27,7 +27,7 @@ import { isValidTimeZone } from "./prompt-context";
 
 const CONFIG_FILE = "agentkit.config.ts";
 const AGENT_RUNTIMES = new Set<AgentRuntime>(["local", "edge"]);
-const PROVIDERS = new Set<AgentProviderName>(["test", "openai", "anthropic", "openrouter", "custom"]);
+const PROVIDERS = new Set<AgentProviderName>(["test", "openai", "anthropic", "openrouter", "opencode", "opencode-go", "custom"]);
 const ACCESS_MODES = new Set<AccessMode>(["private", "token", "public"]);
 const TOOL_VISIBILITIES = new Set<ToolVisibility>(["user", "internal"]);
 const CHANNEL_TYPES = new Set<ChannelType>(["website", "telegram", "whatsapp", "discord", "slack", "webhook"]);

package/src/runtime/evals.ts

@@ -1,5 +1,6 @@
-import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
 import type { Dirent } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -243,35 +244,49 @@ async function runEvalCase(
   const failures: string[] = [];
   let output = "";
   const now = resolveEvalNow(file, evalCase.now);
+  const evalStore = await createEvalStore();
 
-  for (const [index, turn] of turns.entries()) {
-    try {
-      const run = await runAgentMessageFromCwd(root, {
-        message: turn.input,
-        conversationId,
-        now,
-        runtime: {
-          environment: "eval",
-          invocation: "eval",
-        },
-      });
-      const persistedToolCalls = await loadPersistedToolCalls(root, run.runId);
-      const turnFailures = evaluateExpectations(turn.expect ?? {}, run, persistedToolCalls);
-
-      for (const failure of turnFailures) {
-        failures.push(turns.length === 1 ? failure : `turn ${index + 1}: ${failure}`);
+  try {
+    for (const [index, turn] of turns.entries()) {
+      try {
+        const run = await runAgentMessageFromCwd(root, {
+          message: turn.input,
+          conversationId,
+          now,
+          localStoragePath: evalStore.databasePath,
+          runtime: {
+            environment: "eval",
+            invocation: "eval",
+          },
+        });
+        const persistedToolCalls = await loadPersistedToolCalls(root, run.runId, evalStore.databasePath);
+        const turnFailures = evaluateExpectations(turn.expect ?? {}, run, persistedToolCalls);
+
+        for (const failure of turnFailures) {
+          failures.push(turns.length === 1 ? failure : `turn ${index + 1}: ${failure}`);
+        }
+
+        output = run.message.content;
+      } catch (error) {
+        failures.push(turns.length === 1 ? formatEvalFailure(error) : `turn ${index + 1}: ${formatEvalFailure(error)}`);
+        break;
       }
-
-      output = run.message.content;
-    } catch (error) {
-      failures.push(turns.length === 1 ? formatEvalFailure(error) : `turn ${index + 1}: ${formatEvalFailure(error)}`);
-      break;
     }
+  } finally {
+    await rm(evalStore.directory, { recursive: true, force: true });
   }
 
   return { failures, output };
 }
 
+async function createEvalStore(): Promise<{ directory: string; databasePath: string }> {
+  const directory = await mkdtemp(join(tmpdir(), "agentkit-eval-"));
+  return {
+    directory,
+    databasePath: join(directory, "agentkit.db"),
+  };
+}
+
 function resolveEvalNow(file: string, value: EvalCase["now"]): Date | undefined {
   if (value === undefined) {
     return undefined;
@@ -382,9 +397,9 @@ async function loadEvalCase(file: string): Promise<EvalCase> {
   return module.default;
 }
 
-async function loadPersistedToolCalls(root: string, runId: string): Promise<ToolCallSnapshot[]> {
+async function loadPersistedToolCalls(root: string, runId: string, localStoragePath?: string): Promise<ToolCallSnapshot[]> {
   const capsule = await loadAgentCapsule(root);
-  const store = await openCapsuleStore(capsule);
+  const store = await openCapsuleStore(localStoragePath ? { ...capsule, storagePath: localStoragePath } : capsule);
 
   try {
     return store.listToolCallsForRun(runId).map(toolCallSnapshotFromStored);

package/src/templates/blank.ts

@@ -66,6 +66,7 @@ node_modules/
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 OPENROUTER_API_KEY=
+OPENCODE_API_KEY=
 `,
       },
       {
@@ -148,7 +149,7 @@ The capsule root is the runtime boundary. Run, inspect, evaluate, and deploy fro
 
 ## Coding Agent Workflow
 
-When the owner opens this folder in Codex, Claude Code, or another coding agent and asks for a specific agent, treat that request as the product brief.
+When the owner opens this folder in Codex, Claude Code, or another coding agent and asks for a specific agent, treat that request as the product brief. The owner should not need to run a separate AgentKit wizard or prepare a brief file.
 
 Start building immediately:
 
@@ -158,11 +159,26 @@ Start building immediately:
 - Edit \`prompts/instructions.md\` for the agent behavior.
 - Edit \`agentkit.config.ts\` for provider, tools, secrets, access, and storage.
 - Add TypeScript tools under \`tools/\` when the requested agent needs actions or external data.
+- When the agent needs to save durable records, complete the full slice: schema/migration, tool, config registration, prompt instructions, direct tool check, and eval.
 - Add \`sync.ts\`, \`seed.sql\`, and ordered \`migrations/*.sql\` when the requested agent depends on external catalogs or production-shaped data changes.
 - Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; you decide the implementation from the owner's brief.
 - Ask follow-up questions only when missing information blocks a safe local implementation.
 - State assumptions in the final response.
 
+## Proactive Agent Builder Contract
+
+Do not only edit prompts. For every meaningful requirement in the owner's request or \`AGENT_SPEC.md\`, decide what should enforce it:
+
+- spec entry for the product contract;
+- prompt instruction for behavior, tone, boundaries, intake, and escalation;
+- tool plus config registration for actions, live data, external writes, or authorization-sensitive data;
+- schema/migration plus tool for durable records;
+- eval for privacy, confirmation, required fields, date/time behavior, business rules, and regressions;
+- fixture, seed data, fake branch, or direct tool check for integrations and failure paths;
+- deploy/readiness check for hosted secrets, channels, integrations, or production access.
+
+If a rule protects privacy, money, bookings, external writes, customer data, business hours, or safety, it must have an eval or deterministic check before you call the capsule done. If a real conversation exposes a bug, convert it into the smallest regression eval before or alongside the fix.
+
 ## Local Commands
 
 - \`npm install\`: restore capsule dependencies if this capsule used \`--no-install\`, install failed, or \`node_modules\` was deleted.
@@ -188,7 +204,7 @@ Start building immediately:
 - Local UI: run \`npm run dev\`, open the printed \`Chat:\` URL, and tell the owner the exact URL.
 - Hosted UI: after \`npm run agentkit -- deploy\`, run \`npm run agentkit -- chat-ui --deploy\`, open the printed \`Chat:\` URL, and tell the owner it is connected to the hosted deploy.
 - \`test/fake\` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but it does not validate natural conversation quality.
-- Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+- Before claiming real conversation behavior is tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
 
 This blank capsule starts with the built-in \`test/fake\` provider, so local chat works without secrets or internet access. It is also deploy-ready by default: the user can edit the prompt, add tools, and run \`npm run agentkit -- deploy\`.
 
@@ -253,7 +269,9 @@ This folder is an AgentKit Agent Capsule.
 
 ## Start Here
 
-If the owner asks you to build an agent in natural language, that request is the brief. Do not ask them to fill another file first.
+If the owner asks you to build an agent in natural language, that request is the brief. Do not ask them to run a wizard or fill another file first.
+
+Build a testable capsule, not only a prompt.
 
 Example owner request:
 
@@ -265,7 +283,10 @@ Turn the request into a working local capsule:
 - Create or update \`AGENT_SPEC.md\` with \`npm run agentkit -- spec init --brief "<owner request>"\`. The owner gives the general idea; the coding agent turns it into the structured contract.
 - Update \`agentkit.config.ts\` when tools, secrets, provider, or access rules change.
 - Add TypeScript tools under \`tools/\` for real actions or external data.
+- For durable records, implement the full schema/tool/prompt/eval slice instead of only adding a table or only adding a tool.
 - Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
+- For every privacy, confirmation, required-intake, timezone, business-hour, integration-error, or no-leak rule, add an eval, fixture, fake branch, or direct tool check.
+- Convert failed or surprising real conversations into regression evals with \`npm run agentkit -- eval from-conversation <conversation-id>\`.
 - Keep the first version runnable with \`test/fake\` unless the owner explicitly asks for a real provider.
 - Do not use a wizard or recipe. Build the capsule directly from the scaffold, the AgentKit contract, and the owner's brief.
 - Make practical assumptions and list them in your final response.
@@ -281,6 +302,8 @@ npm run chat -- --message "hello"
 
 \`test/fake\` proves the scaffold and deterministic tool paths. It does not prove natural conversation quality.
 
+Before saying the agent is done, make sure important requirements have matching checks. Prompt-only changes are not enough for privacy, external writes, bookings, customer data, business hours, or integration failures.
+
 \`agentkit new\` installs dependencies by default. Run \`npm install\` only if the capsule was created with \`--no-install\`, install failed, or \`node_modules\` was deleted.
 
 Set local development secrets without opening code:
@@ -310,7 +333,7 @@ npm run agentkit -- chat-ui --deploy
 
 Open the printed \`Chat:\` URL and tell the owner this local UI is connected to the hosted deploy.
 
-Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them. After they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them. After they choose, update \`agentkit.config.ts\`, \`.env.schema\`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
 
 If you add a tool, also run a fake-provider tool smoke test:
 
@@ -354,7 +377,7 @@ Use AgentKit conventions when editing this project.
 - Local runtime state lives in \`.agentkit/\` and should not be committed.
 - The default provider is \`test/fake\`, which needs no secrets.
 - Real providers run through AgentKit's internal Pi SDK backend.
-- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, or Anthropic automatically.
+- Ask the owner which real provider to use before switching from \`test/fake\`; do not choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, or OpenCode Go automatically.
 - Production secrets must be managed secrets, not committed files.
 - Keep required local secret names in \`.env.schema\` and values in ignored \`.env\`. AgentKit local commands load \`.env\` directly.
 - Treat the owner's natural-language request as the brief and start implementing inside this capsule.
@@ -383,7 +406,7 @@ When a real provider or tool needs a local development secret, keep the required
 
 For UI testing, run \`npm run dev\` and open the printed \`Chat:\` URL. After hosted deploy, run \`npm run agentkit -- chat-ui --deploy\` and open its printed \`Chat:\` URL.
 
-\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, or another supported provider before real model behavior is tested.
+\`test/fake\` does not validate real conversation quality. The owner must choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider before real model behavior is tested.
 
 ## Files
 

package/src/templates/dentista.ts

@@ -64,6 +64,7 @@ node_modules/
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 OPENROUTER_API_KEY=
+OPENCODE_API_KEY=
 `,
       },
       {
@@ -865,7 +866,21 @@ Esta é uma AgentKit Agent Capsule para a Clara, atendente em português de um c
 
 A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibilidade e agenda consultas em slots de 30 minutos. Ela também consulta e altera o próprio horário do cliente usando email e telefone como verificação mínima.
 
-Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`. O dono dá a ideia geral; o agente de código transforma isso no contrato estruturado.
+Quando o dono pedir mudanças em linguagem natural, trate a mensagem como o brief. O dono não deve precisar rodar wizard ou preparar arquivo de brief. Crie ou atualize \`AGENT_SPEC.md\` com \`npm run agentkit -- spec init --brief "<pedido do dono>"\`; o agente de código transforma a ideia geral no contrato estruturado.
+
+## Contrato Proativo De Produto Testável
+
+Não edite apenas o prompt. Para cada requisito relevante do pedido ou do \`AGENT_SPEC.md\`, decida qual artefato deve garantir o comportamento:
+
+- entrada no spec para o contrato de produto;
+- instrução no prompt para comportamento, tom, limites, coleta de dados e escalonamento;
+- ferramenta mais registro no config para ações, dados vivos, escritas externas ou dados sensíveis;
+- schema/migration mais ferramenta para dados duráveis;
+- eval para privacidade, confirmação, campos obrigatórios, horário comercial, datas, duração e regressões;
+- fixture, seed, branch fake ou teste direto de ferramenta para integrações e caminhos de erro;
+- checagem de deploy/readiness para secrets hosted, canais, integrações ou acesso de produção.
+
+Regras que protegem privacidade, agendamento, confirmação, dados de cliente, horário comercial ou segurança precisam de eval ou checagem determinística antes de dizer que a cápsula está pronta. Se uma conversa real revelar bug, transforme em uma eval de regressão pequena antes ou junto da correção.
 
 ## Regras de Produto
 
@@ -908,16 +923,19 @@ Quando o dono pedir mudanças em linguagem natural, crie ou atualize \`AGENT_SPE
 - UI local: rode \`npm run dev\`, abra a URL impressa em \`Chat:\` e informe essa URL exata ao dono.
 - UI pós-deploy: depois de \`npm run agentkit -- deploy\`, rode \`npm run agentkit -- chat-ui --deploy\`, abra a URL impressa em \`Chat:\` e informe que ela está conectada ao deploy hospedado.
 - \`test/fake\` é determinístico. Ele valida scaffold, ferramentas e evals previsíveis, mas não valida qualidade de conversa natural.
-- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono.
+- Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono.
 
 ## Regras de Implementação
 
 - Use \`ctx.db\` nas ferramentas. Não importe drivers SQLite, Turso ou Node-only APIs.
 - Mantenha \`schema.sql\` idempotente com \`CREATE TABLE IF NOT EXISTS\` e \`CREATE INDEX IF NOT EXISTS\`. Use \`migrations/*.sql\` ordenadas para evolução de schema com cara de produção.
+- Quando a mudança exigir persistência nova, implemente a fatia completa: schema/migration, ferramenta, registro no config, instruções no prompt, teste direto da ferramenta e eval.
 - Use \`npm run agentkit -- sync init\` quando a agente depender de catálogo externo, fixture local ou seed padronizado.
+- Para regras de privacidade, confirmação, campos obrigatórios, timezone, horário comercial, duração, erro de integração ou no-leak, adicione uma eval, fixture, branch fake ou teste direto de ferramenta.
+- Transforme conversas reais com falhas em regressão com \`npm run agentkit -- eval from-conversation <conversation-id>\`.
 - Mantenha segredos em \`.env\`, nunca em arquivos versionados.
 - Não espere wizard ou recipe. AgentKit fornece o scaffold e o contrato; implemente diretamente conforme o brief do dono.
-- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais/hosted.
+- Para trocar para um provider real, o dono deve escolher OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Depois edite \`agentkit.config.ts\`, atualize \`.env.schema\` e configure secrets locais/hosted.
 - Quando a próxima ação não for óbvia, comece por \`skills/agentkit-capsule/SKILL.md\`.
 `,
       },
@@ -995,7 +1013,7 @@ npm run agentkit -- chat-ui --deploy
 
 Abra a URL impressa em \`Chat:\` e informe que essa UI local está conectada ao deploy hospedado.
 
-Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
+Antes de dizer que a conversa real foi testada, pergunte ao dono qual provider usar: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go ou outro provider suportado. Não escolha pelo dono. Depois configure \`agentkit.config.ts\`, \`.env.schema\`, secrets locais e secrets hosted se for deployar.
 
 ## Deploy
 

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -7,6 +7,8 @@ description: Use when the owner gives a natural-language brief for a new or chan
 
 Use this when the owner asks for an agent in plain language.
 
+The owner should only need to run `agentkit new <name>`, open the capsule in Codex or another coding agent, and say what agent they want. Do not send them back to the CLI for a brief wizard. Treat their chat message as the brief and build the first useful local capsule.
+
 ## Workflow
 
 1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
@@ -17,8 +19,34 @@ Use this when the owner asks for an agent in plain language.
 6. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
 7. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
 8. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
-9. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
-10. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+9. Turn requirements into checks as you build. Every privacy rule, external write, confirmation step, business-hour rule, timezone rule, required intake field, and customer-data boundary needs an eval, direct tool check, fixture, or deterministic fake path.
+10. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+11. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Requirement-To-Verification Loop
+
+For each item in the brief or `AGENT_SPEC.md`, classify it before finishing:
+
+- prompt-only behavior: add a prompt instruction and a response eval when the wording or boundary matters;
+- required intake such as name, phone, email, budget, or account id: add a multi-turn eval that proves the agent asks before acting;
+- tool call or external write: add a persisted tool-call eval and a direct `agentkit tool` check;
+- database record: implement the complete slice in the next section;
+- scheduling, deadlines, or timezone: set `timeZone`, freeze eval `now`, and assert the date/time sent to tools;
+- privacy/no-leak rule: add a no-leak eval with `notContains` or `notRegex`;
+- integration failure such as rate limit, timeout, unavailable slot, or missing auth: add a fixture, fake branch, or eval-safe tool behavior.
+
+If a requirement is important enough to mention in the spec, it is usually important enough to test. State any untested requirement in the final response.
+
+## Complete Slice
+
+When the brief implies durable records such as leads, clients, bookings, tickets, or notes, do the whole local slice:
+
+- add or update `schema.sql` and ordered `migrations/*.sql` when appropriate;
+- add the `defineTool` implementation under `tools/`;
+- register the tool in `agentkit.config.ts`;
+- teach `prompts/instructions.md` when and how to use the tool;
+- add a direct tool check fixture or command;
+- add an eval that proves the agent calls the tool in the expected flow.
 
 ## Templates
 

package/src/templates/skills/agentkit-capsule/SKILL.md

@@ -7,6 +7,27 @@ description: Use when working inside an AgentKit Agent Capsule, especially after
 
 Use this first inside an AgentKit Agent Capsule.
 
+## Owner-To-Codex Contract
+
+The owner has already done the setup work by running `agentkit new <name>` and opening this folder in a coding agent. When they ask for an agent in natural language, that message is the brief.
+
+- Do not ask the owner to run a wizard, fill a form, or prepare `AGENT_SPEC.md`.
+- Route immediately to `skills/agentkit-build-agent/SKILL.md`.
+- You create or update `AGENT_SPEC.md`, prompts, tools, schema, evals, and docs as needed.
+- Use the CLI for validation and deployment, not for business inference.
+
+## Proactive Builder Contract
+
+Do not stop at "the prompt was edited." For every meaningful requirement in the owner's brief or `AGENT_SPEC.md`, decide which artifact must enforce it:
+
+- behavior or tone: `prompts/instructions.md`;
+- action, live data, or external write: `tools/` plus `agentkit.config.ts`;
+- durable records: schema/migration, tool, config registration, prompt guidance, direct tool check, and eval;
+- privacy, confirmation, business hours, dates, money, safety, or client data: at least one eval or deterministic check;
+- production or integration dependency: deploy/readiness check and safe fixture or fake path.
+
+If a real conversation reveals a bug or risky behavior, convert it into a regression eval before or alongside the fix.
+
 ## Start
 
 1. Treat the directory containing `agentkit.config.ts` as the capsule root.

package/src/templates/skills/agentkit-database/SKILL.md

@@ -7,6 +7,17 @@ description: Use when adding AgentKit-managed database tables, editing schema.sq
 
 Use this when a capsule owns durable application records.
 
+## Complete Database Tool Slice
+
+When the owner asks the agent to save or update records, do not stop after adding a table. Ship the whole slice:
+
+1. Add or update `schema.sql`; for production-shaped evolution, add an ordered `migrations/*.sql` file too.
+2. Add a `defineTool` under `tools/` that uses `ctx.db`.
+3. Register the tool in `agentkit.config.ts`.
+4. Update `prompts/instructions.md` so the agent knows when to collect fields, confirm writes, and call the tool.
+5. Add or update an eval for the user flow that should persist the record.
+6. Run `db migrate`, a direct tool check, `typecheck`, and `eval`.
+
 ## Rules
 
 - Put the first idempotent bootstrap schema in `schema.sql`.

package/src/templates/skills/agentkit-deploy/SKILL.md

@@ -47,4 +47,6 @@ Open the printed `Chat:` URL and report it to the owner.
 
 ## Production Handoff
 
+`npm run agentkit -- deploy` prints a production handoff after a successful deploy. Use it as the source of truth for the deploy URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and next recommended command.
+
 Report changed files, required env/secret names, database schema changes, deploy order, smoke checks, rollback concerns, and whether the provider was still `test/fake`.

package/src/templates/skills/agentkit-evals/SKILL.md

@@ -7,6 +7,8 @@ description: Use when adding, editing, or running AgentKit eval files, including
 
 Use evals after chat works and before claiming behavior is stable.
 
+`npm run eval` uses temporary local SQLite storage for eval execution. Eval conversations and tool calls do not write to the normal `.agentkit/agentkit.db`, so evals can run while local chat or `npm run dev` is using the development database.
+
 ## Workflow
 
 1. Create or edit `evals/<name>.eval.ts`.
@@ -21,6 +23,19 @@ Use evals after chat works and before claiming behavior is stable.
 10. Do not put secrets or real client PII in evals.
 11. For tools that write externally, delete, charge money, send email, or call real customer systems, branch on `ctx.runtime.environment === "eval"` inside the registered tool.
 
+## What To Test
+
+Create evals proactively from the brief and spec. Common high-value evals:
+
+- identity and scope: the agent says who it is and refuses out-of-scope work;
+- intake: required fields such as name, phone, email, account id, date, or budget are collected before action;
+- confirmation: external writes, deletes, messages, charges, and bookings do not happen before explicit confirmation;
+- privacy: raw tool output, full calendars, internal IDs, retrieval metadata, secrets, and stack traces are not shown to the client;
+- timezone and schedule: eval `now` is frozen, `timeZone` is honored, and tool payloads use the intended local date/time;
+- defaults and constraints: durations, allowed hours, allowed regions, max/min values, and business rules are asserted;
+- unhappy paths: rate limits, timeouts, missing auth, unavailable slots, empty results, and validation errors produce safe user-facing responses;
+- regression: every real conversation bug gets the smallest eval that would have failed before the fix.
+
 ## Assertion Shape
 
 Use this shape first:

package/src/templates/skills/agentkit-improve/SKILL.md

@@ -38,13 +38,23 @@ npm run agentkit -- improve collect --deploy --conversation-id <conversation-id>
 .agentkit/improve/<run>/traces/
 ```
 
-3. Generate regression evals:
+3. Before patching, identify the smallest testable lesson from each relevant trace:
+
+- Did the agent miss a required field?
+- Did it expose raw tool output, a full schedule, an internal id, or a technical error?
+- Did it write externally without confirmation?
+- Did it use the wrong timezone, duration, business hour, or availability assumption?
+- Did a tool error or provider limit produce a bad client response?
+
+4. Generate regression evals:
 
 ```sh
 npm run agentkit -- improve evals .agentkit/improve/<run>
 ```
 
-4. Patch the capsule. Likely files:
+5. Review or rewrite generated evals so they assert the behavior, not brittle transcript wording. If the bug involved a tool call, assert the persisted tool call input or absence of the unsafe call.
+
+6. Patch the capsule. Likely files:
 
 ```txt
 prompts/instructions.md
@@ -54,7 +64,7 @@ knowledge/
 evals/
 ```
 
-5. Verify:
+7. Verify:
 
 ```sh
 npm run typecheck
@@ -63,7 +73,7 @@ npm run eval
 npm run agentkit -- replay .agentkit/improve/<run> --against local
 ```
 
-6. Deploy only after local evals and replay pass:
+8. Deploy only after local evals and replay pass:
 
 ```sh
 npm run agentkit -- deploy --smoke "hello"

package/src/templates/skills/agentkit-integrations/SKILL.md

@@ -44,6 +44,18 @@ For Google Calendar, do not configure create-only access. Include `GOOGLECALENDA
 
 Managed Composio write actions require tool input `confirmed: true` by default. Set it only after the owner/user confirms the exact external change. Use `confirmExternalWrites: false` only when the capsule implements an equivalent confirmation guard elsewhere.
 
+## Testability
+
+Do not rely on the real connected app for ordinary evals. When adding an integration, also add deterministic coverage for:
+
+- the safe path, such as free/busy before calendar create;
+- missing confirmation before an external write;
+- provider errors such as 429, timeout, missing auth, empty result, or unavailable slot;
+- privacy rules, such as not showing a full calendar or raw provider payload to the client;
+- payload invariants, such as timezone conversion, duration, recipients, or record ids.
+
+Use eval-safe branches inside capsule tools, local fixtures, or `test/fake` behavior when the hosted integration cannot run locally without touching the real provider.
+
 ## Commands
 
 ```sh
@@ -54,6 +66,16 @@ npm run agentkit -- integrations status --toolkit googlecalendar
 npm run agentkit -- integrations connect composio --toolkit gmail
 ```
 
+`integrations connect composio` requires a hosted deploy because the connect link is deploy-scoped. After declaring `composioManaged(...)`, tell the owner the sequence is:
+
+```sh
+npm run agentkit -- deploy doctor
+npm run agentkit -- deploy
+npm run agentkit -- integrations connect composio --toolkit googlecalendar
+```
+
+The deploy handoff prints the connect command for each configured toolkit.
+
 ## Rules
 
 - Do not add `COMPOSIO_API_KEY` to `.env.schema` for managed Composio.

package/src/templates/skills/agentkit-provider/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentkit-provider
-description: Use when switching an AgentKit capsule from the deterministic test/fake provider to a real Pi-backed provider such as OpenAI, Anthropic, or OpenRouter, or when verifying provider secrets and model behavior.
+description: Use when switching an AgentKit capsule from the deterministic test/fake provider to a real Pi-backed provider such as OpenAI, Anthropic, OpenRouter, OpenCode Zen, or OpenCode Go, or when verifying provider secrets and model behavior.
 ---
 
 # AgentKit Provider
@@ -9,7 +9,7 @@ Use this when `test/fake` is no longer enough.
 
 ## Rule
 
-Do not choose a real provider automatically. Ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider.
+Do not choose a real provider automatically. Ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider.
 
 ## Workflow
 
@@ -44,6 +44,24 @@ secrets: ["OPENROUTER_API_KEY"],
 
 Prefer OpenRouter model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If a raw OpenRouter id is newer than Pi's registry, AgentKit passes it through to OpenRouter with conservative unknown-model metadata; OpenRouter can still reject invalid, inaccessible, or unsupported models.
 
+OpenCode Zen:
+
+```ts
+provider: { name: "opencode", model: "big-pickle" },
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`.
+
+OpenCode Go:
+
+```ts
+provider: { name: "opencode-go", model: "deepseek-v4-flash" },
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`.
+
 ## Verification
 
 ```sh

package/src/templates/skills/agentkit-tools/SKILL.md

@@ -16,6 +16,8 @@ Use this when the agent needs code, an API, live data, a write, or an external a
 5. Keep secret names in `.env.schema`; values stay in ignored `.env` or hosted managed secrets.
 6. Use `ctx.clock` for date-sensitive tool logic instead of calling `new Date()` directly.
 7. Add eval guards for destructive or external side effects.
+8. Add deterministic fixtures, fake branches, or direct tool inputs for important success and failure paths.
+9. Add evals that assert the tool is called with safe inputs, or not called when confirmation/intake is missing.
 
 ## Examples