@andreprado/agentkit 0.1.0-alpha.5 → 0.1.0-alpha.7

package/src/runtime/tools.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, JsonSchema, ToolContext, ToolRuntimeContext } from "../index";
+import type { AgentTool, JsonSchema, ToolContext, ToolRenderResult, ToolRuntimeContext } from "../index";
 import type { SqliteAgentKitStore } from "../storage/sqlite";
 import { createLocalDatabaseRunner } from "./database";
 import { AgentKitError } from "./errors";
@@ -14,6 +14,7 @@ export type ToolCallResult = {
   visibility: "user" | "internal";
   input: unknown;
   output: unknown;
+  rendered?: ToolRenderResult;
 };
 
 export type ToolRuntime = {
@@ -97,10 +98,13 @@ async function executeToolCall(
       validateSchema(output, tool.outputSchema, `tool "${tool.name}" output`);
     }
 
+    const rendered = renderToolOutput(tool, input, output, options.runtime);
+
     options.store.completeToolCall({
       toolCallId: toolCall.id,
       status: "completed",
       output,
+      rendered,
       secretValues,
     });
 
@@ -110,6 +114,7 @@ async function executeToolCall(
       visibility: tool.visibility ?? "user",
       input,
       output,
+      ...(rendered ? { rendered } : {}),
     };
   } catch (error) {
     const secretValues = collectConfiguredSecretValues(tool, options.env ?? process.env);
@@ -125,6 +130,121 @@ async function executeToolCall(
   }
 }
 
+function renderToolOutput(
+  tool: AgentTool,
+  input: unknown,
+  output: unknown,
+  runtime: ToolRuntimeContext,
+): ToolRenderResult | undefined {
+  if (!tool.render) {
+    return undefined;
+  }
+
+  const rendered = tool.render(output, {
+    input,
+    runtime,
+  });
+
+  if (typeof rendered === "string") {
+    return { text: rendered };
+  }
+
+  if (!isRecord(rendered) || typeof rendered.text !== "string" || rendered.text.trim().length === 0) {
+    throw new AgentKitError("tool_validation_error", `tool "${tool.name}" render must return a non-empty text string.`);
+  }
+
+  if (rendered.blocks !== undefined) {
+    if (!Array.isArray(rendered.blocks)) {
+      throw new AgentKitError("tool_validation_error", `tool "${tool.name}" render.blocks must be an array when provided.`);
+    }
+
+    for (const [index, block] of rendered.blocks.entries()) {
+      validateRenderBlock(block, `tool "${tool.name}" render.blocks[${index}]`);
+    }
+  }
+
+  return {
+    text: rendered.text,
+    ...(rendered.blocks ? { blocks: rendered.blocks } : {}),
+  };
+}
+
+function validateRenderBlock(block: unknown, label: string): void {
+  if (!isRecord(block)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an object.`);
+  }
+
+  if (block.type === "text") {
+    if (typeof block.text !== "string" || block.text.trim().length === 0) {
+      throw new AgentKitError("tool_validation_error", `${label}.text must be a non-empty string.`);
+    }
+    return;
+  }
+
+  if (block.type === "card") {
+    if (typeof block.title !== "string" || block.title.trim().length === 0) {
+      throw new AgentKitError("tool_validation_error", `${label}.title must be a non-empty string.`);
+    }
+
+    validateOptionalString(block.subtitle, `${label}.subtitle`);
+    validateRenderFields(block.fields, `${label}.fields`);
+    validateRenderActions(block.actions, `${label}.actions`);
+    return;
+  }
+
+  throw new AgentKitError("tool_validation_error", `${label}.type must be "text" or "card".`);
+}
+
+function validateRenderFields(value: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, field] of value.entries()) {
+    if (!isRecord(field)) {
+      throw new AgentKitError("tool_validation_error", `${label}[${index}] must be an object.`);
+    }
+
+    validateRequiredString(field.label, `${label}[${index}].label`);
+    validateRequiredString(field.value, `${label}[${index}].value`);
+  }
+}
+
+function validateRenderActions(value: unknown, label: string): void {
+  if (value === undefined) {
+    return;
+  }
+
+  if (!Array.isArray(value)) {
+    throw new AgentKitError("tool_validation_error", `${label} must be an array when provided.`);
+  }
+
+  for (const [index, action] of value.entries()) {
+    if (!isRecord(action)) {
+      throw new AgentKitError("tool_validation_error", `${label}[${index}] must be an object.`);
+    }
+
+    validateRequiredString(action.label, `${label}[${index}].label`);
+    validateOptionalString(action.href, `${label}[${index}].href`);
+  }
+}
+
+function validateRequiredString(value: unknown, label: string): void {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new AgentKitError("tool_validation_error", `${label} must be a non-empty string.`);
+  }
+}
+
+function validateOptionalString(value: unknown, label: string): void {
+  if (value !== undefined && typeof value !== "string") {
+    throw new AgentKitError("tool_validation_error", `${label} must be a string when provided.`);
+  }
+}
+
 function resolveToolSecrets(
   tool: AgentTool,
   env: Record<string, string | undefined>,

package/src/runtime/traces.ts

@@ -0,0 +1,41 @@
+import type { ConversationRecord, StoredRun, StoredToolCall } from "../storage/sqlite";
+import { openCapsuleStore } from "../storage/sqlite";
+import { loadAgentCapsule } from "./config";
+import { AgentKitError } from "./errors";
+
+export type ConversationTrace = ConversationRecord & {
+  runs: ConversationTraceRun[];
+};
+
+export type ConversationTraceRun = StoredRun & {
+  toolCalls: StoredToolCall[];
+};
+
+export async function getConversationTraceFromCwd(cwd: string, conversationId: string): Promise<ConversationTrace> {
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "Missing conversation id.");
+  }
+
+  const capsule = await loadAgentCapsule(cwd);
+  const store = await openCapsuleStore(capsule);
+
+  try {
+    const conversation = store.getConversation(conversationId);
+
+    if (!conversation) {
+      throw new AgentKitError("conversation_not_found", `Conversation "${conversationId}" was not found.`);
+    }
+
+    const runs = store.listRunsForConversation(conversation.id).map((run) => ({
+      ...run,
+      toolCalls: store.listToolCallsForRun(run.id),
+    }));
+
+    return {
+      ...conversation,
+      runs,
+    };
+  } finally {
+    store.close();
+  }
+}

package/src/storage/sqlite.ts

@@ -6,6 +6,7 @@ import type { DatabaseArgs, DatabaseResult, DatabaseRow, DatabaseStatement } fro
 import type { AgentMessageRole, ProviderRunResult } from "../providers";
 import type { LoadedAgentCapsule } from "../runtime/config";
 import { AgentKitError } from "../runtime/errors";
+import { KNOWLEDGE_MIGRATION_ID, KNOWLEDGE_SCHEMA_SQL } from "../runtime/knowledge/schema";
 
 export type ConversationSummary = {
   id: string;
@@ -41,12 +42,30 @@ export type StoredToolCall = {
   visibility: ToolCallVisibility;
   input: unknown;
   output: unknown;
+  rendered: unknown;
   status: ToolCallStatus;
   startedAt: string;
   completedAt: string | null;
   errorMessage: string | null;
 };
 
+export type StoredRun = {
+  id: string;
+  conversationId: string | null;
+  provider: string;
+  model: string;
+  status: RunStatus;
+  usage: {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    totalTokens: number | null;
+  };
+  startedAt: string;
+  completedAt: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
+};
+
 export type PersistedChatRun = {
   conversationId: string;
   runId: string;
@@ -153,6 +172,17 @@ const MIGRATIONS = [
         ADD COLUMN visibility TEXT NOT NULL DEFAULT 'user';
     `,
   },
+  {
+    id: KNOWLEDGE_MIGRATION_ID,
+    sql: KNOWLEDGE_SCHEMA_SQL,
+  },
+  {
+    id: "0007_add_tool_call_rendered",
+    sql: `
+      ALTER TABLE tool_calls
+        ADD COLUMN rendered_json TEXT;
+    `,
+  },
 ] as const;
 
 export async function openCapsuleStore(capsule: LoadedAgentCapsule): Promise<SqliteAgentKitStore> {
@@ -457,6 +487,7 @@ export class SqliteAgentKitStore {
     toolCallId: string;
     status: ToolCallStatus;
     output?: unknown;
+    rendered?: unknown;
     completedAt?: string;
     errorMessage?: string;
     secretValues?: string[];
@@ -469,6 +500,7 @@ export class SqliteAgentKitStore {
         SET
           status = $status,
           output_json = $outputJson,
+          rendered_json = $renderedJson,
           completed_at = $completedAt,
           error_message = $errorMessage
         WHERE id = $toolCallId
@@ -478,6 +510,7 @@ export class SqliteAgentKitStore {
           $toolCallId: input.toolCallId,
           $status: input.status,
           $outputJson: input.output === undefined ? null : serializeJson(input.output, input.secretValues),
+          $renderedJson: input.rendered === undefined ? null : serializeJson(input.rendered, input.secretValues),
           $completedAt: input.completedAt ?? new Date().toISOString(),
           $errorMessage: redactSecrets(input.errorMessage ?? null, input.secretValues),
         });
@@ -550,6 +583,35 @@ export class SqliteAgentKitStore {
     });
   }
 
+  listRunsForConversation(conversationId: string): StoredRun[] {
+    return this.sqlite(() => {
+      const rows = this.db
+        .prepare(
+          `
+          SELECT
+            id,
+            conversation_id,
+            provider,
+            model,
+            status,
+            input_tokens,
+            output_tokens,
+            total_tokens,
+            started_at,
+            completed_at,
+            error_code,
+            error_message
+          FROM runs
+          WHERE conversation_id = $conversationId
+          ORDER BY started_at ASC
+        `,
+        )
+        .all({ $conversationId: conversationId }) as SqliteRow[];
+
+      return rows.map(storedRunFromRow);
+    });
+  }
+
   listToolCallsForRun(runId: string): StoredToolCall[] {
     return this.sqlite(() => {
       const rows = this.db
@@ -563,6 +625,7 @@ export class SqliteAgentKitStore {
             visibility,
             input_json,
             output_json,
+            rendered_json,
             status,
             started_at,
             completed_at,
@@ -578,6 +641,54 @@ export class SqliteAgentKitStore {
     });
   }
 
+  applyApplicationMigrations(migrations: Array<{ id: string; sql: string }>): { applied: string[]; skipped: string[] } {
+    return this.sqlite(() => {
+      if (migrations.length === 0) {
+        return { applied: [], skipped: [] };
+      }
+
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS agentkit_app_migrations (
+          id TEXT PRIMARY KEY,
+          applied_at TEXT NOT NULL
+        )
+      `);
+
+      const applied = new Set(
+        (
+          this.db.prepare("SELECT id FROM agentkit_app_migrations").all() as Array<{
+            id: string;
+          }>
+        ).map((row) => row.id),
+      );
+      const result = {
+        applied: [] as string[],
+        skipped: [] as string[],
+      };
+
+      for (const migration of migrations) {
+        if (applied.has(migration.id)) {
+          result.skipped.push(migration.id);
+          continue;
+        }
+
+        const statements = splitSqlStatements(migration.sql);
+        this.transaction(() => {
+          for (const statement of statements) {
+            this.db.exec(statement);
+          }
+
+          this.db
+            .prepare("INSERT INTO agentkit_app_migrations (id, applied_at) VALUES ($id, $appliedAt)")
+            .run({ $id: migration.id, $appliedAt: new Date().toISOString() });
+        });
+        result.applied.push(migration.id);
+      }
+
+      return result;
+    });
+  }
+
   applyApplicationSchema(source: string): void {
     this.sqlite(() => {
       const statements = splitSqlStatements(source);
@@ -785,6 +896,31 @@ function storedMessageFromRow(row: SqliteRow): StoredMessage {
   };
 }
 
+function storedRunFromRow(row: SqliteRow): StoredRun {
+  const status = String(row.status);
+
+  if (status !== "running" && status !== "completed" && status !== "failed") {
+    throw new AgentKitError("storage_error", `Invalid stored run status "${status}".`);
+  }
+
+  return {
+    id: String(row.id),
+    conversationId: row.conversation_id === null ? null : String(row.conversation_id),
+    provider: String(row.provider),
+    model: String(row.model),
+    status,
+    usage: {
+      inputTokens: nullableNumber(row.input_tokens),
+      outputTokens: nullableNumber(row.output_tokens),
+      totalTokens: nullableNumber(row.total_tokens),
+    },
+    startedAt: String(row.started_at),
+    completedAt: row.completed_at === null ? null : String(row.completed_at),
+    errorCode: row.error_code === null ? null : String(row.error_code),
+    errorMessage: row.error_message === null ? null : String(row.error_message),
+  };
+}
+
 function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
   const status = String(row.status);
   const visibility = String(row.visibility);
@@ -805,6 +941,7 @@ function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
     visibility,
     input: parseStoredJson(row.input_json),
     output: row.output_json === null ? undefined : parseStoredJson(row.output_json),
+    rendered: row.rendered_json === null ? undefined : parseStoredJson(row.rendered_json),
     status,
     startedAt: String(row.started_at),
     completedAt: row.completed_at === null ? null : String(row.completed_at),
@@ -812,6 +949,10 @@ function storedToolCallFromRow(row: SqliteRow): StoredToolCall {
   };
 }
 
+function nullableNumber(value: unknown): number | null {
+  return value === null || value === undefined ? null : Number(value);
+}
+
 function parseStoredJson(value: unknown): unknown {
   if (typeof value !== "string") {
     return value;

package/src/templates/blank.ts

@@ -147,11 +147,13 @@ When the owner opens this folder in Codex, Claude Code, or another coding agent
 
 Start building immediately:
 
-- Read \`AGENTKIT.md\` and the full docs path from \`npm run agentkit -- docs full\`.
+- Start with \`skills/agentkit-capsule/SKILL.md\`, then use \`npm run agentkit -- docs llms\` as the docs router.
+- Create or update \`AGENT_SPEC.md\` from the owner's request with \`npm run agentkit -- spec init --brief "<owner request>"\`; the owner should not fill this file by hand before work starts.
 - Infer the first useful version from the owner's request.
 - 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.
+- 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.
@@ -162,6 +164,9 @@ Start building immediately:
 - \`npm run dev\`: run the local Agent Capsule runtime.
 - \`npm run chat -- --message "hello"\`: send one local chat message.
 - \`npm run eval\`: run agent evals.
+- \`npm run agentkit -- spec check\`: verify the local agent implementation contract exists.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: turn a real conversation into a regression eval.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspect messages, runs, tool calls, inputs, outputs, rendered output, and final responses.
 - \`npm run agentkit -- tool <name> --input fixtures/input.json\`: run one registered tool directly.
 - \`npm run agentkit -- db migrate\`: apply internal migrations and \`schema.sql\` locally.
 - \`npm run agentkit -- db reset --yes\`: recreate the local SQLite database and reapply schema.
@@ -170,7 +175,8 @@ Start building immediately:
 - \`npm run agentkit -- inspect\`: print machine-readable capsule state.
 - \`printf %s "$VALUE" | npm run agentkit -- env set <NAME> --stdin\`: write a local secret value to ignored \`.env\` without putting it in shell history.
 - \`npm run agentkit -- env list\`: list local secret names without printing values.
-- \`npm run agentkit -- docs full\`: print the full AgentKit contract path.
+- \`npm run agentkit -- docs llms\`: print the lightweight AgentKit docs router.
+- \`npm run agentkit -- docs full\`: print the full AgentKit contract path only when a skill asks for it.
 
 ## Testing With A UI
 
@@ -211,7 +217,7 @@ export const myTool = defineTool({
 
 Use \`ctx.db\` as the canonical helper. \`ctx.database\` and \`ctx.storage.sql\` are aliases. Use \`ctx.db.batch([...])\` for atomic writes; local tools can also use \`ctx.db.transaction(async (tx) => ...)\`. Do not import local database drivers or Node-only APIs in tools. AgentKit owns local and hosted database routing.
 
-\`schema.sql\` is an idempotent bootstrap file in v1. Use \`CREATE TABLE IF NOT EXISTS\`, \`CREATE INDEX IF NOT EXISTS\`, and safe additive changes. AgentKit does not run destructive schema changes or ordered \`migrations/*.sql\` automatically yet.
+\`schema.sql\` is an idempotent bootstrap file. Use \`CREATE TABLE IF NOT EXISTS\`, \`CREATE INDEX IF NOT EXISTS\`, and safe additive changes. Use ordered \`migrations/*.sql\` for production-shaped schema evolution; \`npm run agentkit -- db migrate\` applies unapplied local migrations before \`schema.sql\`.
 
 ## Hosted Deploy
 
@@ -251,8 +257,10 @@ Example owner request:
 Turn the request into a working local capsule:
 
 - Update \`prompts/instructions.md\` with domain-specific behavior, boundaries, intake questions, and escalation rules.
+- 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.
+- Use \`npm run agentkit -- sync init\` when the agent needs catalog sync, fixture seed data, or ordered migrations.
 - 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.
@@ -305,12 +313,14 @@ If you add a tool, also run a fake-provider tool smoke test:
 npm run agentkit -- tool tool_name --input '{}'
 \`\`\`
 
-For the full framework contract, read the path printed by:
+For the lightweight docs router, read the path printed by:
 
 \`\`\`sh
-npm run agentkit -- docs full
+npm run agentkit -- docs llms
 \`\`\`
 
+Read the full framework contract with \`npm run agentkit -- docs full\` only when a skill asks for it.
+
 ## Hosted Deploy
 
 This capsule is hosted-deploy ready by default.
@@ -343,6 +353,7 @@ Use AgentKit conventions when editing this project.
 - 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.
+- Start with \`skills/agentkit-capsule/SKILL.md\` when the task is not obvious.
 `,
       },
       {

package/src/templates/dentista.ts

@@ -857,6 +857,8 @@ 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.
+
 ## Regras de Produto
 
 - Persona: Clara, atendente humana, simpática e objetiva.
@@ -885,9 +887,13 @@ A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibi
 - \`npm run agentkit -- tool consultar_consulta --input '{"email":"ana@example.com","telefone":"11999999999"}'\`: consultar uma consulta.
 - \`npm run agentkit -- tool alterar_consulta --input '{"email":"ana@example.com","telefone":"11999999999","novaData":"2099-01-06","novoHorario":"10:30","confirmadoPeloCliente":true}'\`: alterar uma consulta confirmada.
 - \`npm run eval\`: rodar evals.
+- \`npm run agentkit -- spec check\`: validar o contrato local da implementação.
+- \`npm run agentkit -- eval from-conversation <conversation-id>\`: transformar uma conversa real em eval de regressão.
+- \`npm run agentkit -- conversations trace <conversation-id>\`: inspecionar mensagens, runs, ferramentas, inputs, outputs, renderização e resposta final.
 - \`npm run dev\`: rodar a runtime local.
 - \`npm run agentkit -- inspect\`: imprimir o estado da cápsula.
-- \`npm run agentkit -- docs full\`: imprimir o contrato completo do AgentKit.
+- \`npm run agentkit -- docs llms\`: imprimir o roteador leve da documentação AgentKit.
+- \`npm run agentkit -- docs full\`: imprimir o contrato completo do AgentKit somente quando uma skill pedir.
 
 ## Teste Com UI
 
@@ -899,10 +905,12 @@ A Clara conversa com clientes, coleta nome, email e telefone, consulta disponibi
 ## 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\`.
+- 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.
+- Use \`npm run agentkit -- sync init\` quando a agente depender de catálogo externo, fixture local ou seed padronizado.
 - 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.
+- Quando a próxima ação não for óbvia, comece por \`skills/agentkit-capsule/SKILL.md\`.
 `,
       },
       {
@@ -931,6 +939,13 @@ npm run chat -- --message "Oi, quero marcar uma consulta."
 
 A cápsula começa com \`test/fake\`. Isso valida caminhos determinísticos, mas não prova qualidade de conversa natural.
 
+Se o dono pedir uma mudança grande, crie ou atualize o contrato de implementação:
+
+\`\`\`sh
+npm run agentkit -- spec init --brief "<pedido do dono>"
+npm run agentkit -- spec check
+\`\`\`
+
 ## Ferramentas
 
 - \`listar_horarios_disponiveis\`: recebe \`data\` em \`YYYY-MM-DD\` e retorna slots livres.

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

@@ -0,0 +1,51 @@
+---
+name: agentkit-build-agent
+description: Use when the owner gives a natural-language brief for a new or changed AgentKit agent and expects the coding agent to turn it into a working local capsule with prompts, tools, schema, evals, and verification.
+---
+
+# Build An AgentKit Agent
+
+Use this when the owner asks for an agent in plain language.
+
+## Workflow
+
+1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
+2. If `AGENT_SPEC.md` does not exist, create it from the owner's plain-language request with `npm run agentkit -- spec init --brief "<owner request>"`. If it exists, update it directly before changing behavior.
+3. Infer the first useful local version from the owner's brief and the spec. Do not ask the owner to fill a form.
+4. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
+5. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
+6. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
+7. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
+8. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+9. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Templates
+
+Use these only when they match the brief:
+
+- `templates/support-agent.instructions.md`
+- `templates/appointment-intake.instructions.md`
+- `templates/sales-qualifier.instructions.md`
+
+For prompt-only work, use `skills/agentkit-prompts/SKILL.md`.
+For database-backed tools, use `skills/agentkit-database/SKILL.md`.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run eval
+npm run agentkit -- spec check
+```
+
+If a tool was added:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+## Final Response
+
+Summarize the files changed, assumptions made, verification results, and whether the behavior was tested with `test/fake` or a real provider selected by the owner.

package/src/templates/skills/agentkit-build-agent/templates/appointment-intake.instructions.md

@@ -0,0 +1,20 @@
+You are an appointment and intake agent.
+
+Goal:
+- Collect the information needed to understand the request.
+- Offer available times only after checking availability through tools.
+- Confirm the exact date, time, name, and contact details before saving.
+
+Required intake:
+- Full name
+- Contact method
+- Reason for visit
+- Preferred date or time window
+- Any urgency or special constraints
+
+Rules:
+- Do not diagnose, promise outcomes, or provide emergency guidance beyond directing urgent cases to appropriate human or emergency support.
+- Do not create, change, or cancel an appointment without explicit user confirmation.
+- Do not invent availability.
+- Use the scheduling tools for availability and writes.
+

package/src/templates/skills/agentkit-build-agent/templates/sales-qualifier.instructions.md

@@ -0,0 +1,17 @@
+You are a sales qualification agent.
+
+Goal:
+- Understand the user's current situation, urgency, budget range, authority, and desired outcome.
+- Identify whether the lead is a fit for the configured offer.
+- Capture structured lead details through tools when available.
+
+Behavior:
+- Ask one focused question at a time.
+- Avoid pressure and exaggerated claims.
+- Be clear about what is known, unknown, and next.
+- Escalate to a human when the user asks for pricing exceptions, legal terms, procurement details, or custom commitments.
+
+Rules:
+- Do not invent pricing, discounts, case studies, or availability.
+- Do not expose internal lead scores or qualification labels.
+

package/src/templates/skills/agentkit-build-agent/templates/support-agent.instructions.md

@@ -0,0 +1,16 @@
+You are a focused support agent.
+
+Help users resolve the current issue clearly and efficiently.
+
+Behavior:
+- Ask for the minimum missing context needed to help.
+- Use tools when order, account, booking, or case status is needed.
+- Do not invent status, policy, price, or availability.
+- Explain next steps in plain language.
+- Escalate when the request involves billing disputes, safety, legal issues, account ownership, or anything outside the configured tools.
+
+Boundaries:
+- Do not claim to have changed anything unless a tool confirms it.
+- Do not expose internal tool output, IDs, scores, secrets, or logs.
+- If a tool fails, say what could not be verified and ask for a safe next step.
+