eve-hub 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # eve-hub
 
+## 0.10.1
+
+### Patch Changes
+
+- The kit's hub client can store a Dash plan (`dashPlan`); the hub checks it and keeps it as the newest.
+
+## 0.10.0
+
+### Minor Changes
+
+- Every bot's system prompt is rendered from kit templates, each in its own tag: identity, team, execution, engineering, what_reaches_you, reaching_others, writing, role, execution_context. A bot with `agents/<bot>/agent/role.md` (who it is in the first paragraph, then how it works) gets an `instructions.ts` stub that renders the whole prompt in that order; a bot with only `instructions.md` still builds, with the shared sections after it. The forms guide is the `forms` skill, every bot has it. The team text is replaced by `<team_architecture>`, which a bot builds from `hub.workspace.json` (a hosted bot's is embedded at build) and recalls once per session and when it changes; it no longer asks the hub. A bot's own additions to its role go in `agents/<bot>/agent/role/*.md`, inside `<role>`; `hub workspace sync` moves a kit-rendered bot's `instructions/*.md` there (eve would load that folder after the execution context, outside every tag), and reports a bot that has both `role.md` and `instructions.md` without changing it. `create_agent` writes `role.md`.
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -7,8 +7,8 @@ The bot-side code every hub agent shares (milestone M3 in [`docs/architecture`](
 | `tools/update_thread.ts`, `list_threads.ts`, `read_thread.ts`, `react.ts`, `show.ts`, `attach_image.ts`, `browser.ts` | Registry and workspace tools (`defineTool`) | `agent/tools/<same name>.ts` |
 | `tools/create_thread.ts`, `post_message.ts`, `archive_thread.ts`, `unarchive_thread.ts`, `list_agents.ts`, `create_agent.ts`, `remove_agent.ts`, `restart_agent.ts`, `tag_threads.ts`, `apply_tags.ts` | The orchestrator's tools | `main`'s `agent/tools/<same name>.ts` |
 | `hooks/sandbox.ts` | Migrates legacy Docker sessions to the host sandbox (`defineHook`) | `agent/hooks/sandbox.ts` |
-| `instructions/main.ts`, `main-instructions.mjs` | main's instructions (`defineInstructions`), rendered at build time from the kit's `templates/main-instructions.md` + `workspace-protocol.md`, so no workspace carries a copy | `main`'s `agent/instructions.ts`; workspace-only additions in `agent/instructions/*.md` |
-| `instructions/protocol.ts` | The shared protocol alone, rendered from `templates/workspace-protocol.md` followed by `templates/engineering.md` | every other bot's `agent/instructions/protocol.ts`, appended after its own `instructions.md` (who the bot is) |
+| `instructions/main.ts`, `main-instructions.mjs` | main's instructions (`defineInstructions`), rendered at build time from the kit's `templates/main-instructions.md` (identity, role) between the shared templates, each in its own tag, so no workspace carries a copy | `main`'s `agent/instructions.ts`; workspace-only additions in `agent/role/*.md` (inside `<role>`) |
+| `instructions/protocol.ts` | The shared sections alone (`templates/team.md`, `execution.md`, `engineering.md`, `deliveries.md`, `reaching-others.md`, `writing.md`, each in its tag), for a bot whose `instructions.md` still says who it is and how it works | every other bot's `agent/instructions/protocol.ts`, appended after its own `instructions.md`; a bot with `agent/role.md` has `agent/instructions.ts` (`botInstructions`) instead, which renders identity, the shared sections and role in order |
 | `instructions/engineering.ts` | The engineering page alone (`templates/engineering.md`), for a subagent that doesn't carry the protocol | the subagent's `instructions/engineering.ts` |
 | `memory/workspace.ts`, `memory.mjs` | an eve memory slot (default export, constant `workspace` scope) whose provider recalls the workspace's `memory/<id>.md` entries (plus the `memory/<domain>/` folders the bot lists as `domains` in its roster entry), one message each, at every turn start and after compaction, only the ones whose text changed since the session last saw them, as new messages after the history; `validateMemory(root)` for a workspace's tests | every bot's (main too) `agent/memory/workspace.ts`: `export { default } from "eve-hub/memory/workspace"` |
 | `memory/bot.ts` | the same for the bot's own `agents/<bot>/memory/<id>.md` entries; the bot is found from its directory (`findBotDir`), scope is its name | every bot's `agent/memory/bot.ts`: `export { default } from "eve-hub/memory/bot"` |

package/execution-context.mjs

@@ -5,11 +5,11 @@
 // instructions/execution-context.ts stub calls `executionContext`), or, for a
 // bot the Vercel build deploys, a hosted page the build writes over that stub
 // (prepare.mjs), because only the build knows the deployment. The shared
-// prompts (templates/main-instructions.md, workspace-protocol.md) hold only
+// prompts (templates/*.md) hold only
 // what is true in both contexts.
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { templatesDir } from "./main-instructions.mjs";
+import { section, templatesDir } from "./main-instructions.mjs";
 import { agentRunsOn, parseWorkspace } from "./workspace.mjs";
 
 const page = (name, options) => readFileSync(join(templatesDir(options), `execution-context-${name}.md`), "utf8").trimEnd();
@@ -42,7 +42,6 @@ const list = (items) => items.map((item) => `\`${item}\``).join(", ");
 export function hostedContext({ bot, kit, removed, deployment: d }, options) {
   const dashboard = d.team && d.project ? `https://vercel.com/${d.team}/${d.project}` : undefined;
   const lines = [
-    "## Execution context",
     `You are \`${bot}\`, an eve agent deployed on Vercel, not on a laptop: \`hub.workspace.json\` defines you as hosted.`,
     "",
     "- **Workspace:** one hosted hub holds the threads and routes messages to each bot. Who is on the team, where each bot runs and what each can do come live from the hub: the team model message at the top of your turn (when it changes) and `list_agents`.",
@@ -64,7 +63,7 @@ export function hostedContext({ bot, kit, removed, deployment: d }, options) {
     `- **Logs:** ${dashboard ? `[runtime logs](${dashboard}/logs)${d.deployment ? ` and [this deployment](${dashboard}/${d.deployment.replace(/^dpl_/, "")})` : ""} in the Vercel dashboard` : "the Vercel project's runtime logs in the dashboard"}.`,
     ...(bot === "main" ? [page("hosted-main", options)] : []),
   ];
-  return `${lines.join("\n")}\n`;
+  return `${section("execution_context", lines.join("\n"))}\n`;
 }
 
 // What a bot's instructions/execution-context.ts stub renders. Hosted is the
@@ -75,5 +74,6 @@ export function executionContext(bot, workspace, options) {
   if (runsOn !== "local") {
     throw new Error(`${bot} is defined as hosted in hub.workspace.json, and a hosted bot's execution context is written by its Vercel build (eve-hub/vercel). A bot on this machine needs "runsOn": "local", on the agent or at the top of hub.workspace.json.`);
   }
-  return ["## Execution context", `You are \`${bot}\`: \`hub.workspace.json\` defines you as local.`, "", page("local", options), ...(bot === "main" ? [page("local-main", options)] : [])].join("\n") + "\n";
+  const lines = [`You are \`${bot}\`: \`hub.workspace.json\` defines you as local.`, "", page("local", options), ...(bot === "main" ? [page("local-main", options)] : [])];
+  return `${section("execution_context", lines.join("\n"))}\n`;
 }

package/{templates/forms.md → forms/SKILL.md}

@@ -1,10 +1,41 @@
+---
+name: forms
+description: How to show structure in a message. Load before you explain anything with parts that connect, events in order, numbers to compare, a before and after, or a choice the human must make; and before you post a table, diagram or chart.
+---
 
-## Forms
+# Showing structure
 
-A form is an interactive figure the app draws from a fenced block with a JSON body. Any path through three or more parts, order of events across two or more actors, or numbers to compare is a form, never prose steps, an arrow chain or a character drawing; draw it by default (principle 3 says why). Pick the shape: a path through parts (`flow`), an order of events (`sequence`), numbers to compare (`chart`), a choice you need from the human (`ask`). Anchor the picture in something they know, e.g. a before form then an after form, each labeled, in one message. Every part of one diagram is the same kind of thing (all hosts, all processes or all functions); say which in the sentence before it, and for a sequence in `unit`. A group is the level that contains them (processes grouped under their host). Plain prose is for what no shape helps. At most one or two forms per message.
+## Examples
+
+The prompt's show-don't-tell rule says when to draw. These are past misses.
+
+<example>
+The human asks "how do we detect an existing workspace? is it stored in the hub db?" Miss: one sentence and numbered steps. Instead: the one-line answer, then a flow of today's sign-in check and, beside it, the flow with a "create new" option. The question never says "diagram"; it asks for a path through parts.
+</example>
+<example>
+Build times by step. Miss: a schedule chart, then a paragraph repeating every step's seconds. Instead: the chart's title is the claim ("Linking is 70% of the build"), and the prose says only what to do about it.
+</example>
+<example>
+Three candidate looks for a theme. Miss: a prose list of concepts. Instead: a rendered image of each, labeled in a few words.
+</example>
+
+## Picking the shape
+- A path through three or more parts: `flow`.
+- An order of events across two or more actors: `sequence`.
+- Numbers to compare: `chart`. Time split into phases or hops (a latency breakdown, a turn's timeline) is a `schedule` chart, one row per request and one segment per phase, never one `bar` per total. A `bar` compares one number across items.
+- A choice you need from the human: `ask`. Choosing an option sends its label back as their reply, so write labels you can act on.
+- Two or more rows of short, comparable values: a table, at most four columns, a few words per cell. A single item, or anything that needs a reason, is a sentence or bullets.
+- Anchor the picture in something the reader knows: a labeled before form, then an after form, in one message.
+- Every part of one diagram is the same kind of thing (all hosts, all processes or all functions); say which in the sentence before it. A group is the level that contains them.
+- At most one or two forms per message.
+- Never draw with characters: no boxes, arrows, timelines or tables in a code fence.
+
+## How the app shows it
+- Each top-level code fence is a card with a copy button; a table is a table card; a link is a chip showing its label; an attached image is its own tile.
+- A fenced form becomes an interactive figure the human can step through.
+
+## Form syntax
 
-- A code fence is for text the reader will paste, never for a picture: no boxes, arrows, timelines or tables drawn with characters.
-- Pick the shape by what the numbers are. Time split into phases or hops (a latency breakdown, a turn's timeline) is a `schedule` chart: one row per turn or request, one start/end segment per phase, never one `bar` per total. A `bar` compares one number across items.
 - Claim first: a sentence that says what the form shows comes before it. A chart's `title` is its claim.
 - Link a word in your prose to a part with `[word](#id)`. Ids are lowercase slugs (`a-z`, `0-9`, `-`, up to 32 characters), unique in the whole message.
 - Put the explanation of a part in `note` (up to 240 characters), which the human sees when they point at or step to it. Keep labels short.

package/instructions/main.js

@@ -2,5 +2,5 @@ import { defineInstructions } from "eve/instructions";
 import { mainInstructions } from "../main-instructions.mjs";
 // main's system prompt, from hub's templates (see main-instructions.mjs). A
 // workspace's main re-exports this as agent/instructions.ts; workspace-only
-// additions go in agent/instructions/*.md, which eve appends after it.
+// additions go in agent/role/*.md, which the kit puts inside <role>.
 export default defineInstructions({ content: mainInstructions() });

package/kit-modules.json

@@ -11,6 +11,7 @@
   "memory/workspace",
   "schedules/dash",
   "schedules/prune",
+  "skills/forms",
   "skills/onboarding-profile",
   "tools/apply_tags",
   "tools/archive_thread",

package/main-instructions.mjs

@@ -1,19 +1,28 @@
-// main's instructions, rendered from the kit's templates: templates/main-instructions.md,
-// then the shared protocol (templates/workspace-protocol.md, the forms guide,
-// templates/forms.md, then the engineering page, templates/engineering.md). One source for
-// `hub workspace init` (lib/agent-template.mjs) and for every workspace's main,
-// which imports it (instructions/main.ts) instead of carrying a copy, so a
-// template edit reaches each workspace on main's next build. Every other bot
-// imports the protocol alone (instructions/protocol.ts) after its own head.
-import { existsSync, readFileSync, realpathSync } from "node:fs";
+// A bot's system prompt, rendered from the kit's templates. Every section is wrapped in its own
+// tag, in this order: identity, team, execution, engineering, what_reaches_you, reaching_others,
+// writing, role, execution_context (the last one is execution-context.mjs). eve joins a bot's
+// instruction sources with a blank line, flat instructions.{md,ts} first, then instructions/*
+// by file name, so the order is made in code: one source renders identity, the shared sections
+// and role together (botInstructions, mainInstructions), and instructions/execution-context.ts
+// follows. One source for `hub workspace init` (lib/agent-template.mjs) and for every
+// workspace's main, which imports it (instructions/main.ts) instead of carrying a copy, so a
+// template edit reaches each workspace on its next build.
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { findWorkspaceRoot } from "./workspace.mjs";
+import { ROLE_DIR, ROLE_FILE } from "./role-files.mjs";
+import { WorkspaceError, findWorkspaceRoot } from "./workspace.mjs";
 
 const HEAD = "main-instructions.md";
-const PROTOCOL = "workspace-protocol.md";
-const FORMS = "forms.md";
 const ENGINEERING = "engineering.md";
+const SHARED = [
+  ["team", "team.md"],
+  ["execution", "execution.md"],
+  [ENGINEERING.slice(0, -3), ENGINEERING],
+  ["what_reaches_you", "deliveries.md"],
+  ["reaching_others", "reaching-others.md"],
+  ["writing", "writing.md"],
+];
 const templatesOf = (kitDir) => join(kitDir, "templates");
 
 // The templates sit next to the kit in the hub checkout. Run by node, this
@@ -26,22 +35,54 @@ export function templatesDir({ env = process.env, cwd = process.cwd() } = {}) {
   const link = join(findWorkspaceRoot({ env, cwd }), "node_modules", "eve-hub");
   const linked = templatesOf(realpathSync(link));
   if (existsSync(join(linked, HEAD))) return linked;
-  throw new Error(`main's instruction templates aren't at ${here} or ${linked} (through ${link})`);
+  throw new Error(`the kit's prompt templates aren't at ${here} or ${linked} (through ${link})`);
 }
 
-export function mainInstructions(options) {
-  const head = readFileSync(join(templatesDir(options), HEAD), "utf8");
-  return `${head.trimEnd()}\n\n${workspaceProtocol(options)}`;
+export const section = (tag, body) => `<${tag}>\n${body.trim()}\n</${tag}>`;
+const template = (name, options) => readFileSync(join(templatesDir(options), name), "utf8");
+
+// A role file is who the bot is (its first paragraph), then how it works.
+export function splitRole(text, source = "role file") {
+  const [identity, ...rest] = text.trim().split(/\n\s*\n/);
+  const role = rest.join("\n\n").trim();
+  if (!identity || !role) throw new Error(`${source} needs an identity paragraph, a blank line, then the role`);
+  return { identity, role };
 }
 
-// The engineering page alone: the protocol ends with it, and a subagent that
-// never sees the protocol includes it (instructions/engineering.ts).
-export function engineeringPage(options) {
-  return readFileSync(join(templatesDir(options), ENGINEERING), "utf8");
+// What eve joins: each source's content with a blank line between, and trims only the whole. So a
+// source ends at its closing tag, with no newline of its own.
+const assemble = ({ identity, role }, additions, options) =>
+  [section("identity", identity), workspaceProtocol(options), section("role", [role, ...additions].join("\n\n"))].join("\n\n");
+
+// A bot's own additions to its role: agents/<bot>/agent/role/*.md, by file name, inside <role>.
+// They can't sit in instructions/*.md: eve loads that folder itself, after execution-context.ts,
+// outside every tag. A workspace with no folder (or no workspace at all) has none.
+function additionsOf(bot, options) {
+  let root;
+  try {
+    root = findWorkspaceRoot(options);
+  } catch (error) {
+    if (error instanceof WorkspaceError) return [];
+    throw error;
+  }
+  const dir = join(root, "agents", bot, "agent", ROLE_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir).filter((f) => f.endsWith(".md")).sort().map((f) => readFileSync(join(dir, f), "utf8").trim());
 }
 
-// The shared protocol: every bot but main appends it after its own
-// instructions.md (agent/instructions/protocol.ts re-exports instructions/protocol.ts).
-export function workspaceProtocol(options) {
-  return `${readFileSync(join(templatesDir(options), PROTOCOL), "utf8")}${readFileSync(join(templatesDir(options), FORMS), "utf8")}\n${engineeringPage(options)}`;
+export const mainInstructions = (options) => assemble(splitRole(template(HEAD, options), HEAD), additionsOf("main", options), options);
+
+// Every other bot: agents/<bot>/agent/role.md in the workspace.
+export { ROLE_DIR, ROLE_FILE };
+export function botInstructions(bot, options) {
+  const file = join(findWorkspaceRoot(options), "agents", bot, "agent", ROLE_FILE);
+  return assemble(splitRole(readFileSync(file, "utf8"), file), additionsOf(bot, options), options);
 }
+
+// The engineering section alone, for a subagent that doesn't carry the shared sections
+// (instructions/engineering.ts).
+export const engineeringPage = (options) => `${section("engineering", template(ENGINEERING, options))}\n`;
+
+// The shared sections, with no identity or role: what a bot whose instructions.md still holds
+// both gets appended (instructions/protocol.ts).
+export const workspaceProtocol = (options) => SHARED.map(([tag, file]) => section(tag, template(file, options))).join("\n\n");

package/memory/team.d.ts

@@ -1,13 +1,13 @@
 declare const recall: ({ messages }: {
     messages: readonly unknown[];
-}) => Promise<{
+}) => {
     messages: {
         id: string;
         content: string;
     }[];
-}>;
+};
 declare const _default: import("eve/memory").DefinedMemory<{
-    readonly description: "The team: who is on it, what each bot can do, and who hands work to whom.";
+    readonly description: "The team: how work flows between roles, what each owns, where bots run, and your place.";
     readonly namespace: "hub-team-memory";
     readonly scope: "workspace";
     readonly provider: {

package/memory/team.js

@@ -1,23 +1,20 @@
+import { basename } from "node:path";
 import { defineMemory, defineMemoryProvider } from "eve/memory";
-import { registryFetch } from "../registry-fetch.mjs";
-import { teamRecall } from "../team.mjs";
-// The team model (team.mjs) as an eve memory slot: roster, each bot's tools
-// and the handoff rules, from the hub's GET /api/team. Recall runs at the start
-// of every turn and after compaction, and adds one message only when the team
-// differs from what this session was last given, so a turn where nothing
-// changed carries nothing. A hub that can't answer within 5 s fails the recall, not the turn.
+import { findBotDir } from "../memory.mjs";
+import { architectureText, teamRecall } from "../team.mjs";
+import { findWorkspaceRoot, readWorkspaceFile } from "../workspace.mjs";
+// The team architecture (team.mjs) as an eve memory slot: how work flows between roles, what each
+// role owns, where bots run and this bot's own place, built from the workspace's hub.workspace.json
+// (a hosted bot's is embedded by its Vercel build, prepare.mjs). Recall runs at the start of every
+// turn and after compaction, and adds one message only when the text differs from what this
+// session was last given. The bot is the agents/<bot> directory this process runs from (findBotDir).
 const warned = new Set();
-async function fetchTeam(since) {
-    const res = await registryFetch(`/api/team${since ? `?since=${since}` : ""}`, { signal: AbortSignal.timeout(5_000) });
-    if (res.status === 304)
-        return null;
-    if (!res.ok)
-        throw new Error(`GET /api/team: HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
-    return (await res.json());
-}
-const recall = async ({ messages }) => {
+const recall = ({ messages }) => {
     try {
-        return await teamRecall(messages, fetchTeam);
+        const dir = findBotDir();
+        if (!dir)
+            return { messages: [] };
+        return teamRecall(messages, architectureText(readWorkspaceFile(findWorkspaceRoot()).data, basename(dir)));
     }
     catch (error) {
         const note = error.message;
@@ -29,7 +26,7 @@ const recall = async ({ messages }) => {
     }
 };
 export default defineMemory({
-    description: "The team: who is on it, what each bot can do, and who hands work to whom.",
+    description: "The team: how work flows between roles, what each owns, where bots run, and your place.",
     namespace: "hub-team-memory",
     scope: "workspace",
     provider: defineMemoryProvider({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",
@@ -18,6 +18,7 @@
     "./roster-model": "./roster-model.mjs",
     "./workspace": "./workspace.mjs",
     "./memory": "./memory.mjs",
+    "./team": "./team.mjs",
     "./workspace-roster": "./workspace-roster.mjs",
     "./bot-model": "./bot-model.mjs",
     "./subagent-cap": "./subagent-cap.mjs",

package/prepare.mjs

@@ -11,7 +11,7 @@
 //   is the host's fails the build, and the build never writes a sandbox;
 // - the kit extension, host-only workers and kit stubs are dropped, the hub's
 //   workflow world is wired in (and the Vercel Kit connection), every bot gets eve's git extension, and the
-//   workspace's memory is embedded in the bots' memory providers (a function
+//   workspace's memory and each bot's team architecture are embedded in the bots' memory providers (a function
 //   has no workspace cwd);
 // - /hub/manifest: the roster and the commit sha the deployment was built
 //   from, for the hub to sync from: a custom channel on main, routed in
@@ -25,6 +25,7 @@ export { DEPLOYED_KIT_FILES };
 import { deploymentFacts, hostedContext } from "./execution-context.mjs";
 import { botDomains, domainFolders, readBotMemory, readMemory, validateMemory } from "./memory.mjs";
 import { agentRunsOn, readWorkspaceFile, removeWorkspaceAgent } from "./workspace.mjs";
+import { architectureText } from "./team.mjs";
 
 // eve's git extension, for every bot: it points the bot at `gh` and `git` in
 // bash, whose GitHub credential is the sandbox firewall's (the Vercel sandbox lib/agent-template.mjs writes).
@@ -97,6 +98,15 @@ const recall = ({ messages }) => ({ messages: memoryRecall(entries, messages, {
 export default defineMemory({ namespace: ${JSON.stringify(`hub-${slot}-memory`)}, scope: ${JSON.stringify(scope)}, provider: defineMemoryProvider({ recall: { "turn.started": recall, "compaction.completed": recall } }) });
 `;
 
+// The team slot of a hosted bot: its architecture text, built from the whole roster (Mac bots
+// included) at build time, since a function has no workspace file to read.
+const teamProvider = (text) => `import { defineMemory, defineMemoryProvider } from "eve/memory";
+import { teamRecall } from "eve-hub/team";
+const text = ${JSON.stringify(text)};
+const recall = ({ messages }) => teamRecall(messages, text);
+export default defineMemory({ namespace: "hub-team-memory", scope: "workspace", provider: defineMemoryProvider({ recall: { "turn.started": recall, "compaction.completed": recall } }) });
+`;
+
 // Replaces the kit's execution-context stub (the local page) with the hosted
 // page, for a bot the definition says is hosted. Its removed-tools list is read
 // from the bot's folder as pruned.
@@ -158,6 +168,9 @@ export function prepareDeployment(dir) {
     mkdirSync(join(bot, "memory"), { recursive: true });
     const botDir = join(dir, "agents", name);
     writeFileSync(join(bot, "memory", "workspace.ts"), memoryProvider("workspace", readMemory(dir, { folders: domainFolders(botDomains(dir, botDir)) }).entries, "Standing decision", "workspace"));
+    // A folder the roster doesn't list has no place in the team, and a function can't read the file the stub would.
+    if (definition.agents.some((a) => a.name === name)) writeFileSync(join(bot, "memory", "team.ts"), teamProvider(architectureText(definition.data, name)));
+    else rmSync(join(bot, "memory", "team.ts"), { force: true });
     writeFileSync(join(bot, "memory", "bot.ts"), memoryProvider("bot", readBotMemory(dir, botDir).entries, "Your standing decision", name));
   }
 }

package/role-files.mjs

@@ -0,0 +1,5 @@
+// Where a bot's role lives in agents/<bot>/agent/: role.md (who it is, then how it works) and
+// role/*.md (its own additions to the role). Shared by the sync (stubs.mjs) and the renderer
+// (main-instructions.mjs), which a deployed bot imports without stubs.mjs.
+export const ROLE_FILE = "role.md";
+export const ROLE_DIR = "role";

package/schedules/hub.d.mts

@@ -18,6 +18,7 @@ export type Hub = {
   setSummary(path: string, text: string): Promise<unknown>;
   dashClassified(): Promise<Ok & { classifiedAt: string }>;
   fileThread(threadId: string, path: string): Promise<unknown>;
+  dashPlan(basis: string, plan: object): Promise<Ok & { id: string }>;
   dashEntries(entries: object[], remove?: string[], notice?: Notice | null): Promise<Ok & { entries: DashEntries }>;
 };
 export function createHub(options?: { base?: string; agent?: string; fetchImpl?: typeof fetch }): Hub;

package/schedules/hub.mjs

@@ -72,6 +72,8 @@ export function createHub({ base = registryBase(), agent = "main", fetchImpl = f
     // File an unfiled thread into a track (the classifier's pick), as a bot:
     // the hub refuses a thread that's already filed and doesn't lock it.
     fileThread: (threadId, path) => must(`/api/threads/${encodeURIComponent(threadId)}/track`, { method: "POST", body: JSON.stringify({ by: agent, path }) }),
+    // The plan main's pass made (wire DashPlanIn, checked in hosted-hub/src/domain/dash.mjs normalizePlan); the hub keeps it as the newest.
+    dashPlan: (basis, plan) => must("/api/dash/plan", { method: "POST", body: JSON.stringify({ by: agent, basis, plan }) }),
     // `notice` ({ schedule, text, clientId? }): posted in that schedule's
     // thread in the same write as the entries, or neither is kept.
     dashEntries: (entries, remove = [], notice = null) => must("/api/dash/entries", { method: "POST", body: JSON.stringify({ by: agent, entries, remove, ...(notice ? { notice } : {}) }) }),

package/skills/forms.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/skills/forms.gen.mjs

@@ -0,0 +1,2 @@
+// Generated by scripts/build-onboarding.mjs from forms/SKILL.md. Do not edit.
+export default {"description":"How to show structure in a message. Load before you explain anything with parts that connect, events in order, numbers to compare, a before and after, or a choice the human must make; and before you post a table, diagram or chart.","markdown":"# Showing structure\n\n## Examples\n\nThe prompt's show-don't-tell rule says when to draw. These are past misses.\n\n<example>\nThe human asks \"how do we detect an existing workspace? is it stored in the hub db?\" Miss: one sentence and numbered steps. Instead: the one-line answer, then a flow of today's sign-in check and, beside it, the flow with a \"create new\" option. The question never says \"diagram\"; it asks for a path through parts.\n</example>\n<example>\nBuild times by step. Miss: a schedule chart, then a paragraph repeating every step's seconds. Instead: the chart's title is the claim (\"Linking is 70% of the build\"), and the prose says only what to do about it.\n</example>\n<example>\nThree candidate looks for a theme. Miss: a prose list of concepts. Instead: a rendered image of each, labeled in a few words.\n</example>\n\n## Picking the shape\n- A path through three or more parts: `flow`.\n- An order of events across two or more actors: `sequence`.\n- Numbers to compare: `chart`. Time split into phases or hops (a latency breakdown, a turn's timeline) is a `schedule` chart, one row per request and one segment per phase, never one `bar` per total. A `bar` compares one number across items.\n- A choice you need from the human: `ask`. Choosing an option sends its label back as their reply, so write labels you can act on.\n- Two or more rows of short, comparable values: a table, at most four columns, a few words per cell. A single item, or anything that needs a reason, is a sentence or bullets.\n- Anchor the picture in something the reader knows: a labeled before form, then an after form, in one message.\n- Every part of one diagram is the same kind of thing (all hosts, all processes or all functions); say which in the sentence before it. A group is the level that contains them.\n- At most one or two forms per message.\n- Never draw with characters: no boxes, arrows, timelines or tables in a code fence.\n\n## How the app shows it\n- Each top-level code fence is a card with a copy button; a table is a table card; a link is a chip showing its label; an attached image is its own tile.\n- A fenced form becomes an interactive figure the human can step through.\n\n## Form syntax\n\n- Claim first: a sentence that says what the form shows comes before it. A chart's `title` is its claim.\n- Link a word in your prose to a part with `[word](#id)`. Ids are lowercase slugs (`a-z`, `0-9`, `-`, up to 32 characters), unique in the whole message.\n- Put the explanation of a part in `note` (up to 240 characters), which the human sees when they point at or step to it. Keep labels short.\n- `hi: true` marks the one part that matters, at most one per form. Unknown keys are rejected.\n- Send a form with `post_message`, never in your end-of-turn reply. The hub checks a posted form and rejects a bad one (400) with what's wrong: fix it and post again. Nothing checks a final reply, so a bad form there shows as raw JSON.\n\nA request leaves the [app](#app), the [hub](#hub) routes it, and a [bot](#bot) answers. `flow`: nodes 2–12 (`role`, `group`, `ref` as file:line), edges 1–24 (`from`, `to`, `label` up to 16, `fail` for a failure path), optional `groups`. Steps follow node order.\n\n```flow\n{\"nodes\": [\n  {\"id\": \"app\", \"label\": \"App\", \"role\": \"on your Mac\"},\n  {\"id\": \"hub\", \"label\": \"Hub\", \"role\": \"threads, routing\", \"hi\": true, \"ref\": \"server.mjs:5323\", \"note\": \"Stores the message, then wakes the bot.\"},\n  {\"id\": \"bot\", \"label\": \"Bot\", \"role\": \"one turn\"}],\n \"edges\": [{\"from\": \"app\", \"to\": \"hub\", \"label\": \"send\"}, {\"from\": \"hub\", \"to\": \"bot\", \"label\": \"wake\"}, {\"from\": \"bot\", \"to\": \"hub\", \"label\": \"post\"}]}\n```\n\nThe stream [drops](#drop) before the client [retries](#retry). `sequence`: actors 2–6, messages 1–16 (`from`, `to`, `label` up to 32, `fail` where it breaks, `ref` as file:line; `from` = `to` for a wait or retry inside one actor). Optional `unit` (up to 48 characters) is printed above the actors, e.g. \"each line = one process\"; optional `groups` (up to 3, `id` and `label`) with `group` on an actor draws a box around actors that share a host; grouped actors must sit next to each other. Steps follow message order.\n\n```sequence\n{\"unit\": \"each line = one process\", \"groups\": [{\"id\": \"mac\", \"label\": \"Mac\"}, {\"id\": \"hub-proj\", \"label\": \"Hub project\"}],\n \"actors\": [{\"id\": \"client\", \"label\": \"Client\", \"group\": \"mac\"}, {\"id\": \"hub\", \"label\": \"Hub\", \"group\": \"hub-proj\"}],\n \"messages\": [\n  {\"id\": \"drop\", \"from\": \"hub\", \"to\": \"client\", \"label\": \"stream drops\", \"fail\": true, \"ref\": \"Client.swift:257\"},\n  {\"id\": \"retry\", \"from\": \"client\", \"to\": \"hub\", \"label\": \"reconnects\", \"note\": \"Resumes from the last event id.\"}]}\n```\n\nFirst token is under 2 s everywhere but [Sydney](#syd). `chart`: `title` (the claim) and `points` 1–24, each with an id and `label`. `type` is one of four:\n- `bar`: `value`; optional `unit`, `target`.\n- `scatter`: axis titles `x`, `y`; points have numeric `x`, `y`.\n- `budget`: `value` > 0; optional `total`; `spare: true` for unused room.\n- `schedule`: `row` (up to 8 rows), `start` < `end`; optional `unit`.\n\n```chart\n{\"type\": \"bar\", \"title\": \"First token is under 2 s everywhere but Sydney\", \"unit\": \"s\", \"target\": 2,\n \"points\": [{\"id\": \"sfo\", \"label\": \"San Francisco\", \"value\": 0.9}, {\"id\": \"syd\", \"label\": \"Sydney\", \"value\": 2.6, \"hi\": true, \"note\": \"No region near it.\"}]}\n```\n\nYou need a decision, so I'm asking you to pick one. `ask`: 2–5 `options`, each with `id`, `label` (up to 40) and an optional one-line `line` (up to 160). Choosing one sends its label back as the human's reply, so write labels you can act on.\n\n```ask\n{\"options\": [\n  {\"id\": \"heron\", \"label\": \"Heron Lodge\", \"line\": \"Lake house 90 minutes north. Rooms for all 14, $5,400.\"},\n  {\"id\": \"pines\", \"label\": \"The Pines\", \"line\": \"In town, walkable. Sleeps 10, so 4 need a hotel.\"}]}\n```\n"};

package/skills/forms.js

@@ -0,0 +1,6 @@
+import { defineSkill } from "eve/skills";
+import skill from "./forms.gen.mjs";
+// The forms skill: forms/SKILL.md, embedded at build time (scripts/build-onboarding.mjs) so it
+// loads the same on the hub's machine and in a deployed bot. The prompt's "show, don't tell"
+// rule says when to draw; the skill says how.
+export default defineSkill(skill);

package/stubs.d.mts

@@ -5,3 +5,6 @@ export const MEMORY_STUBS: Record<string, string>;
 export const PROTOCOL_STUB_FILE: string;
 export const PROTOCOL_STUB: string;
 export function kitStub(file: string, options?: { files?: Record<string, string[]> }): string;
+export const ROLE_FILE: string;
+export const ROLE_DIR: string;
+export function botInstructionsStub(name: string): string;

package/stubs.mjs

@@ -1,3 +1,5 @@
+import { ROLE_DIR, ROLE_FILE } from "./role-files.mjs";
+
 // eve finds tools, hooks, and channels by file (the tool name is the file
 // name), so each bot keeps a one-line stub per kit module. Bot file -> what it
 // is, and which kit module it re-exports (default: the same path).
@@ -15,6 +17,7 @@ export const KIT_FILES = {
   "tools/read_thread.ts": ["Read any workspace thread."],
   "tools/list_agents.ts": ["The team right now: kind, place, tools, models, who's busy."],
   "tools/post_message.ts": ["Post into an existing thread or a bot's DM; with `status`, report the thread's phase."],
+  "skills/forms.ts": ["The forms skill (packages/agent-kit/forms/SKILL.md): how to draw a flow, sequence, chart or ask the app renders."],
 };
 
 // main, the orchestrator: the shared files (the same channel as every bot),
@@ -56,6 +59,7 @@ export const DEPLOYED_KIT_FILES = new Set([
   "tools/onboarding_scripts.ts",
   ...["react", "show", "update_thread", "list_threads", "read_thread", "post_message"].map((t) => `tools/${t}.ts`),
   "memory/team.ts",
+  "skills/forms.ts",
   ...["create_thread", "set_summary", "move_path", "archive_thread", "unarchive_thread", "list_agents", "create_agent", "remove_agent", "restart_agent", "tag_threads", "dash_update", "apply_tags"].map((t) => `tools/${t}.ts`),
 ]);
 
@@ -67,17 +71,30 @@ export function kitStub(file, { files = KIT_FILES, kit = files[file]?.[1] ?? fil
   return `// ${what} From eve-hub (packages/agent-kit/${kit}).\nexport { default } from "${kitPath(kit)}";\n`;
 }
 
-// Every bot but main: instructions.md says who the bot is (its head), and
-// instructions/protocol.ts re-exports the kit's protocol, which renders
-// packages/agent-kit/templates/workspace-protocol.md at build time. eve appends the
-// instructions/ entries after instructions.md, so the protocol follows the head
-// and is never copied into a bot.
+// A bot whose instructions.md still holds both who it is and how it works: instructions/protocol.ts
+// re-exports the kit's shared sections (packages/agent-kit/templates/, each in its own tag). eve
+// appends the instructions/ entries after instructions.md, so they follow it and are never copied
+// into a bot. A bot with a role.md (below) gets the whole prompt in order instead.
 export const PROTOCOL_STUB_FILE = "instructions/protocol.ts";
-export const PROTOCOL_STUB = `// The workspace protocol every bot shares, from packages/agent-kit/templates/workspace-protocol.md,
-// through eve-hub (packages/agent-kit/instructions/protocol.ts). eve appends it after
-// instructions.md, which holds only who this bot is. Don't copy the protocol there.
+export const PROTOCOL_STUB = `// The shared sections every bot carries, from packages/agent-kit/templates/, through eve-hub
+// (packages/agent-kit/instructions/protocol.ts). eve appends them after instructions.md.
+// Don't copy them there.
 export { default } from "eve-hub/instructions/protocol";
 `;
+// A bot with a role.md (agents/<bot>/agent/role.md: who it is in the first paragraph, then how it
+// works): instructions.ts renders its whole prompt, in order: identity, the shared sections, role
+// (packages/agent-kit/main-instructions.mjs). eve puts instructions.ts before instructions/*, so
+// the execution context stub follows.
+export { ROLE_DIR, ROLE_FILE };
+export const botInstructionsStub = (name) => `import { defineInstructions } from "eve/instructions";
+import { botInstructions } from "eve-hub/main-instructions";
+
+// ${name}'s system prompt: its role.md between the kit's templates (packages/agent-kit/templates/).
+// Edit who ${name} is and how it works in role.md, not here.
+export default defineInstructions({ content: botInstructions(${JSON.stringify(name)}) });
+`;
+const BOT_STUB = /^import \{ defineInstructions \} from "eve\/instructions";\s*import \{ botInstructions \} from "eve-hub\/main-instructions";\s*export default defineInstructions\(\{ content: botInstructions\("[a-z][a-z0-9-]*"\) \}\);?$/;
+
 // Every bot (main too): instructions/execution-context.ts renders the bot's
 // execution context from its definition in hub.workspace.json
 // (packages/agent-kit/execution-context.mjs). A hosted bot's is replaced by
@@ -107,13 +124,13 @@ export const MEMORY_STUBS = {
 };
 
 // main's instructions aren't copied into a workspace: agent/instructions.ts
-// re-exports the kit's, which renders packages/agent-kit/templates/main-instructions.md +
-// workspace-protocol.md at build time (packages/agent-kit/main-instructions.mjs).
-// Workspace-only additions go in agent/instructions/*.md; eve appends them.
+// re-exports the kit's, which renders packages/agent-kit/templates/main-instructions.md between
+// the shared templates at build time (packages/agent-kit/main-instructions.mjs).
+// Workspace-only additions go in agent/role/*.md, inside <role>.
 export const MAIN_INSTRUCTIONS = "instructions.ts";
-export const MAIN_INSTRUCTIONS_STUB = `// main's instructions, from packages/agent-kit/templates (main-instructions.md + workspace-protocol.md),
+export const MAIN_INSTRUCTIONS_STUB = `// main's instructions, from packages/agent-kit/templates (main-instructions.md + the shared sections),
 // through eve-hub (packages/agent-kit/instructions/main.ts). Don't copy them here:
-// workspace-only additions go in instructions/*.md next to this file, appended after these.
+// workspace-only additions go in role/*.md next to this file, inside <role>.
 export { default } from "eve-hub/instructions/main";
 `;
 
@@ -129,8 +146,8 @@ export function isKitReexport(source, module = "instructions/main") {
 
 
 // Where a bot's instructions come from, given its files ({ "instructions.md": text, ... }):
-// main ("kit", "copy", "custom", "conflict", "missing"), or any other bot (the protocol:
-// "kit", "copy", "conflict", "custom", "missing").
+// main ("kit", "copy", "custom", "conflict", "missing"), or any other bot (the shared sections:
+// "kit", "copy", "conflict", "custom", "missing"; "kit" also for a role.md with its instructions.ts stub).
 const PROTOCOL_HEADING = /^## How this workspace works\s*$/m;
 export function instructionsSource(files, main) {
   const has = (file) => typeof files[file] === "string";
@@ -139,6 +156,11 @@ export function instructionsSource(files, main) {
     if (has(MAIN_INSTRUCTIONS)) return isKitReexport(files[MAIN_INSTRUCTIONS]) ? "kit" : "custom";
     return has("instructions.md") ? "copy" : "missing";
   }
+  if (has(MAIN_INSTRUCTIONS)) {
+    if (has("instructions.md")) return "conflict";
+    const code = files[MAIN_INSTRUCTIONS].replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "").trim();
+    return BOT_STUB.test(code) ? "kit" : "custom";
+  }
   const copy = has("instructions.md") && PROTOCOL_HEADING.test(files["instructions.md"]);
   if (!has(PROTOCOL_STUB_FILE)) return copy ? "copy" : "missing";
   if (copy) return "conflict";