From 017a7bbaab3cb63a242969d26f38eade12a26680 Mon Sep 17 00:00:00 2001
From: matthewdias <matthewdias@me.com>
Date: Sun, 13 Sep 2026 14:33:40 -0500
Subject: [PATCH 1/2] Record thread-badges at the version it was released as

The v0.2.0 release bumped its package.json without regenerating the
lockfile, so every install rewrote the workspace entry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 package-lock.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package-lock.json b/package-lock.json
index 617ffb8..ba8a2d7 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2715,7 +2715,7 @@
     },
     "plugins/thread-badges": {
       "name": "bb-plugin-thread-badges",
-      "version": "0.1.0",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
         "@hugeicons/core-free-icons": "^4.1.3",

From 7fe247184f1b3580e1b3baa0e87893727ec3296b Mon Sep 17 00:00:00 2001
From: matthewdias <matthewdias@me.com>
Date: Sun, 13 Sep 2026 14:33:40 -0500
Subject: [PATCH 2/2] File a thread under Planning when a message asks for a
 plan

Filing is the agent's job: it reads the stage table and runs
`bb stages set`. Plan mode is the one moment it cannot, because that is a
mutating shell call, so a thread started with /plan sat in Inbox through
its whole planning session and was only filed once the plan was approved,
by which point the honest stage is Building.

No event or thread field says a turn is a plan. The message does: bb's
plan action is a provider-declared slash command, carried on the send as
a structured command mention. So a message.dispatch hook watches for that
mention opening the message and files the thread under planStageId. It
always proceeds, decides synchronously and moves off the pass, because the
hook is fail-closed and holds a server-wide lock. Command names come from
each provider's composer actions on a background refresh, falling back to
"plan".

Matching the mention rather than the text matters: over 400 recorded
prompts it caught all four plan sends with no false positives, where a
text match on "/plan" flagged 43 messages that only discussed it.

This trigger ships on, unlike the other three. They guess a stage from a
thread's runtime; asking for a plan is the user saying what comes next.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 plugins/workflow-stages/PLUGIN_OVERVIEW.md    |  7 ++
 plugins/workflow-stages/README.md             | 14 +++
 plugins/workflow-stages/app.tsx               | 17 +++-
 plugins/workflow-stages/server.ts             | 99 ++++++++++++++++++-
 .../skills/workflow-stages/SKILL.md           |  6 ++
 plugins/workflow-stages/stages.ts             | 10 ++
 6 files changed, 149 insertions(+), 4 deletions(-)

diff --git a/plugins/workflow-stages/PLUGIN_OVERVIEW.md b/plugins/workflow-stages/PLUGIN_OVERVIEW.md
index 994bb07..8215f4a 100644
--- a/plugins/workflow-stages/PLUGIN_OVERVIEW.md
+++ b/plugins/workflow-stages/PLUGIN_OVERVIEW.md
@@ -25,6 +25,13 @@ turn needs you. Every automatic move skips sticky stages, and "work stops" only
 undoes the move "a turn starts" made, so a thread you filed by hand while it was
 running stays filed.
 
+One automatic move ships on: a message that asks for a plan files its thread
+under Planning. Filing is otherwise the agent's job, and plan mode is the one
+moment an agent may not do it — `bb stages set` is a mutating call, and plan
+mode forbids those — so without this a `/plan` thread sits unfiled for the whole
+planning session. It reads the composer's own command mention rather than the
+message text, so a thread that merely discusses `/plan` is not filed.
+
 ## How it works
 
 Ribbon owns the sidebar — rendering, drag-and-drop, manual order, and the stored
diff --git a/plugins/workflow-stages/README.md b/plugins/workflow-stages/README.md
index eb0e05a..ab5083f 100644
--- a/plugins/workflow-stages/README.md
+++ b/plugins/workflow-stages/README.md
@@ -70,6 +70,7 @@ Configured in the same editor:
 | Trigger | Default |
 | --- | --- |
 | A thread with no placement | Inbox |
+| A message asks for a plan | Planning |
 | A turn starts | off |
 | Work stops | off |
 | A question, an approval, or a failed turn | off |
@@ -77,6 +78,19 @@ Configured in the same editor:
 "Work stops" only undoes the move "a turn starts" made, so a thread you filed by
 hand while it was running stays filed. Every automatic move skips sticky stages.
 
+"A message asks for a plan" is the one that ships **on**, because it is the one
+trigger the agent cannot answer for itself. Filing is otherwise the agent's job:
+it reads the stage table below and runs `bb stages set`. In plan mode it may not
+— that is a mutating shell call, and plan mode is the one moment an agent is not
+allowed to make those — so a thread you started with `/plan` would sit in Inbox
+through the whole planning session and only get filed once the plan was
+approved, by which point the honest stage is Building.
+
+Detection is the composer's, not a string match: bb's plan action is a
+provider-declared slash command, and the send carries it as a structured mention
+rather than as text. So a message that merely *talks* about `/plan` is not one,
+and a provider that calls its plan action something else is still recognised.
+
 The last one ships off on purpose. A stage says where the work is; whether it
 needs you is a different axis, and Ribbon already draws that on the row itself.
 Pointing it at a stage means a thread bounces there every time an agent asks a
diff --git a/plugins/workflow-stages/app.tsx b/plugins/workflow-stages/app.tsx
index 087aaf8..fd94b0b 100644
--- a/plugins/workflow-stages/app.tsx
+++ b/plugins/workflow-stages/app.tsx
@@ -447,6 +447,15 @@ function WorkflowSettings() {
             {options(false)}
           </select>
         </Row>
+        <Row label="When a plan is asked for">
+          <select
+            className={cn(FIELD, "max-w-64")}
+            value={state.config.planStageId ?? ""}
+            onChange={(event) => configure({ planStageId: event.target.value || null })}
+          >
+            {options(true)}
+          </select>
+        </Row>
         <Row label="When a turn starts">
           <select
             className={cn(FIELD, "max-w-64")}
@@ -475,9 +484,11 @@ function WorkflowSettings() {
           </select>
         </Row>
         <p className="text-sm text-subtle-foreground">
-          A question, an approval, or a failed turn counts as needing you. Automatic moves skip
-          any stage marked <em>only the user files here</em>, and "when work stops" only undoes
-          the move "when a turn starts" made.
+          A plan is asked for when a message opens with your provider's plan command, which is
+          the one trigger the agent cannot answer itself. A question, an approval, or a failed
+          turn counts as needing you. Automatic moves skip any stage marked{" "}
+          <em>only the user files here</em>, and "when work stops" only undoes the move "when a
+          turn starts" made.
         </p>
       </div>
     </div>
diff --git a/plugins/workflow-stages/server.ts b/plugins/workflow-stages/server.ts
index 04c254c..2388b3e 100644
--- a/plugins/workflow-stages/server.ts
+++ b/plugins/workflow-stages/server.ts
@@ -9,7 +9,11 @@
 // plugin — `getGroupingCatalogV1` — plus the placement calls in ribbon.ts.
 // Nothing has to be registered with Ribbon, and nothing here replaces bb's
 // sidebar.
-import { defineRpcContract, type BbPluginApi } from "@get-bb/plugin-sdk";
+import {
+  defineRpcContract,
+  type BbPluginApi,
+  type PluginDispatchInput,
+} from "@get-bb/plugin-sdk";
 import { z } from "zod";
 import { GLYPHS, GLYPH_NAMES, GROUPING_GLYPH } from "./icons";
 import {
@@ -179,6 +183,15 @@ export default async function plugin(bb: BbPluginApi) {
       const suffix = marks.length === 0 ? "" : ` (${marks.join(", ")})`;
       lines.push(`- ${stage.id} — ${stage.label}${suffix}: ${stage.description || "No rule set."}`);
     }
+    const planStage = config.planStageId === null ? null : store.get(config.planStageId);
+    if (planStage !== null) {
+      lines.push(
+        "",
+        `A message that asks for a plan files the thread under ${planStage.label} on its own,`,
+        "before you read this. Rule 1 is already satisfied there — leave it, and move it on",
+        "when the plan is agreed and you start building.",
+      );
+    }
     lines.push(
       "",
       "A stage marked user-only is the user's call: never file into or out of one —",
@@ -269,6 +282,90 @@ export default async function plugin(bb: BbPluginApi) {
     }
   }
 
+  // ------------------------------------------------------------- plan mode
+
+  // Nothing on a thread says "this one is planning": no event carries it, and
+  // `ThreadResponse` has no field for it. The message does. bb's plan composer
+  // action is a provider-declared slash command, so a plan-mode send arrives
+  // as a text block whose leading mention is that command — which is why this
+  // hangs off the dispatch hook rather than off `bb.events`.
+  //
+  // The agent cannot file itself here even though the instructions ask it to:
+  // `bb stages set` is a mutating shell call, and plan mode is the one moment
+  // an agent is not allowed to make those. So the plugin does it instead.
+  const FALLBACK_PLAN_COMMANDS: ReadonlySet<string> = new Set(["plan"]);
+  let planCommands: ReadonlySet<string> = FALLBACK_PLAN_COMMANDS;
+  let planCommandsReadAt = 0;
+  /** Long enough that installing a provider mid-session is picked up. */
+  const PLAN_COMMAND_TTL_MS = 5 * 60 * 1000;
+
+  /**
+   * Ask each provider what it calls its plan action, so this recognises a
+   * provider that named it something other than "plan". Never awaited from the
+   * hook: the dispatch pass holds a server-wide lock, so it reads whatever the
+   * last refresh left and the first send of a session runs on the fallback.
+   */
+  async function refreshPlanCommands(): Promise<void> {
+    planCommandsReadAt = Date.now();
+    try {
+      const names = new Set(FALLBACK_PLAN_COMMANDS);
+      for (const provider of await bb.sdk.providers.list()) {
+        for (const action of provider.composerActions) {
+          if (action.kind === "plan") names.add(action.command.name);
+        }
+      }
+      planCommands = names;
+    } catch (cause) {
+      // Bind-gated before the server is listening, and a provider list is not
+      // worth failing a send over. The fallback still names Claude Code's.
+      bb.log.debug(
+        `plan command refresh skipped: ${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    }
+  }
+
+  /**
+   * A plan send, told from an ordinary one. The mention must open the message —
+   * the composer prepends the command — and be a command rather than a skill,
+   * so a skill that happens to be called "plan" does not file the thread.
+   */
+  function isPlanDispatch(input: PluginDispatchInput): boolean {
+    return input.blocks.some(
+      (block) =>
+        block.type === "text" &&
+        block.mentions.some(
+          (mention) =>
+            mention.start === 0 &&
+            mention.resource.kind === "command" &&
+            mention.resource.source === "command" &&
+            planCommands.has(mention.resource.name),
+        ),
+    );
+  }
+
+  bb.experimental_hooks.on("message.dispatch", (context) => {
+    // Fail-closed, time-boxed, and holding a lock every other send queues
+    // behind: decide synchronously, never throw, and let the move happen off
+    // the pass. The answer is always the same one — this hook watches, it does
+    // not gate. Re-running on a drain or a retry is harmless because moving a
+    // thread to the stage it is already in is a no-op.
+    try {
+      if (isPlanDispatch(context.input)) {
+        void automaticMove(context.thread.id, store.config().planStageId);
+      }
+      if (Date.now() - planCommandsReadAt > PLAN_COMMAND_TTL_MS) {
+        void refreshPlanCommands();
+      }
+    } catch (cause) {
+      bb.log.debug(
+        `plan filing skipped: ${cause instanceof Error ? cause.message : String(cause)}`,
+      );
+    }
+    return { action: "proceed" };
+  });
+
+  // ------------------------------------------------------------ transitions
+
   bb.events.on("thread.active", ({ thread }) => {
     void automaticMove(thread.id, store.config().activeStageId);
   });
diff --git a/plugins/workflow-stages/skills/workflow-stages/SKILL.md b/plugins/workflow-stages/skills/workflow-stages/SKILL.md
index 2c3bb7c..1fe28c8 100644
--- a/plugins/workflow-stages/skills/workflow-stages/SKILL.md
+++ b/plugins/workflow-stages/skills/workflow-stages/SKILL.md
@@ -38,6 +38,12 @@ yet, so the evidence rule below would say "wait" — and a whole planning sessio
 would pass with the thread sitting where nobody can see it was picked up. Decide
 from what you are about to do, not from what has happened.
 
+The exception is plan mode, which files itself. A message sent with the plan
+command moves its thread to the planning stage before you read anything, because
+you could not do it yourself there — `bb stages set` mutates, and plan mode
+forbids that. So in a plan-mode turn the first move is already made: leave it,
+and move the thread on when the plan is agreed and you start building.
+
 If no stage describes what you are about to do — a question, a code read, a
 chore that fits none of them — leave the thread in the default stage. That
 escape is for no stage fitting. It is not for being unsure which of two fits:
diff --git a/plugins/workflow-stages/stages.ts b/plugins/workflow-stages/stages.ts
index b2c9637..c91adc2 100644
--- a/plugins/workflow-stages/stages.ts
+++ b/plugins/workflow-stages/stages.ts
@@ -38,6 +38,8 @@ export const configSchema = z
     idleStageId: z.string().nullable(),
     /** Entered when the agent asks a question or a turn fails. */
     attentionStageId: z.string().nullable(),
+    /** Entered when a message asks the provider for a plan. */
+    planStageId: z.string().nullable(),
   })
   .strict();
 export type WorkflowConfig = z.output<typeof configSchema>;
@@ -122,11 +124,18 @@ const SEED: ReadonlyArray<SeedStage> = [
 // already draws per row. Filing a question-asking thread back to the default
 // stage would undo the first move on every clarification, so the attention
 // bounce ships off and stays a setting for anyone who wants that queue.
+//
+// Plan mode is the exception that ships on. The other three read a thread's
+// runtime — busy, idle, waiting — and guess a workflow position from it, which
+// is why they are off by default. Asking for a plan is not a guess: the user
+// said what the next stretch of work is, and Planning is the stage that says
+// it back.
 const DEFAULT_CONFIG: WorkflowConfig = {
   defaultStageId: "inbox",
   activeStageId: null,
   idleStageId: null,
   attentionStageId: null,
+  planStageId: "planning",
 };
 
 /** A stored icon is only as trustworthy as whatever wrote it. */
@@ -218,6 +227,7 @@ export function createStageStore(database: BetterSqlite3.Database): StageStore {
       activeStageId: resolve("activeStageId", DEFAULT_CONFIG.activeStageId),
       idleStageId: resolve("idleStageId", DEFAULT_CONFIG.idleStageId),
       attentionStageId: resolve("attentionStageId", DEFAULT_CONFIG.attentionStageId),
+      planStageId: resolve("planStageId", DEFAULT_CONFIG.planStageId),
     };
   }
   function writeConfig(patch: Partial<WorkflowConfig>): WorkflowConfig {