@kybernesis/create 0.1.3 → 0.2.0

package/dist/cli.js

@@ -5,6 +5,7 @@
  *   kyb init [name]       scaffold a governed, remembering, multiplayer,
  *                         self-testing eve agent (also: npm create @kybernesis)
  *   kyb doctor            preflight an agent project: keys, issuer, envs, discovery
+ *   kyb skills [--global] install/refresh the FDE Claude Code skill suite
  *   kyb upgrade           bump @kybernesis/* to latest, gated on the eval suite
  *     --skip-eval           skip the eval gate (not for production changes)
  */
@@ -12,6 +13,7 @@ import { bold, dim } from "./util.js";
 import { init } from "./init.js";
 import { doctor } from "./doctor.js";
 import { upgrade } from "./upgrade.js";
+import { installSkills } from "./skills.js";
 const [, , command, ...rest] = process.argv;
 switch (command) {
     case "init":
@@ -20,6 +22,9 @@ switch (command) {
     case "doctor":
         await doctor();
         break;
+    case "skills":
+        installSkills({ global: rest.includes("--global") });
+        break;
     case "upgrade":
         await upgrade(rest.includes("--skip-eval"));
         break;
@@ -38,6 +43,8 @@ ${bold("kyb")} — Kybernesis agent scaffolder & FDE toolkit
   ${bold("kyb init [name]")}     scaffold a full Kybernesis eve agent
       --engineer        ${dim("add the engineer layer: workshop sandbox + vision dev loop")}
   ${bold("kyb doctor")}          preflight checks (keys, issuer, envs, discovery)
+  ${bold("kyb skills")}          install/refresh the FDE skill suite for Claude Code
+      --global          ${dim("install to ~/.claude/skills instead of this repo")}
   ${bold("kyb upgrade")}         bump @kybernesis/* packages, gated on evals
       --skip-eval       ${dim("skip the eval gate")}
 

package/dist/doctor.js

@@ -91,6 +91,35 @@ export async function doctor() {
         add("pass", `Slack connector uid: ${env.SLACK_CONNECTOR_UID}`, "verify trigger path /eve/v1/slack (vercel connect list)");
     else
         add("warn", "SLACK_CONNECTOR_UID not set", "vercel connect create slack --triggers");
+    // ── engineer layer (optional — checked only when installed) ────────────
+    const hasEngineer = Boolean(deps["@kybernesis/engineer"]) || existsSync(join(cwd, "agent/extensions/engineer.ts"));
+    if (hasEngineer) {
+        add("pass", `@kybernesis/engineer ${deps["@kybernesis/engineer"] ?? "(extension file present)"}`);
+        if (existsSync(join(cwd, "agent/sandbox/sandbox.ts")))
+            add("pass", "workshop sandbox file present");
+        else
+            add("fail", "agent/sandbox/sandbox.ts missing", "eve add @kybernesis/engineer --overwrite writes it");
+        if (env.BLOB_READ_WRITE_TOKEN)
+            add("pass", "file delivery configured (BLOB_READ_WRITE_TOKEN)");
+        else
+            add("warn", "BLOB_READ_WRITE_TOKEN not set — deliver tool will fail", "vercel blob create-store <name>-deliverables --access public --yes");
+        const vercelConn = join(cwd, "agent/connections/vercel.ts");
+        if (existsSync(vercelConn)) {
+            const src = readFileSync(vercelConn, "utf8");
+            const uid = /connect\(\s*"([^"]+)"/.exec(src)?.[1];
+            if (uid && uid.includes("/"))
+                add("pass", `vercel connection uses connector UID (${uid})`, "verify attached: vercel connect list");
+            else
+                add("fail", `vercel connection uses "${uid ?? "?"}" — must be the connector UID`, 'e.g. connect("mcp.vercel.com/vercel")');
+        }
+        else {
+            add("warn", "agent/connections/vercel.ts missing — no preview deploys/link-back", "eve add connection/vercel, then vercel connect create + attach");
+        }
+        if (env.VERCEL_OIDC_TOKEN || env.VERCEL_TOKEN)
+            add("pass", "Vercel credentials for local hosted sandboxes");
+        else
+            add("warn", "no VERCEL_OIDC_TOKEN — local sandbox/eval runs cannot reach Vercel Sandbox", "vercel link && vercel env pull");
+    }
     // ── eve discovery + local port ─────────────────────────────────────────
     const info = capture("npx", ["eve", "info"], cwd);
     if (info === null)

package/dist/init.js

@@ -2,6 +2,7 @@ import { cpSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync
 import { join, resolve } from "node:path";
 import { DEFAULT_ISSUER, EVE_VERSION, REGISTRY_URL, ask, bold, closePrompts, green, run, slug, yellow, } from "./util.js";
 import { envExample, evalFileTs, evalScript, identityMd, rootArcanaTs, subagentAgentTs, subagentArcanaTs, subagentInstructionsMd, } from "./templates.js";
+import { suiteDir } from "./skills.js";
 const ITEMS = ["enterprise", "arcana", "multiplayer", "evals"];
 // Official eve-registry limbs installed alongside the engineer layer.
 const ENGINEER_OFFICIAL_ITEMS = ["extension/agent-browser", "extension/github-tools", "connection/vercel"];
@@ -43,6 +44,13 @@ export async function init(rawName, options) {
                 console.log(yellow(`  ! ${item} did not install cleanly — re-run: npx eve add ${item}`));
         }
     }
+    console.log(bold("\n2c   Seeding the FDE Claude Code skill suite (.claude/skills) …"));
+    try {
+        cpSync(suiteDir(), join(dir, ".claude/skills"), { recursive: true });
+    }
+    catch {
+        console.log(yellow("  ! skill suite not found — run kyb skills inside the repo later"));
+    }
     console.log(bold("\n3/6  Writing agent identity, memory mount, and eval wiring …"));
     mkdirSync(join(dir, "agent/instructions"), { recursive: true });
     writeFileSync(join(dir, "agent/instructions/identity.md"), identityMd(displayName, depts));
@@ -86,11 +94,21 @@ ${green("✓")} ${bold(name)} scaffolded: governed (enterprise) · remembering (
 
 ${bold("Engineer notes:")}
   · The workshop sandbox (agent/sandbox/sandbox.ts) bakes Playwright into the
-    template on FIRST use — expect the first screenshot turn to take minutes,
-    warm turns ~seconds. Deployed sessions run under a domain allowlist; extend
-    it deliberately in that file when a project needs another host.
-  · agent-browser / github-tools / vercel connection may need their Connect
-    setup flows — run their printed setup commands if tools 401.` : ""}
+    template at DEPLOY time — a broken bootstrap fails the Vercel build loudly.
+    Deployed sessions run under a domain allowlist; extend it deliberately in
+    that file when a project needs another host.
+  · Vercel connection (preview deploys + link-back), after \`vercel link\`:
+      vercel connect create mcp.vercel.com --name vercel
+      vercel connect attach mcp.vercel.com/vercel --yes
+    then set connect("mcp.vercel.com/vercel") — the UID, not the short name —
+    in agent/connections/vercel.ts. First tool use posts an OAuth link in the
+    thread (user-scoped); grant "All projects" so the agent can create new ones,
+    then narrow the grant in the dashboard once the project exists.
+  · File delivery (the deliver tool needs it):
+      vercel blob create-store ${name}-deliverables --access public --yes
+    links the store and injects BLOB_READ_WRITE_TOKEN automatically.
+  · agent-browser / github-tools may need their Connect setup flows — run
+    their printed setup commands if tools 401.` : ""}
 
 ${bold("Human steps (in order) — the FDE playbook covers each in detail:")}
   1. Arcana: create workspaces (${name}-company, ${name}-eval${depts.map((d) => `, ${name}-${d}`).join("")}) + scoped kb_ keys; fill .env.local from .env.example

package/dist/skills.d.ts

@@ -0,0 +1,15 @@
+/** The skill suite shipped inside this package (skills/ beside dist/). */
+export declare function suiteDir(): string;
+/**
+ * Install/refresh the Kybernesis FDE skill suite for Claude Code.
+ *
+ * Default target: ./.claude/skills (the repo you're standing in — the suite
+ * then travels with the repo, including through client handover).
+ * --global targets ~/.claude/skills for the FDE's own machine.
+ *
+ * Existing suite skills are overwritten (that IS the update); skills outside
+ * the suite are never touched.
+ */
+export declare function installSkills(opts?: {
+    global?: boolean;
+}): void;

package/dist/skills.js

@@ -0,0 +1,40 @@
+import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { bold, dim, green } from "./util.js";
+/** The skill suite shipped inside this package (skills/ beside dist/). */
+export function suiteDir() {
+    return join(dirname(dirname(fileURLToPath(import.meta.url))), "skills");
+}
+/**
+ * Install/refresh the Kybernesis FDE skill suite for Claude Code.
+ *
+ * Default target: ./.claude/skills (the repo you're standing in — the suite
+ * then travels with the repo, including through client handover).
+ * --global targets ~/.claude/skills for the FDE's own machine.
+ *
+ * Existing suite skills are overwritten (that IS the update); skills outside
+ * the suite are never touched.
+ */
+export function installSkills(opts = {}) {
+    const src = suiteDir();
+    if (!existsSync(src)) {
+        console.error("skill suite not found in this install — reinstall @kybernesis/create");
+        process.exit(2);
+    }
+    const target = opts.global
+        ? join(homedir(), ".claude", "skills")
+        : join(process.cwd(), ".claude", "skills");
+    mkdirSync(target, { recursive: true });
+    const names = readdirSync(src).filter((n) => !n.startsWith("."));
+    for (const name of names) {
+        cpSync(join(src, name), join(target, name), { recursive: true });
+    }
+    console.log(`${green("✓")} ${bold("FDE skill suite")} → ${target}`);
+    for (const name of names)
+        console.log(`    ${name}`);
+    console.log(dim(opts.global
+        ? "  Available in every Claude Code session on this machine."
+        : "  Travels with this repo — every Claude Code session here loads them."));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kybernesis/create",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "The Kybernesis agent scaffolder and FDE toolkit: one command to a governed, remembering, multiplayer, self-testing eve agent — plus doctor and upgrade.",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,6 +20,7 @@
   ],
   "files": [
     "dist",
+    "skills",
     "NOTICE"
   ],
   "bin": {

package/skills/certification/SKILL.md

@@ -0,0 +1,59 @@
+---
+description: Use when running evals, certifying an agent or an eve version bump, debugging eval failures, or preparing a release — the Kybernesis QA discipline and its run hygiene.
+---
+
+# Certification & eval discipline
+
+The rule: **evals gate every deploy, and the consuming agent's suite is the
+release gate for every package change.** Nothing ships on "it looks right" —
+green suite or it doesn't go.
+
+## The suite
+
+`kybernesisBaseline()` from `@kybernesis/evals` in `evals/kybernesis.eval.ts`:
+smoke (boots, replies, identifies itself), five memory evals (no memory
+thrash on greetings; explicit remember never refused; proactive storage;
+brain-note two-step in order; cross-session unprompted recall), one routing
+eval per department, and with `engineer: true` the vision-loop eval
+(screenshot tool fires and the judge confirms the model SAW the render).
+Judge model is configured in `evals/evals.config.ts` and must NEVER be the
+model under test.
+
+## Run hygiene (each rule ate a real run)
+
+- `npm run eval` — always through the npm script: it forces every Arcana
+  workspace to `<name>-eval` so evals never write into a real brain.
+- **Kill any running dev server first** (`pkill -f "eve dev"`) — eve eval
+  attaches to an existing instance and runs stale code.
+- **Never edit the repo mid-run** — the dev runtime watches `agent/`; an
+  edit breaks the rebuild and kills remaining evals.
+- Engineer eval: hosted Vercel sandbox (no Docker), needs `vercel link` +
+  `vercel env pull` (VERCEL_OIDC_TOKEN). Warm template ≈3–4 min; a
+  pre-first-deploy cold bake is budgeted 20 min.
+- Stale sandbox state (migration errors, re-baking templates):
+  `rm -rf .eve/sandbox-cache .eve/dev-runtime` and rerun.
+- Don't pipe the eval command through `tail` in scripts — it masks the exit
+  code.
+
+## eve version certification
+
+Clients pin the **Kybernesis-certified** eve version (`kyb upgrade` carries
+them there — never blind npm-latest). Certifying a new eve: bump in a branch
+→ typecheck → `npx eve info` → full suite → live smoke on the deployed
+surface → advance the pin in @kybernesis/create → record the certification.
+
+## When an eval fails
+
+Read the eval's transcript before touching fixtures. Order of suspicion:
+(1) environment (stale dev server, missing env, cold template), (2) a real
+behavior regression — fix the agent, (3) only THEN the fixture — and if a
+fixture changes, the reason becomes a comment on it. A failure that reveals
+a new failure mode becomes a new fixture: that is how the suite grew every
+guard it has.
+
+## Release flow (packages)
+
+Edit in `~/platform` → build → bump → human publishes (browser auth) →
+consuming agent bumps → **full suite green** → deploy → registry item update
++ deploy if install files changed. Then propagate the lesson (see the
+`source-of-truth` skill).

package/skills/control-plane/SKILL.md

@@ -0,0 +1,54 @@
+---
+description: Use when registering an agent with the Kybernesis control plane, granting/revoking user access, wiring kybernesisAuth, running the governance E2E check, or debugging 401/403s from a governed agent.
+---
+
+# The Kybernesis control plane (agent.kybernesis.ai)
+
+The control plane governs WHO may talk to which agent. It is an OIDC-style
+issuer (per-org ES256 keys at `/api/jwks`) minting **IdentitySessions**
+`{ issuer, token, bundle, jwks }`; the policy bundle carries
+`agentGrants[{agent, level}]`. Agents verify OFFLINE via
+`kybernesisAuth()` from `@kybernesis/enterprise` — no callback to the plane
+on each request.
+
+## Wiring a governed agent
+
+Env: `KYBERNESIS_ISSUER=https://agent.kybernesis.ai` and
+`KYBERNESIS_AGENT=<agent-name>` (must equal the name registered in the
+admin). The registry item writes the route-auth file; `kyb doctor` checks
+JWKS reachability. Callers send `authorization: Bearer <token>` +
+`x-kybernesis-bundle: <bundle>`. Expected failures: 401 = no/bad
+credentials; 403 `agent_not_granted` = valid user, no grant for THIS agent.
+
+## Admin flow (browser, agent.kybernesis.ai)
+
+Register the agent under Agents (runtime: ▲ eve + deployment URL — the row
+shows a health probe). Grant users under their profile (grants resolve at
+MINT time). Users page also links/revokes chat identities (Slack ↔ user).
+Sign-in for humans is RFC 8628 device flow (user code, e.g. ABCD-EFGH).
+
+## Timing semantics (the support-ticket section)
+
+Token TTL defaults to 1h — that IS the revocation SLA for already-minted
+sessions. Suspension blocks new mints immediately; revocation of a grant
+takes effect at next mint. Tune `IDENTITY_TOKEN_TTL_SECONDS` to the client's
+appetite and tell them the number.
+
+## The governance E2E check (run before any client demo)
+
+1. Call the governed agent with no credentials → expect 401.
+2. Mint via device flow WITHOUT a grant → call → expect 403 agent_not_granted.
+3. Grant the user in the admin → re-mint → call → expect 200/202.
+4. Revoke the grant → old token still works until TTL; re-mint refused.
+5. Suspend the user → mint refused immediately; restore → mint works.
+
+This exact sequence was verified against production 2026-08-05. The demo
+moment for clients is step 3→4 — access appearing and disappearing from the
+admin screen.
+
+## Boundaries to state plainly
+
+Control-plane grants govern the HTTP/desktop doors — NOT the Slack door
+(Slack access = workspace membership). Person-scoped approvals and
+`governedSlackChannel()` are specced, not built. HITL approvals are
+session-scoped; any thread member can click them.

package/skills/eve-building/SKILL.md

@@ -0,0 +1,94 @@
+---
+description: Use when building out an eve agent — adding channels (Slack, iMessage, Telegram, Discord…), connections to client systems, agent skills, model pinning, instructions, or testing in eve dev. The how-to for every eve authoring surface.
+---
+
+# Building eve agents
+
+**The prime rule: read the pinned docs before writing eve code.** The
+installed framework docs are the source of truth for THIS project's version:
+`node_modules/eve/docs/` (README.md indexes them). Never author a channel,
+connection, sandbox, or schedule from memory — read its doc page first.
+Fallback when docs are absent: https://eve.dev/docs.
+
+## The loop
+
+`read the doc → write the file → npx eve info (0 diagnostics) → test a turn
+in npx eve dev → eval`. Every authoring task follows it.
+
+## Model (agent/agent.ts)
+
+`defineAgent({ model })`. No agent.ts → defaults to anthropic/claude-sonnet-5;
+once the file exists, `model` is required. String = Vercel AI Gateway id
+(`anthropic/claude-opus-4.8`, dot version) — the client-deploy default.
+Direct provider: install `@ai-sdk/<provider>`, pass `anthropic("claude-opus-4-8")`
+(hyphen version) + provider key in env. Dynamic per-principal selection via
+`defineDynamic({ fallback, events })` — prefer `session.started` scope (prompt
+caches are per model). Docs: `agent-config.md`.
+
+## Channels (agent/channels/, one file per surface)
+
+Filename = channel id. eve normalizes every surface into one runtime — tools/
+instructions/memory never change per channel. Available: Slack, Photon
+(iMessage), Telegram, Discord, Teams, Twilio (SMS/voice), GitHub, Linear,
+web (eve HTTP + useEveAgent), custom (`defineChannel`). Install:
+`eve add channel/<name>` (e.g. `channel/photon-imessage`, `channel/telegram`).
+
+Setup is always three steps: (1) the channel file, (2) provider-side
+credentials in env — the HUMAN runs anything with a browser login, (3) point
+the provider at the mounted route (`/eve/v1/<channel>`). Each channel's doc
+page (`docs/channels/<name>.mdx`) has the complete recipe including webhook
+registration and HITL behavior. For Kybernesis Slack deploys use
+`@kybernesis/multiplayer` (group semantics) — see the `kybernesis-packages`
+skill.
+
+## Connections (agent/connections/)
+
+Search before writing: `eve registry list` / `search <term>` / `view <item>`
+/ `add <item>` (setup flows resume via `eve add <item> --skip-install`).
+Hand-author only for client-internal services. Two shapes: MCP server →
+`defineMcpClientConnection`; OpenAPI 3.x doc → `defineOpenAPIConnection`.
+Four auth modes: static token (`auth.getToken` from env — pilot default),
+Vercel Connect user-scoped (`connect("<connector-UID>")` — UID not short
+name; first use posts an OAuth link in-thread, turn parks + resumes), Connect
+app-scoped (`connect({connector, principalType:"app"})` — non-interactive),
+or none. Connector provisioning is CLI-able:
+`vercel connect create <service> --name <n>` + `vercel connect attach <uid> --yes`.
+Subagents have NO user principal — static or app-scoped only. Write the
+connection `description` as a capability naming the systems; decide surface
+gating (fail-closed) and `approval` gates per connection at install time.
+Docs: `docs/connections/*`.
+
+## Skills (agent/skills/)
+
+On-demand procedures (model calls `load_skill` when the description matches).
+Forms: flat `.md` (first line = routing description) → packaged dir with
+`SKILL.md` (+`references/`, description frontmatter required) → `defineSkill`
+(only for typed/generated content). The description is a ROUTING HINT — write
+it as the triggering task ("Use when…") and test by asking without naming the
+skill. Scoped per agent: subagents need their own copies (or subagent-local
+extension mounts that ship them). Community marketplace: skills.sh — included
+in `eve registry search`; install `eve add @skills/<owner>/<repo>/<name>`;
+ALWAYS review the diff before running. Docs: `docs/skills.mdx`.
+
+## Instructions (agent/instructions.md or instructions/)
+
+Always-on context: identity, tone, standing rules ONLY — procedures go in
+skills. Directory entries combine alphabetically (root file first); `.ts`
+entries wrap `defineInstructions` (compile-time) or `defineDynamic`
+(per-session, e.g. surface-aware greetings). Draft with Claude from discovery
+notes, then judge by test (eve dev turns + evals), never by reading.
+
+## Subagents (agent/subagents/<id>/)
+
+Inherit NOTHING. Own tools/skills/connections/instructions/sandbox; on eve
+≥0.30 also OWN extension mounts (`subagents/<id>/extensions/` — mounts only
+into that subagent). No channels/schedules; no user principal; whole job must
+fit one delegation call. Docs: `docs/subagents.mdx`.
+
+## Test in eve dev
+
+`npx eve dev` boots the local runtime + chat TUI. Walk: identity → skill
+routing (watch load_skill) → delegation → memory round-trip → (engineer)
+screenshot turn. Local principal counts as a DM surface. Kill the dev server
+before `npm run eval`. The TUI is NOT the deployed agent — redeploy after
+every change.

package/skills/fde-engagement/SKILL.md

@@ -0,0 +1,35 @@
+---
+description: Use when running or planning a Kybernesis FDE client engagement — pilot phases, discovery questions, day-by-day plan, demo script, handover. The operating manual for deploying an eve agent at a client.
+---
+
+# Kybernesis FDE engagement
+
+Kybernesis forward-deploys engineers into companies to agentify them: we build
+eve-framework agents the client reaches on surfaces they already use (Slack,
+iMessage, Telegram, web…), wired to their systems, governed by our control
+plane (agent.kybernesis.ai), remembering through Arcana, and quality-gated by
+evals. You (Claude) are the FDE's co-builder for all of it.
+
+The complete engagement runbook is `references/playbook.md` — READ THE PHASE
+YOU ARE IN before acting. Map of the playbook:
+
+- **Fast path**: `npm create @kybernesis <name> -- [--engineer]` scaffolds the
+  entire baseline (governance + memory + multiplayer Slack + evals, optional
+  engineer layer). `kyb doctor` checks wiring at any point.
+- **Phase 1–2**: pre-engagement checklist; the discovery conversation (agent
+  name, departments, SURFACES — never assume Slack, §2.3 — cohort, data
+  sensitivities). Leave discovery with the §2.6 table filled in.
+- **Phase 3**: environment setup — scaffold, `vercel link`, registry, version
+  pins (eve pinned to the Kybernesis-CERTIFIED version, never blind latest).
+- **Phase 4**: the build — model pinning (§4.0b), our packages (§4.1–4.3b),
+  channels/connections/skills for the client's stack (§4.3c–e), instructions
+  (§4.4), `eve dev` test-drive (§4.4b), subagents (§4.5), evals (§4.8).
+- **Phase 5–6**: deploy + control-plane registration and grants.
+- **Phase 7–9**: pilot onboarding, the acceptance demo script, handover.
+- **§10**: troubleshooting appendix — check it before debugging from scratch.
+- **§11**: known gaps — state them plainly to the client, never sell around.
+
+Non-negotiables that survive every engagement: production promotion is
+human-approved; evals gate every deploy; secrets live in env (Vercel
+Sensitive), never in code or memory; every live failure becomes a playbook or
+skill edit the same day (see the `source-of-truth` skill).