fix: align testing issue commands + add moderator sync pitfall

Address review from 星月:
- Update testing issue #290 to match actual CLI commands
- Add pitfall: moderator must be sync (not async)
- knowledge commands confirmed real (exist in codebase)

Ref: #290

.knowledge/adapter.md

@@ -28,29 +28,8 @@ For long-running or incremental agent outputs:
 |---------|---------|------|
 | `@uncaged/nerve-adapter-cursor` | `cursorAdapter` / `createCursorAdapter()` | cursor-agent CLI |
 | `@uncaged/nerve-adapter-hermes` | `hermesAdapter` / `createHermesAdapter()` | hermes chat CLI |
-| `@uncaged/nerve-workflow-utils` | `createLlmAdapter(provider)` | OpenAI-compatible HTTP chat (single-turn) |
 
-The Cursor and Hermes adapter packages each export a **default instance** (sensible defaults) and a **factory** for custom config. `createLlmAdapter` is a factory on `@uncaged/nerve-workflow-utils` only.
-
-## createLlmAdapter
-
-`createLlmAdapter` builds an `AgentFn` from an `LlmProvider` (`baseUrl`, `apiKey`, `model`). One chat completion per role step: **system** = the string passed by `createRole` (your prompt); **user** = `ctx.start.content` (the thread’s start frame). On failure it throws with a formatted LLM error.
-
-```ts
-import { createLlmAdapter, createRole } from "@uncaged/nerve-workflow-utils";
-import { z } from "zod";
-
-const metaSchema = z.object({ ok: z.boolean() });
-
-const planner = createRole(
-  createLlmAdapter({ baseUrl: "https://api.example.com/v1", apiKey: "…", model: "gpt-4o-mini" }),
-  "You are a planner…",
-  metaSchema,
-  extractConfig,
-);
-```
-
-Use this when you want a role backed by an HTTP LLM instead of a subprocess CLI adapter.
+Each exports a **default instance** (sensible defaults) and a **factory** for custom config.
 
 ## Usage in Workflows
 

.knowledge/workflow.md

@@ -2,20 +2,6 @@
 
 Stateful multi-step execution driven by Roles and a Moderator.
 
-## Workspace Layout (authoring)
-
-User Nerve workspaces use a **flat** build: one root `package.json`, one root bundle script (typically `scripts/build.mjs` wired from `scripts.build`), and **no** per-workflow `package.json` or `tsconfig.json`.
-
-| Location | Purpose |
-|----------|---------|
-| `workflows/<name>/index.ts` | Default export: `WorkflowDefinition` (moderator + role map). |
-| `workflows/<name>/roles/<role>.ts` | One module per role — schemas, prompts, `createRole` factories, or hand-written async role functions. |
-| `dist/workflows/<name>/index.js` | Emit of the root build; this is what the daemon loads. |
-
-**Naming:** Workflow ids should be **verb-first** kebab-case phrases (e.g. `deploy-staging`, `scan-dependencies`), not opaque nouns alone.
-
-Senses follow the same flat pattern: `senses/<name>/src/*.ts`, `migrations/`, root build → `dist/senses/<name>/index.js`. See `.knowledge/sense.md`.
-
 ## Core Concepts
 
 - **Workflow** — definition with concurrency strategy

packages/cli/skills/hermes/SKILL.md

@@ -0,0 +1,505 @@
+---
+name: nerve
+version: 0.5.0
+description: >
+  Nerve — AI agent 观测引擎。掌握 nerve 的核心概念、CLI 操作、sense/workflow 开发。
+  加载此 skill 后你可以：查看系统状态、监控 sense、触发 workflow、开发新 sense 和 workflow。
+metadata:
+  hermes:
+    tags: [nerve, sense, workflow, monitoring, agent-kernel]
+    homepage: https://git.shazhou.work/uncaged/nerve
+---
+
+# Nerve — AI Agent 观测引擎
+
+Nerve 是一个轻量级观测引擎守护进程。它持续观测外部状态，通过声明式规则响应变化，编排多步骤工作流。
+
+## 核心架构
+
+```
+External World → Sense → Signal → Workflow → Log
+```
+
+| 概念 | 说明 |
+|------|------|
+| **Sense** | 观测函数，`compute()` 采样或推导数据。返回非 null 则发出 Signal，可选触发 Workflow。每个 Sense 有独立 SQLite 数据库。 |
+| **Signal** | Sense 返回非 null 时发出的通知。纯事实，无意图。通过内存 Signal Bus 分发，不持久化。 |
+| **Workflow** | 有状态的多步骤执行。包含 Role（有副作用的执行者）和 Moderator（纯路由器）。每个实例是一个 Thread，有唯一 runId。 |
+| **Log** | 不可变审计日志。记录执行、状态转换、错误。不能触发 Sense（防止反馈循环）。 |
+| **Engine** | 内核，持有 Signal Bus、Process Manager、Workflow Manager。不直接加载用户代码。 |
+| **Daemon** | 引擎运行时，作为后台进程运行。 |
+
+**关键规则：**
+- 因果链单向：External → Sense → Signal → Workflow + Log
+- 进程隔离：每个 Sense group 一个 worker（长期），每个 Workflow 类型一个 worker（按需）
+- 两个扩展点：Sense（观测什么 + 何时）、Workflow（做什么）
+
+## 工作区结构
+
+```
+~/.uncaged-nerve/          # 默认工作区（nerve init 创建）
+├── nerve.yaml             # 核心配置
+├── senses/
+│   └── <name>/
+│       ├── src/index.ts   # exports compute() + table
+│       ├── src/schema.ts  # drizzle 表定义
+│       └── migrations/    # SQL 迁移
+├── workflows/
+│   └── <name>/
+│       ├── index.ts       # exports WorkflowDefinition
+│       └── roles/<role>/
+│           ├── index.ts   # role 实现
+│           └── prompt.md  # 可选 system prompt
+└── data/                  # 运行时数据（SQLite、blobs）
+```
+
+---
+
+## CLI 完整参考
+
+全局选项：`--host <host:port>`（连接远程 daemon）、`--api-token <secret>`（Bearer 认证）
+
+### 初始化与脚手架
+
+```bash
+nerve init                          # 初始化工作区
+nerve init --from <git-url>         # 从 git 仓库克隆工作区
+nerve init workspace                # 只初始化工作区结构
+
+nerve create sense <name>           # 创建 sense 脚手架
+nerve create sense <name> --force   # 覆盖已有
+nerve create workflow <name>        # 创建 workflow 脚手架
+nerve create workflow <name> --force
+
+nerve validate                      # 验证 nerve.yaml 配置
+```
+
+### Daemon 管理
+
+```bash
+nerve daemon start                  # 启动后台 daemon
+nerve daemon start --port 3000      # 指定 HTTP API 端口
+nerve daemon stop                   # 停止 daemon
+nerve daemon restart                # 重启
+nerve daemon status                 # 查看状态
+nerve daemon logs                   # 查看日志
+nerve daemon logs --follow          # 实时日志
+nerve daemon logs --n 50            # 最近 50 行
+
+nerve dev                           # 前台开发模式（不 fork daemon）
+nerve dev --port 3000               # 指定端口
+```
+
+### Sense 操作
+
+```bash
+nerve sense list                    # 列出所有注册的 sense
+nerve sense trigger <name>          # 手动触发 sense 计算
+nerve sense schema <name>           # 查看 sense 数据库表结构
+nerve sense schema <name> --json    # JSON 格式
+nerve sense query <name> <sql>      # 对 sense 数据库执行只读 SQL
+nerve sense query <name> "SELECT * FROM samples ORDER BY ts DESC LIMIT 10" --json
+```
+
+### Workflow 操作
+
+```bash
+nerve workflow list                 # 列出 nerve.yaml 中定义的 workflow
+nerve workflow status               # 查看运行中的 workflow 状态
+nerve workflow trigger <name>       # 触发 workflow
+nerve workflow trigger <name> --prompt "检查生产环境"
+nerve workflow trigger <name> --maxRounds 50
+nerve workflow trigger <name> --dryRun   # 干跑模式
+```
+
+### Thread（Workflow 执行记录）
+
+```bash
+nerve thread list                   # 列出最近的 workflow 执行
+nerve thread list --all             # 包含已完成/失败的
+nerve thread list --workflow <name> # 按 workflow 过滤
+nerve thread list --limit 50        # 最多 50 条
+
+nerve thread show <runId>           # 查看 role 对话轮次
+nerve thread show <runId> --budget 16000  # 增大输出预算（默认 8000 字符）
+
+nerve thread inspect <runId>        # 查看详情和事件
+
+nerve thread kill <runId>           # 终止运行中/排队中的 thread
+```
+
+### Store（日志归档）
+
+```bash
+nerve store archive                 # 导出旧日志到 JSONL 归档
+nerve store archive --vacuum        # 归档后 VACUUM 数据库
+```
+
+### Knowledge（知识库）
+
+```bash
+nerve knowledge sync                # 从 knowledge.yaml 重建索引
+nerve knowledge query "搜索内容"     # 搜索知识库
+nerve knowledge query "内容" --limit 5
+nerve knowledge query "内容" -g     # 搜索所有注册仓库
+```
+
+### Remote（远程 daemon）
+
+```bash
+nerve remote add <name> <host:port> --token <secret>
+nerve remote list
+nerve remote show <name>
+nerve remote set-url <name> <host>
+nerve remote set-token <name> <token>
+nerve remote remove <name>
+nerve remote default <name>         # 设为默认远程
+```
+
+---
+
+## nerve.yaml 配置参考
+
+```yaml
+# 引擎全局配置
+max_rounds: 100              # moderator 最大轮次（默认 100）
+
+# Sense 配置
+senses:
+  cpu-usage:
+    group: system            # 必填，同 group 的 sense 共享 worker
+    interval: 10s            # 轮询间隔（duration: 5s, 10m, 1h）
+    throttle: 5s             # 最小计算间隔
+    timeout: 10s             # compute 超时
+    grace_period: null       # 优雅关闭等待
+    retention: 10000         # _signals 表最大行数（默认 10000）
+
+  system-health:
+    group: derived
+    on: [cpu-usage, disk-usage]  # 响应式：被列出的 sense 发出 signal 时触发
+    throttle: null
+    timeout: null
+
+# Workflow 配置
+workflows:
+  my-workflow:
+    concurrency: 1           # 必填，并发数
+    overflow: drop           # 必填，超并发时处理：drop | queue
+    max_queue: 100           # overflow=queue 时的队列上限（默认 100）
+
+# HTTP API
+api:
+  port: 3000                 # null = 不启用 HTTP
+  host: "127.0.0.1"         # 监听地址
+  token: null                # 非 loopback 时必填
+
+# LLM Extract（可选）
+extract:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+```
+
+---
+
+## Sense 开发指南
+
+### compute 函数签名
+
+```typescript
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { ComputeResult, WorkflowTrigger } from "@uncaged/nerve-core";
+
+export async function compute(
+  db: LibSQLDatabase,                          // 此 sense 的 Drizzle ORM 数据库
+  peers: Record<string, LibSQLDatabase>,       // 其他 sense 的数据库（只读）
+  options: { signal: AbortSignal },            // 超时 abort signal
+): Promise<ComputeResult<T>>
+```
+
+### 返回值
+
+```typescript
+// 返回 null = 静默，不发 signal
+// 返回非 null = 发出 signal，可选触发 workflow
+type ComputeResult<T> =
+  | null
+  | { signal: T; workflow: WorkflowTrigger | null };
+
+type WorkflowTrigger = {
+  name: string;          // workflow 名称（对应 nerve.yaml 中的 key）
+  maxRounds: number;     // moderator 最大轮次
+  prompt: string;        // 初始 prompt
+  dryRun: boolean;       // 干跑模式
+};
+```
+
+### Sense 模块导出
+
+```typescript
+// senses/<name>/src/index.ts
+import type { SenseModule, ComputeResult } from "@uncaged/nerve-core";
+import { table } from "./schema.js";
+
+export async function compute(
+  db: LibSQLDatabase,
+  _peers: Record<string, LibSQLDatabase>,
+  _options: { signal: AbortSignal },
+): Promise<ComputeResult<number>> {
+  const value = Math.random(); // 替换为真实观测逻辑
+  await db.insert(table).values({ ts: Date.now(), value });
+  return { signal: value, workflow: null };
+}
+
+export { table };
+```
+
+### Schema 定义
+
+```typescript
+// senses/<name>/src/schema.ts
+import { sqliteTable, integer, real } from "drizzle-orm/sqlite-core";
+
+export const table = sqliteTable("samples", {
+  ts: integer("ts").notNull(),
+  value: real("value").notNull(),
+});
+```
+
+### 调度方式
+
+1. **interval 轮询**：`interval: 10s` — 每 10 秒执行一次
+2. **响应式触发**：`on: [cpu-usage]` — 当 cpu-usage 发出 signal 时触发
+3. 两者可以组合
+
+### 调试
+
+```bash
+nerve dev                           # 前台运行，看实时输出
+nerve sense trigger <name>          # 手动触发一次
+nerve sense query <name> "SELECT * FROM samples ORDER BY ts DESC LIMIT 5"
+```
+
+### 完整示例：CPU 监控
+
+```typescript
+// senses/cpu-usage/src/schema.ts
+import { sqliteTable, integer, real } from "drizzle-orm/sqlite-core";
+
+export const table = sqliteTable("samples", {
+  ts: integer("ts").notNull(),
+  value: real("value").notNull(),
+});
+
+// senses/cpu-usage/src/index.ts
+import os from "node:os";
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import type { ComputeResult } from "@uncaged/nerve-core";
+import { table } from "./schema.js";
+
+export async function compute(
+  db: LibSQLDatabase,
+  _peers: Record<string, LibSQLDatabase>,
+  _options: { signal: AbortSignal },
+): Promise<ComputeResult<number>> {
+  const oneMin = os.loadavg()[0];
+  await db.insert(table).values({ ts: Date.now(), value: oneMin });
+  return { signal: oneMin, workflow: null };
+}
+
+export { table };
+```
+
+nerve.yaml:
+```yaml
+senses:
+  cpu-usage:
+    group: system
+    interval: 10s
+    throttle: 5s
+    timeout: 10s
+    retention: 10000
+```
+
+---
+
+## Workflow 开发指南
+
+### 核心类型
+
+```typescript
+import type {
+  WorkflowDefinition,
+  RoleResult,
+  ThreadContext,
+  StartStep,
+  RoleStep,
+} from "@uncaged/nerve-core";
+import { END } from "@uncaged/nerve-core";
+
+// Role：执行者，接收上下文返回结果
+type Role<Meta> = (ctx: ThreadContext) => Promise<RoleResult<Meta>>;
+type RoleResult<Meta> = { content: string; meta: Meta };
+
+// Moderator：路由器，决定下一个 role 或结束
+type Moderator<M> = (ctx: ThreadContext<M>) => (keyof M & string) | typeof END;
+
+// ThreadContext：对话上下文
+type ThreadContext<M = RoleMeta> = {
+  threadId: string;
+  start: StartStep;       // 初始 prompt（role: "__start__"）
+  steps: RoleStep<M>[];   // 所有 role 的执行记录
+};
+
+// WorkflowDefinition：完整定义
+type WorkflowDefinition<M> = {
+  name: string;
+  roles: { [K in keyof M & string]: Role<M[K]> };
+  moderator: Moderator<M>;
+};
+```
+
+### 基本 Workflow 示例
+
+```typescript
+// workflows/example/index.ts
+import type { RoleResult, ThreadContext, WorkflowDefinition } from "@uncaged/nerve-core";
+import { END } from "@uncaged/nerve-core";
+
+type Meta = Record<"main", { round: number }>;
+
+async function main(ctx: ThreadContext): Promise<RoleResult<{ round: number }>> {
+  const prompt = ctx.start.content;
+  return {
+    content: `处理完成: ${prompt}`,
+    meta: { round: ctx.steps.length },
+  };
+}
+
+const workflow: WorkflowDefinition<Meta> = {
+  name: "example",
+  roles: { main },
+  moderator(ctx: ThreadContext<Meta>) {
+    // 执行一次 main 就结束
+    return ctx.steps.length === 0 ? "main" : END;
+  },
+};
+
+export default workflow;
+```
+
+### 多 Role Workflow 示例
+
+```typescript
+import type { WorkflowDefinition, RoleResult, ThreadContext } from "@uncaged/nerve-core";
+import { END } from "@uncaged/nerve-core";
+
+type Roles = Record<"planner" | "executor" | "reviewer", { status: string }>;
+
+async function planner(ctx: ThreadContext): Promise<RoleResult<{ status: string }>> {
+  return { content: "计划: ...", meta: { status: "planned" } };
+}
+
+async function executor(ctx: ThreadContext): Promise<RoleResult<{ status: string }>> {
+  return { content: "执行: ...", meta: { status: "executed" } };
+}
+
+async function reviewer(ctx: ThreadContext): Promise<RoleResult<{ status: string }>> {
+  return { content: "审核通过", meta: { status: "approved" } };
+}
+
+const workflow: WorkflowDefinition<Roles> = {
+  name: "plan-execute-review",
+  roles: { planner, executor, reviewer },
+  moderator(ctx: ThreadContext<Roles>) {
+    if (ctx.steps.length === 0) return "planner";
+    const last = ctx.steps[ctx.steps.length - 1];
+    if (last.role === "planner") return "executor";
+    if (last.role === "executor") return "reviewer";
+    return END;
+  },
+};
+
+export default workflow;
+```
+
+### Agent 适配器
+
+Workflow role 可以集成 AI agent。已知适配器 ID：`echo`、`cursor`、`hermes`、`codex`。
+
+```typescript
+type AgentFn = (ctx: ThreadContext, systemPrompt: string) => Promise<string>;
+```
+
+### Workflow 运行状态
+
+`queued` → `started` → `completed` | `failed` | `crashed` | `killed` | `interrupted` | `dropped`
+
+---
+
+## 日常操作 Pattern
+
+### 查看系统整体状态
+
+```bash
+nerve daemon status                 # daemon 是否在运行
+nerve sense list                    # 所有 sense 及其调度配置
+nerve workflow status               # 运行中的 workflow
+nerve thread list                   # 最近的 workflow 执行记录
+```
+
+### 检查某个 sense 的历史数据
+
+```bash
+nerve sense query cpu-usage "SELECT * FROM samples ORDER BY ts DESC LIMIT 10" --json
+nerve sense schema cpu-usage        # 查看表结构
+```
+
+### 手动触发 workflow
+
+```bash
+nerve workflow trigger my-workflow --prompt "手动检查"
+nerve thread list --workflow my-workflow  # 查看执行状态
+nerve thread show <runId>           # 查看对话详情
+```
+
+### 排查 sense 报错
+
+```bash
+nerve daemon logs --follow          # 查看实时日志
+nerve sense trigger <name>          # 手动触发看报错
+nerve dev                           # 前台模式，更详细的输出
+```
+
+### 开发新 sense
+
+```bash
+nerve create sense my-sensor        # 脚手架
+# 编辑 senses/my-sensor/src/index.ts 和 schema.ts
+nerve validate                      # 验证配置
+nerve dev                           # 前台测试
+nerve sense trigger my-sensor       # 单次触发验证
+nerve sense query my-sensor "SELECT * FROM ..."  # 检查数据
+```
+
+### 开发新 workflow
+
+```bash
+nerve create workflow my-flow       # 脚手架
+# 编辑 workflows/my-flow/index.ts 和 roles/
+nerve validate                      # 验证配置
+nerve workflow trigger my-flow --prompt "测试" --dryRun  # 干跑
+nerve thread show <runId>           # 查看执行轨迹
+```
+
+---
+
+## Pitfalls
+
+- **Sense 返回值**：返回 `null` 表示静默（不发 signal）；返回 `{ signal, workflow }` 才发 signal。不要返回 undefined。
+- **no optional properties**：nerve 代码规范禁止 `?:`，用 `T | null` 代替。
+- **函数式风格**：用 `function` + `type`，不用 `class` + `interface`。
+- **workflow 用 default export**：这是唯一允许 default export 的场景。
+- **_signals 表**：每个 sense 自动有 `_signals` 表记录 signal 历史，受 `retention` 配置限制。
+- **peers 只读**：sense 的 `peers` 参数提供其他 sense 数据库的只读访问，不要写入。
+- **concurrency + overflow**：workflow 必须配置并发策略，否则验证失败。
+- **moderator 是同步函数**：不要加 async，moderator 是纯路由逻辑，不能有副作用。

packages/cli/src/__tests__/e2e-validate-init.test.ts

@@ -205,10 +205,6 @@ describe("e2e init", () => {
     expect(existsSync(join(nerveRoot, "scripts", "build.mjs"))).toBe(true);
     expect(existsSync(join(nerveRoot, "biome.json"))).toBe(true);
     expect(existsSync(join(nerveRoot, ".gitignore"))).toBe(true);
-    expect(existsSync(join(nerveRoot, "AGENT.md"))).toBe(true);
-    const agentMd = readFileSync(join(nerveRoot, "AGENT.md"), "utf8");
-    expect(agentMd).toContain("verb-first");
-    expect(agentMd).toContain("createRole");
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "src", "index.ts"))).toBe(true);
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "src", "schema.ts"))).toBe(true);
     expect(existsSync(join(nerveRoot, "senses", "cpu-usage", "migrations", "0001_init.sql"))).toBe(

packages/cli/src/commands/init.ts

@@ -127,70 +127,6 @@ node_modules/
 knowledge.db
 `;
 
-/** Generated at workspace root so agents can \`cat AGENT.md\` instead of npm skill paths. */
-const AGENT_MD = `# Nerve workspace — agent guide
-
-This file is created by \`nerve init\`. Read it before implementing senses or workflows.
-
-## Directory layout
-
-| Path | Purpose |
-|------|---------|
-| \`nerve.yaml\` | Senses, workflows, intervals, groups |
-| \`package.json\` | Single root package — no per-sense/per-workflow packages |
-| \`scripts/build.mjs\` | Root esbuild step; output under \`dist/\` |
-| \`senses/<name>/src/index.ts\` | Sense \`compute()\` entry |
-| \`senses/<name>/src/schema.ts\` | Drizzle SQLite schema (TypeScript) |
-| \`senses/<name>/migrations/*.sql\` | SQL migrations (next to \`src/\`, not inside it) |
-| \`workflows/<name>/index.ts\` | Default export: \`WorkflowDefinition\` |
-| \`workflows/<name>/roles/<role>.ts\` | One TypeScript file per role |
-| \`dist/senses/<name>/index.js\` | Bundled sense (after build) |
-| \`dist/workflows/<name>/index.js\` | Bundled workflow (after build) |
-
-There is **no** \`package.json\` or \`tsconfig.json\` inside individual senses or workflows.
-
-## Naming
-
-- **Workflows:** verb-first kebab-case (e.g. \`review-pull-request\`, \`deploy-staging\`). Avoid bare nouns like \`notifications\`.
-- **Senses:** kebab-case descriptive nouns (e.g. \`cpu-usage\`).
-
-## Workflow roles — four-tuple pattern
-
-Wire each role with \`createRole\` from \`@uncaged/nerve-workflow-utils\`:
-
-1. **Adapter** — \`AgentFn\` (LLM call)
-2. **Prompt builder** — \`async (ctx: ThreadContext) => string\`
-3. **Meta schema** — Zod object (routing / structured output from the model)
-4. **Extractor config** — how JSON meta is parsed from replies
-
-Keep meta small (often one boolean per role). The **moderator** in \`WorkflowDefinition\` routes between role names.
-
-## Build commands
-
-Always run from the **workspace root**:
-
-\`\`\`bash
-pnpm run build
-# or: npm run build
-\`\`\`
-
-Fix errors until this succeeds. New workflows must appear under \`workflows/<name>/\` and be registered in \`nerve.yaml\`; new senses under \`senses/<name>/\` with matching \`nerve.yaml\` entries.
-
-## Coding style (Nerve conventions)
-
-- Use \`type\`, not \`interface\`; prefer \`function\` over classes (except errors / library requirements).
-- **Named exports only** — no \`export default\` (exception: \`workflows/<name>/index.ts\` uses default export for the daemon loader).
-- Nullable fields: \`T | null\`, not TypeScript optional \`?:\`.
-- No dynamic \`import()\` in workspace code (bundling and tooling assume static imports).
-- Use \`async\`/\`await\`; use a \`Result\` type for expected failures instead of control-flow try/catch.
-
-## Extra references (optional)
-
-- \`CONVENTIONS.md\` — project-specific overrides at repo root.
-- \`.knowledge/*.md\` — deeper docs when working inside the Nerve monorepo.
-- \`.cursor/skills/\` — Cursor Agent Skills (\`SKILL.md\` per skill).
-`;
-
 const NERVE_SKILLS_MDC = `---
 description: >-
   Where Agent Skills live in this Nerve workspace and how to use them with Cursor
@@ -426,7 +362,6 @@ async function runInitWorkspace(force: boolean, skipInstall = false): Promise<vo
   writeFile(join(nerveRoot, "scripts", "build.mjs"), BUILD_MJS);
   writeFile(join(nerveRoot, "biome.json"), BIOME_JSON);
   writeFile(join(nerveRoot, ".gitignore"), GITIGNORE);
-  writeFile(join(nerveRoot, "AGENT.md"), AGENT_MD);
   writeFile(join(nerveRoot, "senses", "cpu-usage", "src", "index.ts"), CPU_INDEX_TS);
   writeFile(join(nerveRoot, "senses", "cpu-usage", "src", "schema.ts"), CPU_SCHEMA_TS);
   writeFile(

packages/workflow-meta/src/develop-sense/roles/coder.ts

@@ -10,7 +10,7 @@ export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 export function coderPrompt({ threadId }: { threadId: string }): string {
   return `Read the workflow thread for the planner's sense design and any tester feedback: \`nerve thread ${threadId}\`
-Read \`cat AGENT.md\` from the repository root, then \`CONVENTIONS.md\` and \`.knowledge/sense.md\` if present.
+Read the nerve-dev skill for sense file structure and conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 
 ## Your task
 
@@ -20,21 +20,21 @@ Implement (or fix) the sense the planner designed. If there is tester feedback i
 
 You do NOT need to finish everything in one pass. You may return \`done: false\` to continue in the next iteration.
 
-## File structure for each sense (flat workspace)
+## File structure for each sense
 
-The workspace has **one root** \`package.json\` and root \`scripts/build.mjs\` (or equivalent) that bundles all senses. There is **no** per-sense \`package.json\`. Bundled output is \`dist/senses/<name>/index.js\` after a root build.
-
-- \`senses/<name>/src/index.ts\` — compute entry; import schema as \`./schema.ts\`
+- \`senses/<name>/src/index.ts\` — TypeScript compute source; import schema as \`./schema.ts\`
 - \`senses/<name>/src/schema.ts\` — Drizzle schema (TypeScript)
-- \`senses/<name>/migrations/\` — SQL migration files (at sense root, not inside \`src/\`)
+- \`senses/<name>/migrations/\` — Drizzle migration files (at sense root, not inside src/)
+- \`senses/<name>/package.json\` — with esbuild build script
+- \`senses/<name>/index.js\` — bundled output generated by \`pnpm build\` (do NOT edit by hand)
 
-Look at existing senses for patterns.
+Look at existing senses for the package.json template and patterns.
 
 ## When to return done: true
 
 Return \`done: true\` ONLY when ALL of the following are true:
 - All required files are created
-- From the **workspace root**, \`pnpm run build\` or \`npm run build\` succeeds (run it!) and \`dist/senses/<name>/index.js\` exists
+- \`pnpm install --no-cache && pnpm build\` succeeds (run it!)
 - \`nerve.yaml\` is updated with the sense config
 
 Return \`done: false\` if you made progress but there is still work to do.`;

packages/workflow-meta/src/develop-sense/roles/planner.ts

@@ -12,7 +12,7 @@ export function plannerPrompt({ threadId }: { threadId: string }): string {
   return `You are planning a new Nerve sense.
 
 Read the workflow thread for the user's request: \`nerve thread ${threadId}\`
-Read the workspace guide: \`cat AGENT.md\` from the repository root (created by \`nerve init\`). Also read \`CONVENTIONS.md\` and \`.knowledge/sense.md\` if present. Optional skills live under \`.cursor/skills/\`.
+Read the nerve-dev skill for sense conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 Also look at existing senses in the \`senses/\` directory for patterns.
 
 Pick a good kebab-case name for this sense. Produce a PLAN (not code) in markdown:

packages/workflow-meta/src/develop-sense/roles/tester.ts

@@ -17,20 +17,21 @@ export function testerPrompt({
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. All paths below are relative to this directory. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
-Read \`cat ${nerveRoot}/AGENT.md\`, then \`${nerveRoot}/CONVENTIONS.md\` and \`${nerveRoot}/.knowledge/sense.md\` if they exist.
+Read the nerve-dev skill for expected file structure: \`cat ${nerveRoot}/node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 
 Verify the full lifecycle in this order:
 
-1. **File check** — all required sense files exist (no per-sense \`package.json\`):
+1. **File check** — all required sense files exist:
    - \`senses/<name>/src/index.ts\`
    - \`senses/<name>/src/schema.ts\`
    - \`senses/<name>/migrations/\`
+   - \`senses/<name>/package.json\`
 
-2. **Build** — from the workspace root:
+2. **Build** — run inside the sense directory:
    \`\`\`
-   cd ${nerveRoot} && pnpm run build
+   cd ${nerveRoot}/senses/<name> && pnpm install --no-cache && pnpm build
    \`\`\`
-   (or \`npm run build\` per root \`package.json\`.) Must produce \`${nerveRoot}/dist/senses/<name>/index.js\` without errors.
+   Must produce \`index.js\` at sense root without errors.
 
 3. **Config check** — \`nerve validate\` passes, confirming nerve.yaml is valid.
 

packages/workflow-meta/src/develop-workflow/roles/coder.ts

@@ -10,7 +10,7 @@ export type CoderMeta = z.infer<typeof coderMetaSchema>;
 
 export function coderPrompt({ threadId }: { threadId: string }): string {
   return `Read the workflow thread to get the planner's design and any reviewer/tester/committer feedback: \`nerve thread ${threadId}\`
-Read \`cat AGENT.md\` from the repository root, then \`CONVENTIONS.md\` and \`.knowledge/workflow.md\` if present. Optional skills live under \`.cursor/skills/\`.
+Read the nerve-dev skill for workflow file structure and conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 Also look at existing workflows in the \`workflows/\` directory for patterns.
 
 ## Your task
@@ -29,13 +29,15 @@ You do NOT need to finish everything in one pass. You may return \`done: false\`
 2. Second pass: implement role logic
 3. Third pass: fix build/lint errors
 
-## Workflow file structure (flat workspace)
-
-The workspace has **one root** \`package.json\` and **one** root build (\`pnpm run build\` or \`npm run build\`), implemented by \`scripts/build.mjs\`, which emits bundles under \`dist/workflows/<name>/index.js\`. There is **no** per-workflow \`package.json\` or \`tsconfig.json\`.
+## Workflow file structure
 
 Each workflow must have:
-- \`workflows/<name>/index.ts\` — default export \`WorkflowDefinition\` (moderator and meta types typically live here or are imported from co-located modules)
-- \`workflows/<name>/roles/<role>.ts\` — one TypeScript file per role (schemas, prompts, \`createRole\` wiring, or plain async role functions)
+- \`workflows/<name>/index.ts\` — WorkflowDefinition default export
+- \`workflows/<name>/build.ts\` — factory function
+- \`workflows/<name>/moderator.ts\` — moderator + meta types
+- \`workflows/<name>/roles/<role>.ts\` — meta schema and prompt function per role
+- \`workflows/<name>/package.json\` — with esbuild build script
+- \`workflows/<name>/tsconfig.json\` — TypeScript config
 
 For **new workflows**, also update \`nerve.yaml\` with \`workflows.<name>\`.
 
@@ -51,7 +53,7 @@ For **new workflows**, also update \`nerve.yaml\` with \`workflows.<name>\`.
 
 Return \`done: true\` ONLY when ALL of the following are true:
 - All changes from the plan are implemented
-- From the **workspace root**, \`pnpm run build\` or \`npm run build\` succeeds (run it!) so \`dist/workflows/<name>/index.js\` is produced
+- \`cd workflows/<name> && pnpm install --no-cache && pnpm build\` succeeds (run it!)
 - No lint or type errors remain
 
 Return \`done: false\` if you made progress but there is still work to do, or if build/lint has errors you plan to fix in the next iteration.`;

packages/workflow-meta/src/develop-workflow/roles/planner.ts

@@ -12,18 +12,18 @@ export function plannerPrompt({ threadId }: { threadId: string }): string {
   return `You are a Nerve workflow planner. You can **create new workflows** or **modify existing ones**.
 
 Read the workflow thread for the user's request: \`nerve thread ${threadId}\`
-Read the workspace guide: \`cat AGENT.md\` from the repository root (created by \`nerve init\`). Also read \`CONVENTIONS.md\` if it exists; if \`.knowledge/workflow.md\` exists (e.g. Nerve monorepo), read it for layout and engine behavior. Optional Cursor skills live under \`.cursor/skills/\`.
+Read the nerve-dev skill for workflow conventions: \`cat node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 List existing workflows: \`ls workflows/\`
 
 ## Determine the task type
 
-1. If the user wants to **modify an existing workflow** — read its current code (\`cat workflows/<name>/index.ts\`, \`ls workflows/<name>/roles/\`, \`cat workflows/<name>/roles/<role>.ts\`, etc.) and understand its current structure before planning changes.
+1. If the user wants to **modify an existing workflow** — read its current code (\`cat workflows/<name>/moderator.ts\`, \`cat workflows/<name>/build.ts\`, \`ls workflows/<name>/roles/\`, etc.) and understand its current structure before planning changes.
 2. If the user wants to **create a new workflow** — look at existing workflows in \`workflows/\` for patterns to follow.
 
 ## Produce a PLAN (not code) in markdown
 
 For **new workflows**:
-- Workflow name — **verb-first** kebab-case phrase (e.g. \`review-pull-request\`, \`deploy-staging\`), not a bare noun
+- Workflow name (kebab-case)
 - Roles list (name, purpose, tool)
 - Flow transitions / moderator routing logic
 - Validation loops design

packages/workflow-meta/src/develop-workflow/roles/tester.ts

@@ -17,22 +17,24 @@ export function testerPrompt({
 **IMPORTANT: The Nerve workspace is at \`${nerveRoot}\`. All paths below are relative to this directory. Always \`cd ${nerveRoot}\` first.**
 
 Read the workflow thread for context: \`nerve thread ${threadId}\`
-Read \`cat ${nerveRoot}/AGENT.md\`, then \`${nerveRoot}/CONVENTIONS.md\` and \`${nerveRoot}/.knowledge/workflow.md\` if they exist.
+Read the nerve-dev skill for expected file structure: \`cat ${nerveRoot}/node_modules/@uncaged/nerve-skills/nerve-dev/SKILL.md\`
 
 Get the workflow name from the thread (the planner's output).
 
 Verify the full lifecycle in this order:
 
-1. **File check** — all required workflow sources exist (under \`${nerveRoot}/\`):
+1. **File check** — all required workflow files exist (under \`${nerveRoot}/\`):
    - \`workflows/<name>/index.ts\`
-   - \`workflows/<name>/roles/\` with one \`.ts\` file per role (flat files, not per-role packages)
-   - **No** \`workflows/<name>/package.json\` or \`tsconfig.json\` expected
+   - \`workflows/<name>/build.ts\`
+   - \`workflows/<name>/moderator.ts\`
+   - \`workflows/<name>/roles/\` with one \`.ts\` file per role
+   - \`workflows/<name>/package.json\`
 
-2. **Build** — from the workspace root:
+2. **Build** — run inside the workflow directory:
    \`\`\`
-   cd ${nerveRoot} && pnpm run build
+   cd ${nerveRoot}/workflows/<name> && pnpm install --no-cache && pnpm build
    \`\`\`
-   (or \`npm run build\` if that is what the root \`package.json\` defines.) Must produce \`${nerveRoot}/dist/workflows/<name>/index.js\` without errors.
+   Must produce \`dist/index.js\` without errors.
 
 3. **Config check** — \`cd ${nerveRoot} && nerve validate\` passes, confirming nerve.yaml is valid.