contextdevkit 1.8.0

package/templates/contextkit/squads/agent-forge/templates/agent-package/prompts/system.google.md

@@ -0,0 +1,19 @@
+<!--
+  GENERATED in Fase 1 by `prompt-engineer` from system.canonical.md. Do not hand-edit.
+  Google (Gemini): goes in the `systemInstruction` param. Markdown + few-shot works
+  well. Remember safetySettings are configured on the REQUEST, not here.
+-->
+# Role
+{{ROLE_ONE_LINE}}
+
+## Context
+{{STABLE_BACKGROUND}}
+
+## Rules
+- {{AFFIRMATIVE_RULE_1}}
+
+## Output
+{{OUTPUT_CONTRACT}}
+
+## Examples (few-shot)
+{{FEW_SHOT}}

package/templates/contextkit/squads/agent-forge/templates/agent-package/prompts/system.ollama.md

@@ -0,0 +1,21 @@
+<!--
+  GENERATED in Fase 1 by `prompt-engineer` from system.canonical.md. Do not hand-edit.
+  Self-hosted (Ollama/vLLM): the chat template VARIES BY MODEL (Llama 3 vs Mistral vs
+  Qwen). Prefer the API that applies the model's chat_template automatically; otherwise
+  render the exact template for the target model. Tool-use reliability is below cloud —
+  lean on the eval golden set.
+-->
+# Role
+{{ROLE_ONE_LINE}}
+
+## Context
+{{STABLE_BACKGROUND}}
+
+## Rules
+- {{AFFIRMATIVE_RULE_1}}
+
+## Output
+{{OUTPUT_CONTRACT}}
+
+## Examples
+{{FEW_SHOT}}

package/templates/contextkit/squads/agent-forge/templates/agent-package/prompts/system.openai.md

@@ -0,0 +1,20 @@
+<!--
+  GENERATED in Fase 1 by `prompt-engineer` from system.canonical.md. Do not hand-edit.
+  OpenAI (GPT): this becomes the first `system` message. Use clear delimiters. Prefer
+  native response_format: json_schema (strict) for structured output. o-series models
+  take no system message — fold into the first user turn + set reasoning_effort.
+-->
+# Role
+{{ROLE_ONE_LINE}}
+
+## Context
+{{STABLE_BACKGROUND}}
+
+## Rules
+- {{AFFIRMATIVE_RULE_1}}
+
+## Output
+{{OUTPUT_CONTRACT}}
+
+## Examples
+{{FEW_SHOT}}

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/config.yaml

@@ -0,0 +1,17 @@
+# RAG config. This whole rag/ folder is present ONLY if the agent needs retrieval
+# (manifest spec.capabilities.rag: true). Generated by rag-designer.
+embedding:
+  # multilingual (PT-BR / multi) → multilingual-e5 | bge-m3
+  # english-only → text-embedding-3-large | voyage-3
+  model: {{multilingual-e5}}
+  dimensions: {{1024}}
+
+index:
+  backend: {{faiss|pgvector|qdrant|pinecone}}
+  metric: cosine
+
+retrieval:
+  top_k: {{8}}
+  min_score: {{0.30}}          # drop chunks below this
+  hybrid_search: {{true}}      # BM25 + vector
+  rerank: {{true}}             # see retrieval/rerank.config.yaml

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/index/.gitkeep

@@ -0,0 +1,3 @@
+# The vector index is BUILT BY THE CLIENT from rag/ingestion/sources.yaml.
+# It is never embarked in the Agent Package (size + freshness). This dir stays empty
+# in the package; the client populates it at deploy time.

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/ingestion/chunker.config.yaml

@@ -0,0 +1,6 @@
+# How source documents are split before embedding.
+strategy: {{recursive|semantic|fixed}}
+chunk_size_tokens: {{512}}
+chunk_overlap_tokens: {{64}}
+respect_boundaries: [heading, paragraph]   # avoid splitting mid-section
+keep_metadata: [source, section, page]

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/ingestion/sources.yaml

@@ -0,0 +1,8 @@
+# Where the knowledge content comes from. READ-ONLY specs — the index is built by the
+# client (see ../index/), never embarked in the package.
+sources:
+  - id: {{source_id}}
+    type: {{filesystem|url|s3|gcs|db}}
+    location: {{path or uri}}
+    include: ["**/*.{md,pdf,txt}"]
+    refresh: {{manual|daily|weekly}}

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/retrieval/query-template.md

@@ -0,0 +1,16 @@
+<!-- How the user query is turned into a retrieval query + how context is injected. -->
+
+## Retrieval query
+{{TRANSFORM of the user input into a search query — e.g. expand acronyms, strip PII}}
+
+## Context injection
+Inject the top-k chunks as:
+
+```
+<context>
+{{retrieved_chunks}}
+</context>
+```
+
+Instruct the model to answer ONLY from `<context>` and to say when the answer is not
+present (faithfulness > fluency).

package/templates/contextkit/squads/agent-forge/templates/agent-package/rag/retrieval/rerank.config.yaml

@@ -0,0 +1,6 @@
+# Optional reranker — re-scores the top_k from the vector store before injection.
+# Remove this file if config.yaml retrieval.rerank is false.
+enabled: {{true}}
+model: {{bge-reranker-v2-m3|cohere-rerank-3}}
+top_n_after_rerank: {{4}}
+min_score: {{0.50}}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/adapters/anthropic.tools.json

@@ -0,0 +1,11 @@
+{
+  "_generated": "Fase 1 by tool-designer from ../schemas.canonical.json. Do not hand-edit.",
+  "_format": "Anthropic `tools` array: each tool = { name, description, input_schema }. Force a tool with tool_choice: { type: 'tool', name: '...' }.",
+  "tools": [
+    {
+      "name": "{{tool_name}}",
+      "description": "{{from canonical}}",
+      "input_schema": { "type": "object", "properties": {}, "required": [] }
+    }
+  ]
+}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/adapters/deepseek.tools.json

@@ -0,0 +1,14 @@
+{
+  "_generated": "Fase 1 by tool-designer from ../schemas.canonical.json. Do not hand-edit.",
+  "_format": "DeepSeek is OpenAI-compatible — same shape as openai.tools.json (type 'function').",
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "{{tool_name}}",
+        "description": "{{from canonical}}",
+        "parameters": { "type": "object", "properties": {}, "required": [] }
+      }
+    }
+  ]
+}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/adapters/google.tools.json

@@ -0,0 +1,11 @@
+{
+  "_generated": "Fase 1 by tool-designer from ../schemas.canonical.json. Do not hand-edit.",
+  "_format": "Gemini `tools[].functionDeclarations[]`: { name, description, parameters }. parameters is a JSON-Schema SUBSET — not every field is supported; the generator down-converts.",
+  "functionDeclarations": [
+    {
+      "name": "{{tool_name}}",
+      "description": "{{from canonical}}",
+      "parameters": { "type": "object", "properties": {}, "required": [] }
+    }
+  ]
+}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/adapters/ollama.tools.json

@@ -0,0 +1,14 @@
+{
+  "_generated": "Fase 1 by tool-designer from ../schemas.canonical.json. Do not hand-edit.",
+  "_format": "Self-hosted via OpenAI-compatible endpoint — same shape as openai.tools.json. Native function calling on Llama 3.x / Mistral; reliability below cloud, so eval golden is critical.",
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "{{tool_name}}",
+        "description": "{{from canonical}}",
+        "parameters": { "type": "object", "properties": {}, "required": [] }
+      }
+    }
+  ]
+}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/adapters/openai.tools.json

@@ -0,0 +1,14 @@
+{
+  "_generated": "Fase 1 by tool-designer from ../schemas.canonical.json. Do not hand-edit.",
+  "_format": "OpenAI `tools` array of type 'function': { type, function: { name, description, parameters } }.",
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "{{tool_name}}",
+        "description": "{{from canonical}}",
+        "parameters": { "type": "object", "properties": {}, "required": [] }
+      }
+    }
+  ]
+}

package/templates/contextkit/squads/agent-forge/templates/agent-package/tools/schemas.canonical.json

@@ -0,0 +1,25 @@
+{
+  "_note": "CANONICAL tool schemas — the source of truth. tool-designer generates the per-provider adapters under tools/adapters/ from this. Every tool description follows: what it does / when to use / when NOT to use / one example. Keep input_schema strict.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "{{tool_name}}": {
+    "description": "WHAT: {{what it does}}. WHEN: {{when to call}}. WHEN NOT: {{when to avoid}}. EXAMPLE: {{one concrete example}}.",
+    "idempotent": true,
+    "input_schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["{{required_field}}"],
+      "properties": {
+        "{{required_field}}": { "type": "string", "description": "{{what it is}}" }
+      }
+    },
+    "error_format": {
+      "type": "object",
+      "description": "Actionable error the model can recover from.",
+      "properties": {
+        "code": { "type": "string" },
+        "message": { "type": "string" },
+        "retryable": { "type": "boolean" }
+      }
+    }
+  }
+}

package/templates/contextkit/starters/tanstack/README.md

@@ -0,0 +1,86 @@
+# TanStack starter
+
+> Minimal wiring scaffold copied by `/aidevtool-from0` when the chosen stack
+> is **TanStack**. After copy, this becomes your project — there is no upgrade
+> path from the kit.
+
+## What this gives you
+
+- **TanStack Router** (file-based, type-safe) wired through
+  `@tanstack/router-plugin` for Vite. The plugin generates
+  `src/routeTree.gen.ts` from `src/routes/**` on every dev/build — that file
+  is gitignored.
+- **TanStack Query** with a single `QueryClient` provider mounted in
+  `src/main.tsx`. The Router is given `{ queryClient }` as `context`, so route
+  loaders can call `context.queryClient.ensureQueryData(queryOptions)`.
+- **React 19** + **Vite 6** + **TypeScript** (`strict`, `noUncheckedIndexedAccess`,
+  `verbatimModuleSyntax`).
+
+## What this does NOT give you (by design — ADR-0017)
+
+- No invented domain (no `User`, `Product`, `Post` — just one placeholder route).
+- No CSS framework / design system — the placeholder is plain HTML.
+- No backend client, no auth, no DB. Those are separate decisions for separate
+  ADRs in your project.
+- No example query — the conventions are in the playbook; write your first
+  query against your real backend.
+
+## First steps after copy
+
+```bash
+npm install
+npm run dev
+```
+
+Then:
+
+1. **Replace `src/routes/index.tsx`** with your first real route.
+2. **Write your first query** following the `queryOptions` pattern from the
+   playbook — never `useState` for server data, never an inline `queryKey`
+   string. Co-locate the `queryOptions` factory next to the feature, not in a
+   global file.
+3. **Open an ADR in your project** (`/new-adr "<your-first-feature>"`) before
+   the first non-trivial route — type-safe Router params are a contract;
+   contracts deserve ADRs.
+
+## Conventions you inherit from the kit
+
+The full conventions block lives in
+[`contextkit/workflows/playbooks/tanstack.md`](../../workflows/playbooks/tanstack.md)
+and was copied into your project's `CLAUDE.md` under "Stack" when this starter
+was applied. The short version:
+
+- Server state in Query, never `useState`.
+- `queryOptions` is the unit of reuse.
+- Cache keys are arrays, hierarchical, stable.
+- Router params via `Route.useParams()` — never a generic hook.
+- `staleTime` is deliberate; the default of `0` is correct only for dashboards.
+- Mutations invalidate the **smallest viable** key, with a one-line comment
+  naming the invariant the invalidation preserves.
+
+## Upgrading to TanStack Start (SSR / full-stack)
+
+This starter intentionally **omits** TanStack Start to avoid pinning to a
+moving target. When you decide you need SSR + a sanctioned server story:
+
+1. Read the current TanStack Start docs (the API has been evolving — verify
+   before trusting any guide).
+2. Open an ADR in your project capturing the migration: routing model staying,
+   build tool changing from Vite to vinxi, deployment target.
+3. The Router conventions you already follow carry over unchanged — only the
+   build/runtime swap.
+
+## Freshness
+
+Versions in `package.json` were chosen at the time the kit shipped the
+starter. Before relying on a specific TanStack API:
+
+```bash
+npm outdated
+npm view @tanstack/react-router version
+npm view @tanstack/react-query version
+```
+
+If a major has shipped since the kit's starter was authored, the playbook's
+"Freshness" section in the kit repo is the place to refresh — not your
+project. Your project owns its own pinned versions from the moment of copy.

package/templates/contextkit/starters/tanstack/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>TanStack starter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/contextkit/starters/tanstack/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "tanstack-starter",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.62.0",
+    "@tanstack/react-router": "^1.95.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/router-plugin": "^1.95.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/templates/contextkit/starters/tanstack/src/main.tsx

@@ -0,0 +1,40 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { RouterProvider, createRouter } from '@tanstack/react-router';
+
+import { routeTree } from './routeTree.gen';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 0,
+      retry: 1,
+    },
+  },
+});
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  context: { queryClient },
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}
+
+const rootEl = document.getElementById('root');
+if (!rootEl) {
+  throw new Error('Root element #root missing in index.html');
+}
+
+createRoot(rootEl).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  </StrictMode>,
+);

package/templates/contextkit/starters/tanstack/src/router.tsx

@@ -0,0 +1,12 @@
+/**
+ * Re-exports the Router context type so consumers (loaders, route components)
+ * can type-check against it without reaching into `main.tsx`.
+ *
+ * The actual `createRouter` call lives in `main.tsx` because it depends on the
+ * generated `routeTree.gen.ts` (produced by `@tanstack/router-plugin`).
+ */
+import type { QueryClient } from '@tanstack/react-query';
+
+export interface RouterContext {
+  queryClient: QueryClient;
+}

package/templates/contextkit/starters/tanstack/src/routes/__root.tsx

@@ -0,0 +1,10 @@
+import { Outlet, createRootRouteWithContext } from '@tanstack/react-router';
+import type { RouterContext } from '../router';
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  component: RootLayout,
+});
+
+function RootLayout() {
+  return <Outlet />;
+}

package/templates/contextkit/starters/tanstack/src/routes/index.tsx

@@ -0,0 +1,17 @@
+import { createFileRoute } from '@tanstack/react-router';
+
+export const Route = createFileRoute('/')({
+  component: IndexRoute,
+});
+
+function IndexRoute() {
+  return (
+    <main>
+      <h1>TanStack starter</h1>
+      <p>
+        Wiring only — no invented domain. Replace this placeholder with your
+        first real route. See <code>README.md</code> for the conventions.
+      </p>
+    </main>
+  );
+}

package/templates/contextkit/starters/tanstack/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "noEmit": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/contextkit/starters/tanstack/vite.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { TanStackRouterVite } from '@tanstack/router-plugin/vite';
+
+export default defineConfig({
+  plugins: [
+    TanStackRouterVite({ target: 'react', autoCodeSplitting: true }),
+    react(),
+  ],
+});

package/templates/contextkit/tools/scripts/adr-digest-core.mjs

@@ -0,0 +1,42 @@
+/**
+ * ADR digest core — pure parsing of an ADR file into a catalog record. [ADR-0027]
+ *
+ * Turns a full ADR (~100–120 lines) into one catalog line (number · status ·
+ * title · one-line decision) so "read the relevant ADR(s)" becomes "scan the
+ * catalog, open at most one". Shared by `adr-digest.mjs` (the CLI) and
+ * `context-pack.mjs` (the start-of-work bundle). No I/O — callers pass the text.
+ */
+import { firstParagraph, metaValue, section } from '../../runtime/hooks/md-extract.mjs';
+
+/** `<NNNN>-<slug>.md` — the ADR file shape (`_TEMPLATE.md` is excluded by callers). */
+export const ADR_FILENAME_RE = /^(\d{4})-([a-z0-9._-]+)\.md$/;
+
+/**
+ * Parses one ADR markdown string into a catalog record.
+ * @returns {{ok:boolean, number:string, title:string, status:string, decision:string, slug:string}}
+ */
+export function parseAdr(text, filename = '') {
+  const safe = String(text || '').replace(/^/, '');
+  const lines = safe.split('\n');
+  const fm = ADR_FILENAME_RE.exec(filename) || [];
+  const number = fm[1] || '';
+  const rawTitle = (lines.find((l) => l.startsWith('# ')) || '').slice(2).trim();
+  const title = rawTitle.replace(/^ADR-\d{4}\s*[:—-]\s*/i, '').trim();
+  // Status keyword only (drop the parenthetical / HTML-comment tail).
+  const status = (metaValue(lines, 'Status').split(/[\s(<]/)[0] || '').trim();
+  const decision = firstParagraph(section(lines, 'decision'), 140);
+  // `ok` means we extracted a title/decision — a structureless file shows the
+  // `?` "open the file" marker rather than a misleadingly blank catalog line.
+  const ok = Boolean(rawTitle || decision);
+  return { ok, number: number || '????', title, status, decision, slug: fm[2] || '' };
+}
+
+/** One catalog line for a record, or `null` when unparseable (rule 8: a `?`, never dropped). */
+export function renderCatalogLine(record) {
+  if (!record) return null;
+  const number = record.number || '????';
+  if (!record.ok) return `- **${number}** · ? · (unparseable — open the file)`;
+  const status = record.status || '?';
+  const decision = record.decision ? ` — ${record.decision}` : '';
+  return `- **${number}** · ${status} · ${record.title}${decision}`;
+}

package/templates/contextkit/tools/scripts/adr-digest.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * ADR digest — compact catalog of Architecture Decision Records. [ADR-0027]
+ *
+ * Replaces "read 3–5 ADRs to find the relevant one" (~110 lines each) with a
+ * ~1-line-per-ADR catalog (number · status · title · one-line decision), with an
+ * optional keyword filter. Read the catalog, then open at most ONE full ADR.
+ * Read-only, zero third-party deps. Parsing is single-sourced in `adr-digest-core.mjs`.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/adr-digest.mjs                 # full catalog (human)
+ *   node contextkit/tools/scripts/adr-digest.mjs --search token  # only matching ADRs
+ *   node contextkit/tools/scripts/adr-digest.mjs --last 5        # the 5 most recent
+ *   node contextkit/tools/scripts/adr-digest.mjs --json
+ */
+import { readFile, readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+import { ADR_FILENAME_RE, parseAdr, renderCatalogLine } from './adr-digest-core.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const args = process.argv.slice(2);
+const flag = (name) => args.includes(name);
+const opt = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const readSafe = (abs) => readFile(abs, 'utf-8').catch(() => null);
+
+/** ADR filenames (excluding `_TEMPLATE.md`), newest first (zero-padded numeric sort). */
+async function listAdrFiles() {
+  let files = [];
+  try {
+    files = await readdir(P.decisions);
+  } catch {
+    return [];
+  }
+  return files.filter((f) => ADR_FILENAME_RE.test(f) && f !== '_TEMPLATE.md').sort().reverse();
+}
+
+async function main() {
+  const search = opt('--search');
+  const limit = Number.parseInt(opt('--last') || '0', 10) || 0;
+
+  const records = [];
+  for (const name of await listAdrFiles()) {
+    const text = await readSafe(resolve(P.decisions, name));
+    if (text !== null) records.push(parseAdr(text, name));
+  }
+
+  let selected = records;
+  if (search) {
+    const query = search.toLowerCase();
+    selected = records.filter((r) =>
+      `${r.number} ${r.title} ${r.decision} ${r.status} ${r.slug}`.toLowerCase().includes(query),
+    );
+  }
+  if (limit > 0) selected = selected.slice(0, limit);
+
+  if (flag('--json')) {
+    process.stdout.write(JSON.stringify({ count: selected.length, adrs: selected }, null, 2) + '\n');
+    return;
+  }
+  if (selected.length === 0) {
+    console.log(search ? `No ADRs match "${search}".` : 'No ADRs found (contextkit/memory/decisions/).');
+    return;
+  }
+  console.log(`\n🏛️  ADR catalog — ${selected.length} decision(s)${search ? ` matching "${search}"` : ''}, newest first\n`);
+  console.log(selected.map(renderCatalogLine).join('\n'));
+  console.log('\nOpen a full ADR in contextkit/memory/decisions/ only when you need its full context.');
+}
+
+main().catch((err) => {
+  console.error('❌ adr-digest failed:', err?.message ?? err);
+  process.exit(1);
+});