@sabaiway/agent-workflow-kit 14.15.1 → 14.16.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.16.0 — `/agent-workflow-kit jev` walks you to a first Jev request: what it is, what it is not, three steps and three prompts where it pays (AD-164)
+
+**A new read-only command, `/agent-workflow-kit jev`, recommends Jev (TypeSafe), a decision model that returns a typed
+answer with probabilities and a confidence.** It says what Jev is, why it pays in this workflow, and what it is not,
+quoting the vendor's own sentence that it is not a drop-in replacement for the LLM behind Claude Code, Cursor, opencode
+or Copilot, then the jagged edges of jev-1.13, the confidence caveat and the retention terms as the vendor states them,
+and its sources, each with the date it was read.
+
+- **Three steps to a first request.** The vendor skill: both install forms, Claude Code's and the other agents', in a
+  fixed order, and a mark: `found` names each of five skill paths that holds a `typesafe-ai/SKILL.md`, `not seen`
+  says a plugin install is not visible to a file check and names the checks that do see it. The key: where to get it,
+  `TYPESAFE_API_KEY` exported before the agent starts, never pasted into the chat, and a `set` / `not set` mark. The
+  first use: a prompt routing three tickets, then the vendor's smallest documented request and response with the
+  field and error meanings, quoted.
+- **Three prompts where it pays here:** the first real error in a red gate log, the decided-register entry a council
+  finding repeats, a paragraph that restates a named rule. Each tells the agent to keep every request within the vendor
+  limits (255 options, 64k tokens, 32k for the state plus the longest question), and each answer is a hint the agent
+  checks, never a gate; every candidate text goes to the vendor.
+- **Safe to run anywhere.** The guide writes nothing, opens no connection and never prints the key's value; `--json`
+  gives the same content as an envelope. The command appears in the command list, the skill description and the
+  README's Use table.
+
 ## 14.15.1 — a fenced empty read-only file no rule calls a mask stops the probe, so a concurrent sandboxed command no longer turns its masks into real paths (AD-163)
 
 **`/agent-workflow-kit sandbox-masks` now withholds its verdict on a possible leftover.** While one sandboxed

package/README.md

@@ -235,6 +235,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), and the **feature-spec adoption state** (`not adopted` / `adopting (N draft)` / `adopted (N live, M draft)` / `could not be read`, plus `declined` when recorded), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit now` | any time | **read-only** answer to where work stands in four blocks: **NOW** names every plan in flight, its phase, current and next step, and the tree evidence; **STEPS** gives every ledger row its evidence-derived status; **QUEUE** folds named rows under their full heading paths and calls position priority only in the judged backlog; **CAMPAIGN** shows the source-size practice figures and config state. The plan's own text never sets a status; a contradicted claim prints beside it. A block that cannot be derived is WITHHELD with its cause; NOW has two halves, plans and tree, each independently a value or WITHHELD, and NOW itself is WITHHELD only when both are. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit tier` | any time | **read-only** guide to the epic, story and task tier: what each level is, and the next step of the walk, with the command that runs it wherever a tool does. Never writes, never commits, never runs a subscription CLI. |
+| `/agent-workflow-kit jev` | any time | **read-only** guide to Jev (TypeSafe), a decision model: what it is, why it pays here, what it is not, the three steps to a first request and three prompts where it pays. Opens no connection and never prints the key. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents five named recipes for composing the carriers of a step — the bridges and the full-tool executor subagent — into plan → execute → review — **Solo / Reviewed / Council / Delegated / Subagent** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready, or when the executor vehicle is missing/unusable), and offers the choice. The activity/slot registry (six activities) is rendered by `procedures` and by `set-recipe --help`. The orchestrator runs it via the bridge skills or the executor vehicle and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution` / `routine` / `feedback-triage` / `epic` / `task`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + carrier readiness (`plan-authoring`: author, fold, review; default Reviewed when a backend is ready, Council on request; slot-aware incl. Delegated and Subagent) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same) — except `feedback-triage`, whose record-bound block carries the check with `--excerpts`, the resolved member lines (ready bridge commands, the ready lens brief, or explicit skipped members), and either the record round-table command for a bridge obligation or the no-receipt fact otherwise: the record is the artifact. `--override <slot>=<value>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<value>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend or a subagent, never commits**; hand-editing stays fully supported. |

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: agent-workflow-kit
-description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`.
+description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.15.1'
+  version: '14.16.0'
 ---
 
 # agent-workflow-kit
@@ -119,6 +119,10 @@ read-only — read `${CLAUDE_SKILL_DIR}/references/modes/now.md` before acting.
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/tier.md` before acting.
 
+### Mode: jev
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/jev.md` before acting.
+
 ### Mode: recommendations
 
 read-only — read `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md` before acting.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.15.1",
+  "version": "14.16.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.15.1",
+  "version": "14.16.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/jev.md

@@ -0,0 +1,21 @@
+### Mode: jev
+
+<!-- opt-in-capability: none — a read-only guide that configures nothing and calls no service -->
+
+Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the three steps to a first request and three prompts where it pays. It writes no file, opens no connection, never prints the key's value and never commits.
+
+Run `node ${CLAUDE_SKILL_DIR}/tools/jev-guide.mjs --dir <project> --json`.
+
+Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them. Keep every vendor-quoted text verbatim and in quotes, never translated or reflowed: the not-a-replacement sentence, the request, the response, the three field meanings and the four error meanings.
+
+Keep this order: the fixed text (WHAT, WHY HERE, NOT, SOURCES); then the three steps — the vendor skill with its install lines and its mark, the key with its mark, the first use; then the three prompts where it pays.
+
+Exit codes:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Rendered, or `--help` / `-h` as the whole invocation. |
+| 1 | Nothing rendered: a stat of the `--dir` does not report a directory; the cause is printed on stderr. |
+| 2 | Usage: an unknown argument, a `--dir` without a value, or `--help` / `-h` combined with anything. |
+
+**Invariants:** read-only · no network · the key's value never printed · compact user-language render with paths, commands and vendor quotes verbatim · `process.exitCode`, never `process.exit()`.

package/tools/commands.mjs

@@ -98,6 +98,13 @@ const CATALOG = [
     kind: READ_ONLY,
     oneLine: 'Explain the epic, story and task tier in plain words and name the next step of the walk, with the command that runs it wherever a tool does: the tier guide reads the disk alone.',
   },
+  {
+    key: 'jev',
+    invocation: invocationOf('jev'),
+    group: 'Inspect',
+    kind: READ_ONLY,
+    oneLine: 'Guide to Jev (TypeSafe), a decision model: what it is, why it pays here, the steps to a first request and three prompts where it pays; the guide opens no connection.',
+  },
   {
     key: 'backends',
     invocation: invocationOf('backends'),

package/tools/jev-guide.mjs

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// spec:jev-guide — docs/ai/specs/kit/jev-guide/index.md
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fail } from '../references/scripts/markdown-blocks.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const SCHEMA = 1;
+const KEY_VARIABLE = 'TYPESAFE_API_KEY';
+const SKILL_FILE = join('typesafe-ai', 'SKILL.md');
+const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the steps to a first request.
+
+Usage:
+  node jev-guide.mjs [--dir PROJECT] [--json]
+
+--dir   the project to read (default: the current directory).
+--json  the JSON envelope instead of the plain text.
+--help  answered only when it is the whole invocation.
+
+Exit codes: 0 rendered; 1 nothing rendered (a --dir that is not a directory); 2 usage.
+
+Reads only: the --dir, the home directory, the key variable's presence and five skill paths; no network.`;
+
+export const JEV_TEXT = Object.freeze([
+  'WHAT: Jev is a decision model: it takes a state and typed questions (choice, score, noul) and returns typed answers with probabilities and a confidence; it does not write text.',
+  'WHY HERE: a typed decision with a confidence instead of prompt-and-parse, in the user\'s own code and in the agent\'s scratch scripts.',
+  'Price and latency as the vendor states them: 0.042 dollars per million input tokens, output free; sub-second.',
+  'NOT: "Jev is not a drop-in replacement for the LLM behind Claude Code, Cursor, opencode, Copilot" (the vendor).',
+  'Jagged edge of jev-1.13: it reads literally.',
+  'Jagged edge of jev-1.13: no counting or arithmetic.',
+  'Jagged edge of jev-1.13: dates are read as text.',
+  'Jagged edge of jev-1.13: a large irrelevant state distracts it.',
+  'Jagged edge of jev-1.13: adversarial content can move the answer.',
+  'Jagged edge of jev-1.13: indirection lowers accuracy.',
+  'Jagged edge of jev-1.13: no structural invariants across questions.',
+  'Jagged edge of jev-1.13: no generation.',
+  'A confidence is not a correctness: start with conservative thresholds and test with your own data.',
+  'Retention as the vendor states it: zero data retention for enterprise customers only; a data processing agreement covers retention; a commitment not to train on user data.',
+  'SOURCES: docs.typesafe.ai for every Jev claim, read 2026-09-29.',
+  'The skills CLI README (github.com/vercel-labs/skills) for the skill paths, read 2026-09-29.',
+  'code.claude.com for claude plugin list, read 2026-09-29.',
+]);
+
+const INSTALL = [
+  'Claude Code:',
+  'claude plugin marketplace add typesafe-ai/skills',
+  'claude plugin install typesafe@typesafe-ai',
+  'Other agents:',
+  'npx skills add typesafe-ai/skills --skill typesafe-ai',
+];
+const NOT_SEEN = [
+  'skill: not seen at the five skill paths. A plugin install is not visible to a file check; check it by its owners:',
+  '/typesafe:typesafe-ai',
+  'in a Claude Code session (the vendor); ask any other agent to use the TypeSafe skill (the vendor); or run Claude Code\'s own',
+  'claude plugin list',
+];
+const KEY_TEXT = [
+  'Get a key at console.typesafe.ai and set it on every host the agent runs on.',
+  `Export ${KEY_VARIABLE}, the variable the vendor's SDKs read, in the shell the agent is started from: an agent inherits the environment its session started with, so export before starting it or restart it.`,
+  'Never paste the key into the chat or into a project file.',
+];
+const KEY_NOT_SET = `key: ${KEY_VARIABLE} not set. A host setting that filters the environment of the agent's commands also hides it.`;
+const FIRST_USE = [
+  'Give the agent this prompt: using the TypeSafe skill, route these three tickets to billing, technical or sales, one request each, and print each choice and confidence — "I was charged twice this month.", "The app crashes when I upload a file.", "Is there a discount for a yearly plan?".',
+  'The vendor\'s smallest documented request:',
+  'POST https://api.typesafe.ai/v1/systemone',
+  'Authorization: Bearer <API_KEY>',
+  '{"state":"Help! My payouts have been failing for 3 days.","model":"jev-latest","questions":{"department":{"type":"choice","instructions":"Which team should handle this?","criteria":{"billing":"Payments, invoicing, refunds","technical":"Bugs, outages, integrations","sales":"Pricing, upgrades, new accounts"}}}}',
+  'Its documented response:',
+  '{"model":"jev-1.13.0","answers":{"department":{"type":"choice","choice":"billing","probabilities":{"billing":0.88,"technical":0.12,"sales":0.0},"confidence":0.81}},"usage":{"input_tokens":318,"output_tokens":34}}',
+  'choice: "The highest-probability option."',
+  'probabilities: "Every option mapped to its probability (floats that sum to 1)."',
+  'confidence: "How certain the model is, derived from probabilities."',
+  '401: "Missing or invalid API key. Check the `Authorization` header."',
+  '422: "The request body failed validation — for example a missing required field or a malformed question. The body details the offending field."',
+  '429: "You have exceeded your rate limit. Back off and retry after a short delay."',
+  '529: "TypeSafe is temporarily overloaded. Retry after a short delay."',
+  'Success: three choices, each with a confidence.',
+];
+const LIMITS = 'Each request stays within the vendor limits: 255 options, 64k tokens, 32k for the state plus the longest question.';
+const HINT = 'The answer is a hint the agent checks, never a gate; every candidate text is sent to the vendor.';
+const PROMPTS = [
+  `(a) A red gate log: give each failing gate's own lines ids and ask one choice of the first real error per failing gate. ${LIMITS} ${HINT}`,
+  `(b) Council findings against the decided register: for each finding, ask a choice of the register id it repeats, or none. ${LIMITS} ${HINT}`,
+  `(c) Candidate paragraphs with ids: ask one noul each that the paragraph restates a named rule. ${LIMITS} ${HINT}`,
+];
+
+const valueAt = (argv, index, flag) => {
+  const value = argv[index + 1];
+  if (value === undefined || value === '' || value.startsWith('-')) throw fail(2, `${flag} takes a value`);
+  return value;
+};
+const parseArgv = (argv) => {
+  if (argv.includes('--help') || argv.includes('-h')) {
+    if (argv.length !== 1) throw fail(2, '--help is answered only when it is the whole invocation');
+    return { help: true };
+  }
+  return argv.reduce((parsed, arg, index) => {
+    if (parsed.skip) return { ...parsed, skip: false };
+    if (arg === '--dir') return { ...parsed, dir: valueAt(argv, index, arg), skip: true };
+    if (arg === '--json') return { ...parsed, json: true };
+    throw fail(2, `unknown argument "${arg}" — run with --help`);
+  }, { help: false, dir: '.', json: false, skip: false });
+};
+
+const statIs = (path, kind) => {
+  try { return kind === 'file' ? statSync(path).isFile() : statSync(path).isDirectory(); } catch { return false; }
+};
+const skillPaths = (dir, home) => [...new Set([join(dir, '.claude', 'skills'), join(dir, '.agents', 'skills'),
+  join(home, '.claude', 'skills'), join(home, '.codex', 'skills'), join(home, '.cursor', 'skills')]
+  .map((root) => join(root, SKILL_FILE)))];
+const keySet = (env) => typeof env[KEY_VARIABLE] === 'string' && env[KEY_VARIABLE].trim() !== '';
+
+const renderSteps = (found, set) => [
+  ['STEP 1 — the vendor skill', ...INSTALL,
+    ...(found.length ? found.map((path) => `skill: found at ${path}`) : NOT_SEEN)],
+  ['STEP 2 — the key', ...KEY_TEXT, set ? `key: ${KEY_VARIABLE} set.` : KEY_NOT_SET],
+  ['STEP 3 — the first use', ...FIRST_USE],
+];
+
+export const main = (argv, io = {}) => {
+  const log = io.log ?? console.log;
+  const error = io.error ?? console.error;
+  const parsed = (() => {
+    try { return parseArgv(argv); } catch (err) { error(err.message); return null; }
+  })();
+  if (parsed === null) return 2;
+  if (parsed.help) { log(HELP); return 0; }
+  const dir = resolve(io.cwd ?? process.cwd(), parsed.dir);
+  if (!statIs(dir, 'directory')) { error(`${dir} is not a directory`); return 1; }
+  const found = skillPaths(dir, io.home ?? homedir()).filter((path) => statIs(path, 'file'));
+  const set = keySet(io.env ?? process.env);
+  const steps = renderSteps(found, set);
+  log(parsed.json
+    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found }, key: { set },
+      steps, prompts: PROMPTS }, null, 2)
+    : [...JEV_TEXT, ...steps.flat(), 'WHERE IT PAYS IN THIS WORKFLOW', ...PROMPTS].join('\n'));
+  return 0;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));