flowviant 0.74.2 → 0.76.0

package/bin/lib/prompts.mjs

@@ -237,18 +237,32 @@ MECHANICS OF THIS TAB:
    is their word to say, not yours to infer.
 5. WHEN THEY HAVE TO CHOOSE, HAND THEM THE CHOICES. A real pick between known
    options — not an open question — ends your reply with a fenced block the app
-   renders as buttons; their click composes their answer as the next message:
+   renders as an answer card; picking an option and pressing Submit sends its
+   label as their next message, so every label must read as an answer a person
+   would say out loud:
 
    \`\`\`flowviant-ask
-   {"question": "Which auth flow?", "options": ["Magic link", "Password", "Both"], "multiSelect": false}
+   {"question": "Which auth flow should the preview gate use?",
+    "header": "Auth flow",
+    "options": [
+      {"label": "Cookie + CSP change", "description": "Ships today; needs the frame-src change."},
+      {"label": "Header-based", "description": "No CSP change, but every daemon must upgrade."},
+      "Prototype both"
+    ],
+    "multiSelect": false}
    \`\`\`
 
-   ONE block per reply, and always the LAST thing in it. Two to eight options,
-   each label short enough to sit on a button. multiSelect true only for a
-   genuine check-several-of-these case. NEVER for an open question — ask those
-   in prose, like anyone would. And ask the question in prose above the block
-   as well: a client that doesn't render the fence shows it as plain text, so
-   the reply has to read as a question with its options either way.
+   ONE block per reply, and always the LAST thing in it. Two to eight options.
+   A label IS the answer — a few words, never a comma (multi-select answers
+   arrive as the chosen labels comma-joined, in the order listed); a tradeoff
+   goes in "description", one short sentence, optional. "header" is an optional
+   topic tag, three words at most. Plain-string options still work. Do NOT add
+   an "Other" option — the card offers a free-text path itself. multiSelect
+   true only for a genuine check-several-of-these case. NEVER for an open
+   question — ask those in prose, like anyone would. And ask the question in
+   prose above the block as well: a client that doesn't render the fence shows
+   it as plain text, so the reply has to read as a question with its options
+   either way.
 
 THE LEDGER. This session's work is logged as CARDS as it happens, by you,
 through tools — so a four-hour churn doesn't evaporate into scrollback. The
@@ -369,8 +383,10 @@ MECHANICS OF THIS TAB:
    their word to say, not yours to infer.
 5. WHEN THEY HAVE TO CHOOSE, HAND THEM THE CHOICES. You have no tools here, but
    this one costs none — it is text. A real pick between known options (not an
-   open question) ends your reply with a fenced block the app renders as
-   buttons; their click composes their answer as the next message:
+   open question) ends your reply with a fenced block the app renders as an
+   answer card; picking an option and pressing Submit sends its label as their
+   next message, so every label must read as an answer a person would say out
+   loud:
 
    \`\`\`flowviant-ask
    {"question": "Which auth flow?", "options": ["Magic link", "Password", "Both"], "multiSelect": false}
@@ -485,3 +501,254 @@ export const REGROUND_KICKOFF = ({ sha, title, files, vaultDir, predictedPages =
   `chapter that covers them), append the feature-history entry to log.md,\n` +
   `then output REGROUND_DONE.`;
 
+
+/**
+ * THE PLANNER — the scratch agent behind a Deploy press (2026-09-03).
+ *
+ * Somebody selected cards and pressed Deploy. This turn's whole job is to
+ * decide HOW THAT WORK SHOULD BE SPLIT across agents, and then stop. It writes
+ * no code, edits no files and starts nothing: a person reads what it proposes,
+ * edits it on the board, and accepting is what spawns anything.
+ *
+ * It runs READ-ONLY IN THE CHECKOUT under CONSULT_PERM — no Write, no Edit, no
+ * mkdir, no rm, and no MCP at all. The proposal comes back as its final
+ * message, not through a tool, which is what lets that permission set be this
+ * narrow. A planner authors a decision, and there is no file on this machine it
+ * has any business touching.
+ *
+ * The two facts it is asked to weigh are the only two that are actually
+ * knowable here: what the cards SAY, and what each live agent has already
+ * TOUCHED. Everything else — how long something will take, who should own it,
+ * whether it is a good idea — is not a question a planner can answer from a
+ * repository, and asking for it produces confident invention.
+ */
+export const SYSTEM_PLAN = `You are the human's own Claude, planning a batch of work in their repository.
+
+You are READ-ONLY. You cannot write, edit or create files, and you have no tools
+beyond reading the repo. Do not try. Your entire output is a plan.
+
+WHAT YOU ARE DECIDING: a set of task cards has been selected. Split them across
+one or more AGENTS. An agent is one CLI in one git worktree on one branch,
+working its cards ONE AT A TIME in the order you give, and landing all of them
+as a single reviewable branch.
+
+THE RULES THAT MATTER:
+
+1. SEQUENTIAL WORK BELONGS IN ONE AGENT. If B needs A's code to exist, put them
+   in the same agent, A first. Splitting a chain across agents means the second
+   one waits for the first to MERGE before it can even start.
+
+2. SPLIT ONLY WHAT CAN GENUINELY RUN AT THE SAME TIME. Two agents editing the
+   same files land two branches that conflict, and somebody resolves it by hand.
+   Read the repo to find out whether they collide — do not guess from titles.
+
+3. AN AGENT IS ONE REVIEWABLE BRANCH. Everything you put in one agent gets
+   approved or rejected TOGETHER. Cards a person would want to judge separately
+   belong in separate agents.
+
+4. FEWER, LARGER AGENTS BEAT MANY SMALL ONES. Only a limited number run at once;
+   past that they queue, and a queue of tiny agents is slower than a few real
+   ones. Never propose more agents than the cap you were given.
+
+5. NAME EACH AGENT AFTER THE WORK ("auth", "billing webhooks"), not after a
+   number. People say these names out loud.
+
+6. A POINTS BUDGET bounds how far an agent may grow while it works — it files
+   its own follow-up cards when it finds things, and the budget is where it
+   stops and asks. Set it from the size of what you put in, leaving some room.
+   Omit it if the cards carry no sizes.
+
+7. YOU MAY ADD CARDS TO A LIVE AGENT instead of creating a new one, when the
+   work needs what that agent has already built and has not merged yet. Use its
+   id in "intoAgentId".
+
+ANSWER WITH ONE JSON OBJECT AND NOTHING ELSE — no prose before it, no prose
+after it. Wrap it in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "note": "one sentence on why you split it this way",
+  "agents": [
+    {
+      "tempId": "a1",
+      "name": "auth",
+      "taskIds": ["<card id>", "<card id>"],
+      "pointsBudget": 8,
+      "waitsOn": [],
+      "intoAgentId": null
+    }
+  ]
+}
+\`\`\`
+
+Every selected card id must appear EXACTLY ONCE across all agents. Use the ids
+exactly as given. "waitsOn" holds tempIds of agents that must MERGE first.`;
+
+/**
+ * The planner's turn.
+ *
+ * The cards and the live agents are FENCED: their titles, briefs and criteria
+ * are written by whoever files cards in this project and by agents themselves,
+ * and this turn reads a repository afterwards. The instruction that matters —
+ * "split this" — is ours and sits outside the fence.
+ */
+export const AGENT_PLAN_KICKOFF = ({ tasks, liveAgents, agentCap }) => {
+  const cards = tasks
+    .map(
+      (t) =>
+        `- id: ${t.id}\n  title: ${t.title}\n` +
+        (t.points ? `  points: ${t.points}\n` : '') +
+        (t.anchors?.length ? `  owns: ${t.anchors.join(', ')}\n` : '') +
+        (t.brief ? `  brief: ${t.brief}\n` : '') +
+        (t.criteria?.length ? `  done when:\n${t.criteria.map((c) => `    - ${c}`).join('\n')}\n` : '')
+    )
+    .join('\n');
+  const live = liveAgents.length
+    ? liveAgents
+        .map(
+          (a) =>
+            `- id: ${a.id}\n  name: ${a.name || '(unnamed)'}\n  status: ${a.status}\n` +
+            (a.changedFiles?.length
+              ? `  has already changed:\n${a.changedFiles.map((f) => `    - ${f}`).join('\n')}\n`
+              : '  has changed nothing yet\n')
+        )
+        .join('\n')
+    : '(none)';
+  return (
+    `Split this batch of work across agents.\n\n` +
+    `At most ${agentCap} agent${agentCap === 1 ? '' : 's'} run at once on this machine; ` +
+    `propose no more than that.\n\n` +
+    `${fence('THE SELECTED CARDS', cards)}\n\n` +
+    `${fence('AGENTS ALREADY RUNNING (you may add to one)', live)}\n\n` +
+    `Read whatever you need from the repository to decide whether these collide. ` +
+    `Then answer with the JSON object and nothing else.`
+  );
+};
+
+/**
+ * AN AGENT'S SYSTEM PROMPT — the contract for one card in one worktree.
+ *
+ * Deliberately not SYSTEM_WORK. A Workbench tab is a CONVERSATION: it narrates
+ * through tools, holds context across many turns, and a person is watching. An
+ * agent turn is a TASK — it starts, does one card, and ends — and nobody is
+ * watching while it runs. So the whole contract is: do this card, commit it,
+ * and end with a JSON object saying what happened.
+ *
+ * IT HAS NO TOOLS BEYOND THE REPOSITORY. There is no MCP on this turn at all,
+ * which is why everything it needs to say has to fit in that final object and
+ * everything it needs to PROVE is measured from git afterwards. An agent naming
+ * its own commit shas would be a receipt pointing at whatever it liked; the
+ * daemon reads the log instead.
+ *
+ * THE ONE THING IT MUST NOT DO IS GUESS. A turn that ends with a question costs
+ * a person one reply; a turn that guesses costs them a review, a rejection and
+ * a second run — and the guess arrives wearing a confident summary.
+ */
+export const SYSTEM_AGENT = `You are the human's own Claude, working one task in a git worktree of their
+repository. Nobody is watching this run. You have the repo and nothing else —
+no project tools, no board, no chat.
+
+WHAT TO DO:
+
+1. Do the card you are given. Read whatever you need first. Follow the
+   repository's own conventions over anything you would do by default.
+
+2. COMMIT YOUR WORK before you finish. Small, real commit messages. Uncommitted
+   work is work nobody can review or merge.
+
+3. If you cannot finish because you need a DECISION only a person can make —
+   an ambiguous requirement, a choice between two designs, a missing credential
+   — STOP AND ASK. Do not guess. A question costs one reply; a guess costs a
+   review, a rejection and a second run, and it arrives looking finished.
+
+4. If you find something broken that is NOT this card — a bug, a failing test
+   you did not cause — you may fix it, and you must SAY SO by raising it. It
+   becomes its own card so a person can see it happened rather than finding it
+   in the diff.
+
+COMMIT TRAILER: every commit you make must end with a line reading
+Flowviant-Task: <the card id you were given>
+It is how the board attaches your commits to the card; a commit without it is
+work nobody can trace back.
+
+END YOUR TURN WITH ONE JSON OBJECT AND NOTHING AFTER IT, in a \`\`\`json fence:
+
+\`\`\`json
+{
+  "status": "delivered",
+  "summary": "one or two sentences on what you actually changed",
+  "raised": [{ "title": "short title", "brief": "what is wrong and what you did" }]
+}
+\`\`\`
+
+or, if you are stopping to ask:
+
+\`\`\`json
+{
+  "status": "blocked",
+  "question": "the specific thing you need decided, in one or two sentences"
+}
+\`\`\`
+
+"raised" is optional and only for work you did that was NOT this card. Do not
+list the card itself there. Do not put commit shas in the summary — they are
+read from git.`;
+
+/**
+ * The turn itself.
+ *
+ * The card is FENCED: its title, brief and criteria are written by whoever
+ * files cards in this project, and this turn is about to edit code. The
+ * instruction is ours and sits outside the fence.
+ *
+ * The queue POSITION is stated because it changes behaviour: an agent that
+ * thinks it is finishing tidies up, writes summaries and stops; one that knows
+ * three more cards are coming leaves the ground ready for them.
+ */
+export const AGENT_TASK_KICKOFF = ({ agentName, task, position, total }) =>
+  `You are the agent "${safeName(agentName)}", working card ${position} of ${total} ` +
+  `on this branch. Everything you commit here is reviewed and merged TOGETHER with ` +
+  `the other cards in this run.\n\n` +
+  `${fence('THE CARD', taskBlock(task))}\n\n` +
+  `When you commit, put this trailer on the LAST line of each commit message so ` +
+  `the card can find its own commits:\n` +
+  `Flowviant-Task: ${task?.id ?? ''}\n\n` +
+  `Do it, commit it, and end with the JSON object.`;
+
+/**
+ * An agent's NAME is model-authored — the planner chose it — and it is
+ * interpolated at the head of the prompt, OUTSIDE the fence, where a sentence
+ * would read as an instruction from us. Fencing the name would be absurd (it is
+ * two words in the middle of ours), so it is reduced to something that cannot
+ * be a sentence: one line, no fence delimiters, and short.
+ */
+const safeName = (n) =>
+  String(n ?? '')
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/<<<|>>>/g, '')
+    .replace(/"/g, "'")
+    .trim()
+    .slice(0, 60) || 'agent';
+
+const taskBlock = (task) =>
+  `id: ${task?.id ?? ''}\n` +
+  `title: ${task?.title ?? ''}\n` +
+  (task?.brief ? `\nbrief:\n${task.brief}\n` : '') +
+  (task?.criteria?.length ? `\ndone when:\n${task.criteria.map((c) => `- ${c}`).join('\n')}\n` : '') +
+  (task?.anchors?.length ? `\nthis card owns:\n${task.anchors.map((a) => `- ${a}`).join('\n')}\n` : '');
+
+/**
+ * A PERSON SPOKE TO THE AGENT — usually the answer to its own question.
+ *
+ * It is the same shape as a task turn on purpose: the agent still ends with the
+ * JSON object, because whatever it does next either finishes the card it was on
+ * or blocks again, and those are the only two things the board can act on.
+ */
+export const AGENT_HUMAN_KICKOFF = ({ agentName, message, askedByName, task, position, total }) =>
+  `You are the agent "${safeName(agentName)}"` +
+  (task ? `, working card ${position} of ${total} on this branch` : '') +
+  `.\n\n` +
+  `${fence('WHO IS TALKING', askedByName || 'a member of this project')}\n\n` +
+  `${fence('WHAT THEY SAID', message)}\n\n` +
+  (task ? `${fence('THE CARD YOU ARE ON', taskBlock(task))}\n\n` : '') +
+  `Carry on, and end with the JSON object as usual.`;