/wbPlan — Exhaustive Simulation ()
/wbPlan is the general. Its job is to produce the plan file that every other QA-group command reads from. The plan is the source of truth for what work is queued, what's done, what's validated, and what's deferred — and /wbPlan is the one command that creates and structures it. Workers and validators only ever mutate cells in plans they didn't author; the plan's shape is /wbPlan's alone.
Read this if you want to know why /wbPlan is the only command that can mutate both Done and Valid cells, what --focus actually scopes, and where planning ends and orchestration (/wbActOn) begins.
1. Role & target
| Aspect | Behavior |
|---|---|
| Role | The General — coordinates workers and validators by structuring their tasks and estimating execution cost. |
| Target | A free-text description of what should be planned, or a --resume flag to carry over yesterday's incomplete work. |
| Cell scope | Both Done and Valid cells (state-only flags). This is the unique privilege; /wbWork writes only Done, /wbValid writes only Valid, /wbPlan can transition either or both. |
| Side effects allowed | Writing new plan_<package>_<date>.md files; appending rows to existing plans; mutating both cells of a row via state-only flags; computing Est. (min · kt) token estimates and 💰 Budget Summary per plan. |
| Side effects forbidden | Editing source code; running tests; making non-plan-related decisions. |
The "both cells" privilege is what makes /wbPlan the recovery tool. If the worker/validator pair gets into a bad state — a row marked Done = ✅, Valid = 🚫 that should actually be Done = ⏸️, Valid = ⏸️ — only /wbPlan can correct both cells in one operation. /wbWork --id="N" -d would only fix Done; /wbValid --id="N" -d only Valid. The plan command is the cleanup primitive.
2. Argument resolution matrix
| Form | Example | What /wbPlan does |
|---|---|---|
| Free-text description | Command: /wbPlan "implement WBC.js decomposition" | Reads context.md for the active package, breaks the description into rows, assigns model tiers per feedback_model_selection.md. |
| File reference | Command: /wbPlan core2/packages/wb-core/src/WBC.js | Treats the file as the target of planning — produces rows for refactoring/extending it. |
| Audit/review report | Command: /wbPlan reports/<date>/audits/audit_<...>.md | Reads the report's findings and produces rows that address them. (This is what /wbAudit --wbPlan does internally — /wbPlan accepts the report directly when chaining hasn't happened.) |
--resume flag | Command: /wbPlan --resume | Reads yesterday's plan, extracts incomplete rows (Done ≠ ✅ or Valid ≠ ✅), carries them into a fresh plan_*_<today>.md with renumbered IDs. |
--id="<filter>" + state flag | Command: /wbPlan --id="3" -d | State-only mutation: writes ⏸️ to both Done and Valid of row 3. |
The state-only path is operationally important. It exists because the most common cleanup case is "this row is irrelevant now; clear both cells in one go." Doing it via two separate commands (/wbWork ... -d then /wbValid ... -d) is correct but ceremonious; /wbPlan ... -d is the one-step.
3. Flag matrix
/wbPlan has the largest flag surface in the QA group — it's the most-configurable command because planning intent varies most.
Structural flags
| Flag | Shortcut | Purpose |
|---|---|---|
--focus="<sub-system>" | -f | Scopes the plan to a specific sub-system (e.g., --focus="auth", --focus="docs"). Filters rows so they all relate to the focus. |
--scope="<level>" | -s | Architectural scope: local (one package), cross-package, monorepo. Default: local. |
--resume | -r | Carries over incomplete rows from the most recent plan in the same scope. |
--continue-tomorrow | (none) | Marks the current plan with a handover header for tomorrow's --resume. The header summarizes context and pending decisions. |
Row-shaping flags
| Flag | Shortcut | Purpose |
|---|---|---|
--task="<type>" | -t | Forces a row category: feature, bugfix, refactor, audit-followup, docs. Affects the Verify column template. |
--id="<id>" | -i | When state-only flags are present, scopes the mutation to specific rows. |
State-only flags (the dual-cell privilege)
| Flag | Shortcut | Effect when paired with --id |
|---|---|---|
--open | -o | Both cells → ⬜. Re-opens the row entirely. |
--def | -d | Both cells → ⏸️ Deferred. |
--can | -c | Both cells → 🚫 Cancelled. |
Chaining flags
| Flag | Shortcut | Purpose |
|---|---|---|
--act | -a | Routes the new plan through /wbActOn to produce a ranked execution order. |
--wbPlan | -P | Error / no-op here — /wbPlan already produces a plan; chaining its output back into itself is meaningless. The flag exists for grammar consistency across commands but is rejected with a notice. |
The --wbPlan no-op is an interesting case. Other commands (/wbAudit, /wbReview, /wbStandup) take this flag as "convert findings into plan rows." /wbPlan's findings are plan rows. The flag would be circular; the agent rejects it explicitly rather than silently ignoring.
4. Pipelines (the agent-native scenarios)
/wbPlan --resume> /wbPlan --resume💠 Pipeline The Monday morning resume
Friday's plan had 5 rows; 3 done, 2 incomplete. Monday, the user wants to start with those 2 carried forward into a fresh plan:
💠 Pipeline The audit-driven plan (no chaining required)
/wbAudit --wbPlan is the chained shortcut, but the user can also do it explicitly: run audit, produce report, then /wbPlan directly from the report:
💠 Pipeline The dual-cell cleanup
A row is in a confused state (e.g., Done=✅, Valid=❌ because the work landed but failed validation, then the team decided the row was wrong-shaped to begin with). One command fixes both cells:
💠 Pipeline Plan with --focus and --continue-tomorrow
A multi-day session on docs work needs explicit handover state:
5. Edge cases & refusals
| Trigger | What /wbPlan does |
|---|---|
| Free-text input that's vague (e.g., "make things better") | Halt. ❌ Need a more specific description. What sub-system? What outcome? |
--resume with no prior plan in scope | Halt. ❌ No plan to resume from in scope=local. |
--id without a state flag | Halt. ❌ --id on /wbPlan only valid with -o/-d/-c (state mutation). |
--wbPlan flag | Reject with notice. Self-chaining is circular. |
| Plan generation produces zero rows | Honest "nothing to plan." Does not fabricate filler rows. |
--task="<unknown>" | Halt. Lists supported categories. |
--continue-tomorrow on a plan that's already complete | Plan is written with handover header noting "all rows closed; next session free to choose direction." |
--scope="monorepo" | Permitted but warns: "monorepo plans tend to be too coarse for /wbWork to action; consider per-package plans." |
The pattern: /wbPlan is the structural authority, the only dual-cell command, and the source of every plan file every other command reads. It refuses circular self-chaining, refuses to fabricate rows for vague descriptions, and treats the --continue-tomorrow header as a first-class handover artifact. Planning is the foundation; everything else operates on what /wbPlan produces.