@kybernesis/create 0.1.4 → 0.2.0

package/skills/kybernesis-packages/SKILL.md

@@ -0,0 +1,74 @@
+---
+description: Use when installing, configuring, or debugging any @kybernesis package — arcana (memory), enterprise (governance), multiplayer (Slack), engineer (build+ship), evals (QA), create (kyb CLI) — or the Kybernesis registry. Includes every production-learned gotcha.
+---
+
+# The Kybernesis packages
+
+Six packages, npm-public under `@kybernesis`, Apache-2.0, monorepo
+`KybernesisAI/platform`. Registry: `https://registry.kybernesis.ai`
+(`eve registry add @kybernesis=https://registry.kybernesis.ai/r/{name}.json`,
+then `eve add @kybernesis/<item>`). Each covers one axis:
+
+- **arcana** — memory. Extension mount `arcana({ apiKey, workspace,
+  resolveWorkspace? })`. Workspace-scoped `kb_` keys (403 outside their
+  workspace — one key per brain). `resolveWorkspace` only from VERIFIED
+  session context, never model output, and only key-reachable workspaces.
+  Subagents: local extension mount (`subagents/<id>/extensions/arcana.ts`,
+  eve ≥0.30) or plain connection + skill copies. Header
+  `X-Kyberagent-Agent: <workspace>` required by the MCP.
+- **enterprise** — governance. Plain library (route auth can't ship in an
+  extension). `kybernesisAuth()` admits only control-plane IdentitySessions
+  WITH a grant for this agent (`authorization: Bearer` + `x-kybernesis-bundle`
+  headers; 401 no-creds, 403 agent_not_granted). Lazy JWKS — compiles without
+  KYBERNESIS_ISSUER. See the `control-plane` skill.
+- **multiplayer** — Slack conversation mechanics. `multiplayerSlackChannel()`
+  from `/slack` subpath: thread = shared session with per-speaker verified
+  identity, no-re-mention continuation, dual surface (verified
+  `surface: "channel"|"dm"` attribute + helpers from package root), `/new` DM
+  reset. Slack-only today.
+- **engineer** — build + ship. Extension: `screenshot` (renders in in-sandbox
+  Chromium, returns pixels the model SEES) + `deliver` (sandbox file → public
+  Blob URL; needs BLOB_READ_WRITE_TOKEN — one-liner:
+  `vercel blob create-store <name>-deliverables --access public --yes`) +
+  six skills (dev-loop, scaffold, visual-qa, git-discipline, ship,
+  architecture-notes). The registry item ALSO writes
+  `agent/sandbox/sandbox.ts` — the workshop: Playwright baked into the
+  template at DEPLOY time, backend PINNED to Vercel Sandbox (no Docker
+  anywhere, local runs use hosted sandboxes via `vercel link` + `env pull`),
+  domain allowlist = the client's security posture. Ship loop: preview deploys
+  via the Vercel MCP connection (inline file tree, no git needed, no token in
+  the VM); production promotion is ALWAYS human-approved.
+- **evals** — QA. `kybernesisBaseline({ agentDisplayName, routing,
+  engineer? })` = smoke + 5 memory + routing per dept + optional vision-loop
+  eval. Judge model ≠ model under test. Hermetic runs force all workspaces to
+  `<name>-eval` via the npm script.
+- **create** — the `kyb` CLI: `init [--engineer]`, `doctor`, `upgrade`
+  (carries eve to the Kybernesis-CERTIFIED pin, never blind latest),
+  `skills`. Ships THIS skill suite.
+
+## Gotchas that each cost a real debugging session
+
+- **Tool names are mount-dependent — ALWAYS suffix-match.** Extension mount →
+  `arcana__memory__arcana_remember`; plain connection → `arcana__arcana_remember`.
+  In approvals/hooks/evals: `toolName.endsWith("arcana_remember")`.
+- **Vercel Connect connectors: use the UID** (`mcp.vercel.com/vercel`), never
+  the short name, in `connect()`. No grant editor exists — changing scope =
+  detach → remove → create (same UID) → attach, then re-auth from a FRESH
+  session (stale sessions error without re-prompting).
+- **Dev servers in the sandbox start DETACHED** (nohup + background + log +
+  curl-poll) — a foreground server blocks the tool call and hangs the turn.
+  Verified-and-unchanged builds deploy WITHOUT re-running a server.
+- **Deliver/file links: post URLs as plain text** — markdown bold glues
+  asterisks onto the URL in Slack and breaks it. Coach agents in prose, not
+  shell (WAFs eat shell-syntax Slack messages).
+- **ESM packaging**: relative imports need `.js` extensions (tsc doesn't
+  rewrite); eve is a peer dep with an explicit range (`>=0.30.0 <0.31.0`),
+  pinned exactly in devDeps.
+- **Eval fixtures are hardened on purpose** — in-test nonces (eve caches
+  compiled eval modules), per-run unique keys (workspaces accumulate),
+  company-general wording (dept-flavored prompts delegate and hide tool
+  calls), no security vocabulary ("canary" triggers refusals), long routing
+  timeouts. Do not "clean up" the odd-looking patterns.
+- **npm**: only the `kybernesis` account creates new packages in the scope;
+  publishes need the human's browser auth; new versions take 1–3 min to
+  propagate to anonymous reads.

package/skills/source-of-truth/SKILL.md

@@ -0,0 +1,60 @@
+---
+description: Use whenever a lesson is learned, a bug is fixed, a package/registry/playbook/doc changes, or something shipped — the checklist that keeps the Kybernesis knowledge system the single source of truth. Also use when unsure where a piece of knowledge belongs.
+---
+
+# Source of truth — and how it stays that
+
+The knowledge system only works if every change lands in the right place the
+same day it happens. This skill is the routing table and the checklist.
+
+## Where truth lives
+
+| Kind of knowledge | Canonical home |
+| --- | --- |
+| How to run an engagement | `packages/create/skills/fde-engagement/references/playbook.md` (THIS package) — the Obsidian copy is a mirror, never edit it first |
+| How to build eve agents / packages / control plane / certification | the sibling skills in `packages/create/skills/` |
+| Package behavior + install steps | each package's README + registry item in `~/platform` |
+| Framework truth | `node_modules/eve/docs/` at the pinned version — never restate at length, point at it |
+| What exists, what's specced, what's parked | the system-overview doc (session-handoff master, Obsidian) |
+| Session-to-session working context | the Claude project memory (`~/.claude/projects/.../memory/`) — pointers and lessons, not content that belongs above |
+
+Secrets live in env managers only. Client-specific facts live in the client's
+repo and brain, never in this suite.
+
+## The propagation checklist — run it whenever any of these happens
+
+**A live failure taught something / a gotcha was paid for:**
+1. Encode it where the next run will hit it: a skill in this suite, a package
+   README, an eval fixture, or a `kyb doctor` check — prefer executable
+   guards (doctor/evals) over prose.
+2. If it changes engagement procedure → edit `references/playbook.md` here,
+   then copy to the Obsidian mirror.
+3. Bump `@kybernesis/create`, build, commit — the human publishes.
+4. Add one line to the Claude project memory if future sessions need it
+   before they'd naturally read this suite.
+
+**A package changed (version, API, install steps):**
+1. README + registry item updated in the same commit as the change.
+2. Consuming agent bumped, suite green (the release gate), deployed.
+3. Version references in the playbook §3.4 pin list + system overview updated.
+4. If install/setup steps changed → the relevant skill here too.
+
+**Something new was built or shipped:**
+1. System overview: move it into "shipped and verified" with the evidence.
+2. Playbook: add the operational steps if an FDE will ever repeat them.
+3. This suite: extend the matching skill (or add one) if Claude needs it.
+
+**A framework (eve) version was certified:**
+1. Advance the pin in `@kybernesis/create` (`EVE_VERSION`).
+2. Check every skill/playbook claim that names framework behavior — versions
+   change what's true (example: "subagents cannot mount extensions" was true
+   on 0.29, false on 0.30, and stale in four places until a maintainer
+   review caught it).
+
+## The standing rule
+
+If you (Claude) finish a piece of work and cannot point at where its lesson
+now lives, the work is not done. When unsure where something belongs, the
+answer is almost always "the most executable place that the next person or
+agent will actually hit" — doctor check > eval fixture > skill > playbook >
+memory, in that order of preference.