eve-hub 0.16.48 → 0.16.50

package/brief/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: brief
+description: How to write a brief for the human's yes. Load before you post a brief or a revised brief, so it reads cold, in plain paragraphs, with the build detail kept apart.
+---
+
+# Writing a brief
+
+A brief asks the human for a yes before anything is built. The human reads it cold, between other threads, often hours or days after they asked. They read the post first and open the document only if the post leaves them unsure. They own the product and are a senior engineer, so they follow any technical argument. What they don't have is your last hour: they don't remember PR numbers, the labels you coined while researching, the names of functions, or the wording of something they decided last week. Everything below follows from that.
+
+A brief leads with its impact for the human: the measured change (latency, CPU, cost, steps), or the named work it unblocks with that work's number. A step with no measured impact is offered to the human as optional and never built by default. The post's first sentence states the impact, and the brief states it right after its opening paragraph's reading of their ask.
+
+## Two documents, two readers
+
+A brief is for the human alone: it is the document they read to decide. The build spec is a second document for the builder, and it is never part of the brief. Write them separately, because the human decides and the builder builds, and each needs different things.
+
+The brief is prose, and the human can say yes or no after reading only it. 500 words is the ceiling, not the target: a small change needs a hundred, and the scale rule still holds (three lines for a copy fix, with no build spec at all).
+
+The build spec is a separate file that you write after the human's yes, or while they decide, and link in the handoff post to the builder, not in the post to the human. It holds the required behavior, how it works today with `file:line`, each PR or moving part, every consumer of anything that moves or is removed, and the real-path test. Exact names lead there, and it can be as dense as the builder needs.
+
+## What the brief says
+
+Write it the way you would explain it to the human across a desk, in paragraphs, in this order, each one leading to the next:
+
+1. What they asked, quoted or closely paraphrased, with a link to their message when you have one, and how you read it. If you narrowed the goal or changed it, say so here. A wrong reading caught in the first paragraph costs the human one reply. Caught after the build, it costs a PR.
+2. What happens today, described as what they or a user sees, and the cause in a sentence or two.
+3. What you propose and what will be different afterwards, with the number when there is one. If there was a real alternative, say why you didn't pick it.
+4. What it costs: how many PRs, what could go wrong, and anything the human has to do themselves.
+5. What you need from the human: the one decision, with your recommendation.
+
+Explain, don't list. The reasoning lives in the words that join sentences (because, so, but, which means, the catch is), so keep them. A run of short flat statements makes the human rebuild the argument themselves. Join two facts only when one causes or qualifies the other, and stop the sentence there, because a sentence that carries four facts is as hard to follow as four that carry none of the reasoning. Use a bullet list only for items that are parallel, such as three PRs or four steps they must take, and a table only for numbers to compare. A page this short needs no section headings.
+
+Say what a thing does before you say what it is called. Write "the check that runs before every deploy (`validateMemory`)", not "`validateMemory` runs first". Add the identifier in parentheses only when the human might search for it. In the brief a file, function or flag is never the subject of a sentence.
+
+Name options, steps and parts by what they do, every time, in the document, the post and the ask buttons. "Sign the app" and "the PR that refuses a status post with no tracker row" can be read cold. "Option B", "step 3", "gate G0b" and "the refusal PR" cannot.
+
+The human does not remember history, so restate it. For a past decision, an earlier brief, another thread or a PR, say in a clause what it was or what it concluded, then link it. Write "the three things you said on Nov 1 must work before the beta: a signed app, access without the playground team, and connections that work for a new user", not "the three beta gates you set on Nov 1".
+
+Team words (kit, ledger, seed, real-path test, the vision's measures) are ours, not the human's. Use the plain phrase the first time: "the package every bot's prompt and tools are built from (the kit)".
+
+When a standing rule asks the brief to state something, say it as part of the argument in plain words. "This should cut the questions you ask about what the Artifacts pane shows. You asked three this week." carries the vision measure. "Vision goal 1: this moves Maximizes understanding. It moves none of the other three measures." is a form entry, and it belongs in the build spec. The brief still says in plain words which of the vision's four measures the change moves and by how much, or that it moves none.
+
+Headings in the build spec are sentence case and name the topic literally ("How the broker issues tokens"), never wordplay ("What the broker brokers"), with no uppercase eyebrow or kicker label above them ("THE BUILD", "SCOPE"). Write without metaphors or personification ("two front doors", "the hub hands off"): say what the thing does in plain words, then give its exact name ("two endpoints that each run as a different principal, `/a` and `/b`").
+
+## A revised brief
+
+A revision is any brief that follows an earlier one in the same thread, including one that answers the human's question about it. It is a new document that stands alone, because the human does not remember the previous version. Open with one sentence that says what changed and why ("You said the tracker row should be optional, so I removed the PR that refused a status post without one. The rest is as before."). Then give the whole brief again.
+
+## The post
+
+The post is what the human reads first, and often it is all they read, so it gets the most care, not the least. It is the brief in miniature: what they asked, what you propose, what you need. Every rule above about names, labels, history and team words applies to each sentence of it, and the usual length limits for a post still hold. If a phrase such as "the rule already live here" or "the review PR" would make the human ask "which one?", say which one. Each ask button names its option by what it does.
+
+## Read it cold before posting
+
+You can't see your own context, so have a reader with none of it read the brief. Use your `reader` subagent; a bot without one (main) uses an `agent` copy. Give it only three things: the post, the brief, and the human's message that asked for it. Load the `fanout` skill for the task shape, and send the task below with the three pasted in.
+
+````text
+goal: Read this brief the way its human reader does, cold, and say what they cannot resolve from it alone. This is a reading task with a fixed output: do not rewrite the brief or propose fixes.
+
+owns: nothing. Change no file. Post nothing to any thread (never call post_message, react, update_thread or show). Never call git__gh. Do not open code repositories or threads; judge only from the three texts below.
+
+facts:
+- A brief is a proposal a planning bot wrote for one human, asking for their yes before anything is built. The human owns the product the brief is about and is a senior engineer who knows it in general. They run dozens of threads, give each a few minutes, and read each brief cold. They do not remember PR numbers, step or option labels from other threads, internal code identifiers, or the wording of decisions they made days ago.
+- A reference is "unresolved" when both hold: (1) they need it to understand what is proposed or what they are deciding, and (2) where it first appears it is neither explained in plain words (in that sentence or earlier in the same text) nor a link whose label says what the target is. Kinds:
+  - "pr": a PR or issue number with no words saying what it does.
+  - "label": a coined label such as a gate, step, option, phase or part name ("G0b", "option A", "step 14", "PR B") used before it is defined.
+  - "code": a code identifier, file or flag used as the subject of what is proposed, with no plain-words gloss. Count these only in the post and in the brief.
+  - "past": a past decision, event or conversation they are assumed to remember, with no link and no restatement.
+  - "elsewhere": another thread, doc or brief referred to without a link or without saying what it concluded.
+  - "jargon": a team term used as if known ("real-path test", "the ledger", "kit") with no gloss. List each distinct term once.
+- Texts: POST (the chat post the human sees first), PAGE (the brief document), REQUEST (the human's message that asked for the brief).
+
+return, and nothing else:
+- decision: one sentence, what exactly they are asked to say yes to.
+- premise: "matches", "narrower", "different" or "cannot tell", with at most 25 words comparing the brief's stated goal to their own words in REQUEST.
+- unresolved: a list, one line each: where (post or page), kind, the verbatim quote (at most 20 words), why (at most 15 words). At most 15, the ones that matter most to the decision; give the total if there are more.
+
+budget: one pass, no tool calls beyond reading what you were given.
+stop: if a text is missing, say which and stop.
+````
+
+Fix every reference it lists, then check its one-sentence decision against the one you meant, and rewrite the opening if they differ. Anything unresolved in the post must reach zero before you post. Then run a second read with a fresh reader (not the same task continued), fix what it lists, and post, even if the page still has an item or two. List what is left at the end of the brief. If a read returns no response, retry it with a fresh reader; the retry is the same read. If the retry also returns nothing, post anyway and say in the brief that the cold read didn't run. Never read a third time: a reader finds something new on every pass, so the second read is the last.
+
+## Example
+
+The passage below is from a real brief. The human's reply to it was "what 3 beta gates?".
+
+Before:
+
+> **Release.** The three beta gates you set on Nov 1 have had no merged work since Nov 2. This plan clears all three by Wednesday and puts tester 0 (Chad) on a fresh install Thursday.
+
+After:
+
+> On Nov 1 you said three things must work before anyone outside the team gets Hub: the Mac app is signed, so it opens without a security warning, a new person can get in without being added to the playground team, and their connections work on first sign-in. None of the 263 PRs merged since then touched any of the three, because nothing ranks new asks against the release. This plan finishes all three by Wednesday, so that Chad, the first outside tester, can install from scratch on Thursday.
+
+The example shows the register, not a template. Don't copy its wording or its length.

package/kit-modules.json

@@ -13,6 +13,7 @@
   "schedules/tracker-prs",
   "schedules/wake",
   "schedules/workspace-review",
+  "skills/brief",
   "skills/deep-dive",
   "skills/fanout",
   "skills/forms",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.16.48",
+  "version": "0.16.50",
   "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",

package/skills/brief.d.ts

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

package/skills/brief.gen.mjs

@@ -0,0 +1,2 @@
+// Generated by scripts/build-onboarding.mjs from brief/SKILL.md. Do not edit.
+export default {"description":"How to write a brief for the human's yes. Load before you post a brief or a revised brief, so it reads cold, in plain paragraphs, with the build detail kept apart.","content":"# Writing a brief\n\nA brief asks the human for a yes before anything is built. The human reads it cold, between other threads, often hours or days after they asked. They read the post first and open the document only if the post leaves them unsure. They own the product and are a senior engineer, so they follow any technical argument. What they don't have is your last hour: they don't remember PR numbers, the labels you coined while researching, the names of functions, or the wording of something they decided last week. Everything below follows from that.\n\nA brief leads with its impact for the human: the measured change (latency, CPU, cost, steps), or the named work it unblocks with that work's number. A step with no measured impact is offered to the human as optional and never built by default. The post's first sentence states the impact, and the brief states it right after its opening paragraph's reading of their ask.\n\n## Two documents, two readers\n\nA brief is for the human alone: it is the document they read to decide. The build spec is a second document for the builder, and it is never part of the brief. Write them separately, because the human decides and the builder builds, and each needs different things.\n\nThe brief is prose, and the human can say yes or no after reading only it. 500 words is the ceiling, not the target: a small change needs a hundred, and the scale rule still holds (three lines for a copy fix, with no build spec at all).\n\nThe build spec is a separate file that you write after the human's yes, or while they decide, and link in the handoff post to the builder, not in the post to the human. It holds the required behavior, how it works today with `file:line`, each PR or moving part, every consumer of anything that moves or is removed, and the real-path test. Exact names lead there, and it can be as dense as the builder needs.\n\n## What the brief says\n\nWrite it the way you would explain it to the human across a desk, in paragraphs, in this order, each one leading to the next:\n\n1. What they asked, quoted or closely paraphrased, with a link to their message when you have one, and how you read it. If you narrowed the goal or changed it, say so here. A wrong reading caught in the first paragraph costs the human one reply. Caught after the build, it costs a PR.\n2. What happens today, described as what they or a user sees, and the cause in a sentence or two.\n3. What you propose and what will be different afterwards, with the number when there is one. If there was a real alternative, say why you didn't pick it.\n4. What it costs: how many PRs, what could go wrong, and anything the human has to do themselves.\n5. What you need from the human: the one decision, with your recommendation.\n\nExplain, don't list. The reasoning lives in the words that join sentences (because, so, but, which means, the catch is), so keep them. A run of short flat statements makes the human rebuild the argument themselves. Join two facts only when one causes or qualifies the other, and stop the sentence there, because a sentence that carries four facts is as hard to follow as four that carry none of the reasoning. Use a bullet list only for items that are parallel, such as three PRs or four steps they must take, and a table only for numbers to compare. A page this short needs no section headings.\n\nSay what a thing does before you say what it is called. Write \"the check that runs before every deploy (`validateMemory`)\", not \"`validateMemory` runs first\". Add the identifier in parentheses only when the human might search for it. In the brief a file, function or flag is never the subject of a sentence.\n\nName options, steps and parts by what they do, every time, in the document, the post and the ask buttons. \"Sign the app\" and \"the PR that refuses a status post with no tracker row\" can be read cold. \"Option B\", \"step 3\", \"gate G0b\" and \"the refusal PR\" cannot.\n\nThe human does not remember history, so restate it. For a past decision, an earlier brief, another thread or a PR, say in a clause what it was or what it concluded, then link it. Write \"the three things you said on Nov 1 must work before the beta: a signed app, access without the playground team, and connections that work for a new user\", not \"the three beta gates you set on Nov 1\".\n\nTeam words (kit, ledger, seed, real-path test, the vision's measures) are ours, not the human's. Use the plain phrase the first time: \"the package every bot's prompt and tools are built from (the kit)\".\n\nWhen a standing rule asks the brief to state something, say it as part of the argument in plain words. \"This should cut the questions you ask about what the Artifacts pane shows. You asked three this week.\" carries the vision measure. \"Vision goal 1: this moves Maximizes understanding. It moves none of the other three measures.\" is a form entry, and it belongs in the build spec. The brief still says in plain words which of the vision's four measures the change moves and by how much, or that it moves none.\n\nHeadings in the build spec are sentence case and name the topic literally (\"How the broker issues tokens\"), never wordplay (\"What the broker brokers\"), with no uppercase eyebrow or kicker label above them (\"THE BUILD\", \"SCOPE\"). Write without metaphors or personification (\"two front doors\", \"the hub hands off\"): say what the thing does in plain words, then give its exact name (\"two endpoints that each run as a different principal, `/a` and `/b`\").\n\n## A revised brief\n\nA revision is any brief that follows an earlier one in the same thread, including one that answers the human's question about it. It is a new document that stands alone, because the human does not remember the previous version. Open with one sentence that says what changed and why (\"You said the tracker row should be optional, so I removed the PR that refused a status post without one. The rest is as before.\"). Then give the whole brief again.\n\n## The post\n\nThe post is what the human reads first, and often it is all they read, so it gets the most care, not the least. It is the brief in miniature: what they asked, what you propose, what you need. Every rule above about names, labels, history and team words applies to each sentence of it, and the usual length limits for a post still hold. If a phrase such as \"the rule already live here\" or \"the review PR\" would make the human ask \"which one?\", say which one. Each ask button names its option by what it does.\n\n## Read it cold before posting\n\nYou can't see your own context, so have a reader with none of it read the brief. Use your `reader` subagent; a bot without one (main) uses an `agent` copy. Give it only three things: the post, the brief, and the human's message that asked for it. Load the `fanout` skill for the task shape, and send the task below with the three pasted in.\n\n````text\ngoal: Read this brief the way its human reader does, cold, and say what they cannot resolve from it alone. This is a reading task with a fixed output: do not rewrite the brief or propose fixes.\n\nowns: nothing. Change no file. Post nothing to any thread (never call post_message, react, update_thread or show). Never call git__gh. Do not open code repositories or threads; judge only from the three texts below.\n\nfacts:\n- A brief is a proposal a planning bot wrote for one human, asking for their yes before anything is built. The human owns the product the brief is about and is a senior engineer who knows it in general. They run dozens of threads, give each a few minutes, and read each brief cold. They do not remember PR numbers, step or option labels from other threads, internal code identifiers, or the wording of decisions they made days ago.\n- A reference is \"unresolved\" when both hold: (1) they need it to understand what is proposed or what they are deciding, and (2) where it first appears it is neither explained in plain words (in that sentence or earlier in the same text) nor a link whose label says what the target is. Kinds:\n  - \"pr\": a PR or issue number with no words saying what it does.\n  - \"label\": a coined label such as a gate, step, option, phase or part name (\"G0b\", \"option A\", \"step 14\", \"PR B\") used before it is defined.\n  - \"code\": a code identifier, file or flag used as the subject of what is proposed, with no plain-words gloss. Count these only in the post and in the brief.\n  - \"past\": a past decision, event or conversation they are assumed to remember, with no link and no restatement.\n  - \"elsewhere\": another thread, doc or brief referred to without a link or without saying what it concluded.\n  - \"jargon\": a team term used as if known (\"real-path test\", \"the ledger\", \"kit\") with no gloss. List each distinct term once.\n- Texts: POST (the chat post the human sees first), PAGE (the brief document), REQUEST (the human's message that asked for the brief).\n\nreturn, and nothing else:\n- decision: one sentence, what exactly they are asked to say yes to.\n- premise: \"matches\", \"narrower\", \"different\" or \"cannot tell\", with at most 25 words comparing the brief's stated goal to their own words in REQUEST.\n- unresolved: a list, one line each: where (post or page), kind, the verbatim quote (at most 20 words), why (at most 15 words). At most 15, the ones that matter most to the decision; give the total if there are more.\n\nbudget: one pass, no tool calls beyond reading what you were given.\nstop: if a text is missing, say which and stop.\n````\n\nFix every reference it lists, then check its one-sentence decision against the one you meant, and rewrite the opening if they differ. Anything unresolved in the post must reach zero before you post. Then run a second read with a fresh reader (not the same task continued), fix what it lists, and post, even if the page still has an item or two. List what is left at the end of the brief. If a read returns no response, retry it with a fresh reader; the retry is the same read. If the retry also returns nothing, post anyway and say in the brief that the cold read didn't run. Never read a third time: a reader finds something new on every pass, so the second read is the last.\n\n## Example\n\nThe passage below is from a real brief. The human's reply to it was \"what 3 beta gates?\".\n\nBefore:\n\n> **Release.** The three beta gates you set on Nov 1 have had no merged work since Nov 2. This plan clears all three by Wednesday and puts tester 0 (Chad) on a fresh install Thursday.\n\nAfter:\n\n> On Nov 1 you said three things must work before anyone outside the team gets Hub: the Mac app is signed, so it opens without a security warning, a new person can get in without being added to the playground team, and their connections work on first sign-in. None of the 263 PRs merged since then touched any of the three, because nothing ranks new asks against the release. This plan finishes all three by Wednesday, so that Chad, the first outside tester, can install from scratch on Thursday.\n\nThe example shows the register, not a template. Don't copy its wording or its length.\n"};

package/skills/brief.js

@@ -0,0 +1,6 @@
+import { defineSkill } from "eve/skills";
+import skill from "./brief.gen.mjs";
+// The brief skill: brief/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 says when a brief is
+// owed; the skill says how to write it and how to read it cold before posting.
+export default defineSkill(skill);

package/stubs.mjs

@@ -19,6 +19,7 @@ export const KIT_FILES = {
   "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."],
+  "skills/brief.ts": ["The brief skill (packages/agent-kit/brief/SKILL.md): how to write a brief for the human's yes and read it cold before posting."],
   "skills/fanout.ts": ["The fanout skill (packages/agent-kit/fanout/SKILL.md): the contract for handing work to the reader, editor and verifier subagents."],
   "skills/local-onboarding.ts": ["The local-onboarding skill (packages/agent-kit/local-onboarding/SKILL.md): the Mac half of onboarding, the live work to port and the sandbox setup."],
 };
@@ -66,6 +67,7 @@ export const DEPLOYED_KIT_FILES = new Set([
   "memory/team.ts",
   "skills/forms.ts",
   "skills/fanout.ts",
+  "skills/brief.ts",
   ...["create_thread", "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`),
 ]);
 

package/team.mjs

@@ -24,7 +24,7 @@ export const FLOW = [
   { from: "coordinator", to: "planner", kind: "route", text: "hands it over when the scope or the cause is unclear" },
   { from: "coordinator", to: "builder", kind: "route", text: "hands it over when it is clear and small" },
   { from: "planner", to: "human", text: "posts the brief to confirm; nothing is built before the yes" },
-  { from: "planner", to: "builder", kind: "plan", text: "hands over the confirmed brief" },
+  { from: "planner", to: "builder", kind: "plan", text: "hands over the build spec for the confirmed brief" },
   { from: "builder", to: "reviewer", kind: "build", text: "hands over the PR and head sha, what is proven and how" },
   { from: "reviewer", to: "builder", kind: "fixfirst", text: "sends fix-first back to the builder that posted the build" },
   { from: "reviewer", to: "planner", text: "sends rethink back to the planner" },

package/templates/engineering.md

@@ -3,7 +3,7 @@
   - Question it again whenever two fixes on one idea fail.
   - Why: a correct fix for the wrong problem costs a full build and review, then a second one.
 - **Brief before building**
-  - The owner posts a brief, scaled to the change (three lines for a copy fix). It leads with its impact for the human: the measured change (latency, CPU, cost, steps), or the named work it unblocks with that work's number. Then the required behavior in the human's words, how it works today (file:line), every PR, repo or moving part it adds, and the real-path test.
+  - The owner posts a brief, scaled to the change (three lines for a copy fix). Load the `brief` skill before writing one.
   - A step or PR with no measured impact, schema cleanup that only tidies included, is offered to the human as optional, never built by default.
   - Building waits for the human's yes, even while they're offline; meanwhile do the research, the repro and the draft. Picking an option that names what gets built counts as a yes.
   - Build only what the brief names; within it, make the sensible call on details and say which you made.