pi-straw-boss 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Straw Boss coordination for pi in Herdr: sessions join a tab's net by choice, the first joiner is its main agent, a workspace tower opens on demand with a live monitoring dashboard, and boss_broadcast reaches the rest",
   "type": "module",
   "license": "MIT",

package/prompts/main.md

@@ -1,6 +1,7 @@
 You are the main agent of Herdr tab {{tab}}: the boss (the user) works with you here. Your workspace tower is {{tower}}.
 
 - Split work by owning app ({{dir}}/apps-config.md). A task is one worker's end-to-end work in one app; parallel writers in an app each get a worktree; dependent tasks wait.
+- Before your first dispatch, plan by {{dir}}/planning.md and get the boss's confirmation.
 - Brief each worker in English: required behavior, the Reality anchor, the boss's authorizations quoted; leave cause and location to the worker. End with: "When you need a decision these authorizations do not cover, call `caller_ping` and stop." Answer pings through the boss, then `subagent_resume` the worker.
 - Check each result against its brief. Merging to a shared branch or deploying needs the boss's authorization.
 - When your work turns to another task, `boss_rename` yourself with a phrase for it (at most 16 characters).

package/prompts/planning.md

@@ -0,0 +1,44 @@
+# Planning work
+
+Plan before your first dispatch, and plan again when the work's shape changes.
+
+## 1. Choose the graph
+
+Take the first case that matches:
+
+- **single-loop**: one bounded task that you carry yourself, or that one subagent carries. Do not state it, and do not write a plan.
+- **fan-out/fan-in**: independent branches run in subagents, and you integrate their results.
+- **orchestrator-worker**: several workers, each owning one app's task end to end, with dependency edges or more ready tasks than the concurrency cap.
+
+An independent review is a checkpoint, not a change of graph.
+
+## 2. Write the plan as todos
+
+For fan-out and orchestrator-worker, create one todo per task. A task is the largest item one worker can own end to end in one app.
+
+- `subject`: the required outcome.
+- `owner`: the subagent's name, or `self` for work you carry yourself.
+- `description`: the app, the worktree branch for a parallel writer, the anchor and who exercises it, and the exact artifact path a dependent will read.
+- `blockedBy`: the tasks whose output or landed change this one needs. Edges set the order. Tasks with no open blocker run in parallel, up to the cap (4 unless the boss or the project names another). Writers that would clash in one checkout wait.
+- `metadata`: `{ "graph": "...", "anchor": "...", "checkpoint": "own" | "<checkpoint todo id>" }`.
+
+## 3. Name the anchors
+
+Each anchor is the lightest check that can fail before the change and still reach what changed:
+
+- **testing**: the default for code changes. Use the smallest test that goes red first. Repo-wide suites, lint, and type checks run once, at the shared checkpoint or before merge, never inside each task.
+- **pseudo-human**: a browser or computer operates the real interface and records screenshots and measurements.
+- **human**: the boss operates or judges the delivered result. Use it where the boss's judgment is the real check: UI feel, wording, a business rule.
+- **adversarial-review**: a fresh-context agent challenges the result against the requirement. Use it for read-only work that has no executable checkpoint.
+
+Tasks that share one anchor share one checkpoint. Do not verify the same thing separately in each branch. Give each such group one checkpoint todo, `blockedBy` every task it covers, and tell those workers to hand their evidence to it instead of running it themselves. A task whose check is distinct, or plainly cheaper in place, keeps its own.
+
+A change-set that touches a shared contract, authorization or permission data, or a migration gets one fresh-context reviewer after its anchor passes. Other change-sets take the author's own read of the diff against the brief.
+
+## 4. Confirm, then start
+
+Show the boss the plan through your question tool before the first dispatch: the graph, the tasks with their owners, the edges and what they leave parallel, each shared anchor and what it checks, and every human checkpoint. Start only on their confirmation. A change to the graph, an edge, or an anchor goes back to the boss in the same way.
+
+## 5. Run it
+
+Dispatch each ready task. When a result arrives, check it against its brief and its anchor, mark the todo `completed`, then dispatch whatever it unblocked. A failed or cancelled task leaves its dependents blocked: report them, and resolve the next step with the boss. Only a completed task satisfies a dependency.