monomind 2.2.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Open-source CLI extension for Claude Code. Adds an MCP server with a codebase knowledge graph, persistent memory, multi-agent coordination, and reusable slash commands. MIT licensed, runs locally, no data leaves your machine.",
   "main": "dist/index.js",
   "type": "module",
@@ -183,4 +183,4 @@
     "access": "public",
     "tag": "latest"
   }
-}
+}

package/packages/@monomind/cli/.claude/commands/mastermind/createorg.md

@@ -53,17 +53,21 @@ Parse `$ARGUMENTS` for:
 
 **If `--list` flag is set:**
 ```bash
-orgs_dir=".monomind/orgs"
-if [ ! -d "$orgs_dir" ] || [ -z "$(ls "$orgs_dir"/*.json 2>/dev/null)" ]; then
-  echo "No saved orgs. Run /mastermind:createorg <goal> to create one."
-else
-  echo "Saved orgs:"
-  for f in "$orgs_dir"/*.json; do
-    name=$(jq -r '.name // empty' "$f" 2>/dev/null)
-    goal=$(jq -r '.goal // ""' "$f" 2>/dev/null | cut -c1-60)
-    [ -n "$name" ] && echo "  • ${name} — ${goal}"
-  done
-fi
+# org list knows how to skip artifact side-car files (-state/-goals/…) and
+# shows role count, schedule, and runtime status per org
+npx -y monomind@latest org list || {
+  # fallback for environments without the CLI: config files only
+  orgs_dir=".monomind/orgs"
+  if [ ! -d "$orgs_dir" ] || [ -z "$(ls "$orgs_dir"/*.json 2>/dev/null)" ]; then
+    echo "No saved orgs. Run /mastermind:createorg <goal> to create one."
+  else
+    echo "Saved orgs:"
+    ls "$orgs_dir"/*.json | grep -vE -- '-(state|goals|threads|activity|approvals|members|secrets|budgets|routines|issues|projects|workspaces|worktrees|environments|plugins|adapters|join-requests|bootstrap|project-workspaces|approval-comments|skills)\.json$' \
+      | while IFS= read -r f; do
+          echo "  • $(basename "$f" .json) — $(jq -r '.goal // ""' "$f" 2>/dev/null | cut -c1-60)"
+        done
+  fi
+}
 ```
 Stop after listing. Do not proceed to skill invocation.
 
@@ -74,12 +78,16 @@ Stop after listing. Do not proceed to skill invocation.
    ```
 2. In confirm mode (default): ask "Delete org '${delete_name}' and all its data? This cannot be undone. Type 'yes' to confirm."
    In auto mode: proceed without asking.
-3. Call the server DELETE endpoint:
+3. Delete via the CLI (it refuses to delete a running org unless --force, and
+   removes every artifact side-car file); fall back to the dashboard server's
+   DELETE endpoint only if the CLI is unavailable:
    ```bash
-   REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-   CTRL_URL=$(jq -r '.url // "http://localhost:4242"' "$REPO_ROOT/.monomind/control.json" 2>/dev/null || echo "http://localhost:4242")
-   result=$(curl -s -X DELETE "${CTRL_URL}/api/orgs/${delete_name}")
-   echo "$result" | jq -r 'if .ok then "Org '\'''"${delete_name}"'''\'' deleted." else "Error: " + (.error // "unknown") end'
+   npx -y monomind@latest org delete "${delete_name}" --yes || {
+     REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+     CTRL_URL=$(jq -r '.url // "http://localhost:4242"' "$REPO_ROOT/.monomind/control.json" 2>/dev/null || echo "http://localhost:4242")
+     result=$(curl -s -X DELETE "${CTRL_URL}/api/orgs/${delete_name}")
+     echo "$result" | jq -r 'if .ok then "Org '\'''"${delete_name}"'''\'' deleted." else "Error: " + (.error // "unknown") end'
+   }
    ```
 4. Stop after deleting. Do not proceed to skill invocation.
 

package/packages/@monomind/cli/.claude/commands/mastermind/master.md

@@ -172,13 +172,13 @@ These thoughts mean **STOP** — you are rationalizing. Check for a skill first.
 | "Should I continue?" (in auto mode) | Never ask. Auto mode means execute continuously until blocked or all tasks complete. |
 | "TBD / TODO / implement later" (in a plan) | Placeholder = plan failure. Every step needs exact paths, complete code, runnable commands. |
 | "Code quality review first, then spec" | Wrong order every time. Spec compliance FIRST, code quality SECOND. Never reversed. |
-| "The subagent can read the plan file itself" | Controller provides full task text to each implementer. Subagents never read plan files. |
+| "The subagent can read the plan file itself" | Controller extracts each task into a brief file and hands over that path. Subagents never read whole plan files. |
 
 ### Mandatory Patterns
 
 These sequences are non-negotiable in all modes:
 
-- **Before building**: Load brain → `mastermind:design` if approach is unclear → `mastermind:plan` for complex work → then build
+- **Before building**: Load brain → `mastermind:design` (questions → approaches → approved spec) → `mastermind:plan` (complete plan + execution handoff) → then build
 - **When fixing bugs**: `mastermind:debug` first (root cause) → write failing test via `mastermind:tdd` → fix → `mastermind:verify`
 - **After building**: `mastermind:review` — at minimum one pass before reporting complete
 - **Consuming a review**: `mastermind:receive-review` — verify before implementing, clarify unclear items first
@@ -186,8 +186,8 @@ These sequences are non-negotiable in all modes:
 - **Before releasing**: `mastermind:review --tillend --auto` → `mastermind:verify` → `mastermind:finish`
 - **Isolated work**: `mastermind:worktree` before making changes to avoid contaminating main
 - **Before claiming complete**: Run `mastermind:verify` — never claim completion based on agent reports, linter passes, or partial checks
-- **When writing a plan**: Map file structure first → write tasks with exact paths + complete code (no placeholders) → self-review (spec coverage, placeholder scan, type consistency) → offer execution mode choice (subagent-driven vs inline)
-- **When executing with subagents**: Provide full task text to each implementer (never make them read the plan file) → spec compliance review FIRST → code quality review SECOND → re-review until both ✅ → dispatch final reviewer after all tasks complete → then `mastermind:finish`
+- **When writing a plan**: Map file structure first → copy spec-wide Global Constraints into the plan header → right-size tasks (smallest unit with its own test cycle) with exact paths, complete code, and Interfaces (Consumes/Produces) blocks — no placeholders → self-review (spec coverage, placeholder scan, type consistency) → offer execution mode choice (subagent-driven vs inline)
+- **When executing with subagents**: Hand each implementer its task as a brief file (never make them read the plan file) → spec compliance review FIRST → code quality review SECOND → re-review until both ✅ → record each completed task in the durable progress ledger (`.monomind/taskdev/progress.md`) → dispatch final whole-branch reviewer (most capable model, diff handed over as a file) after all tasks complete → then `mastermind:finish`
 - **When blocked during execution**: Stop immediately — do not guess or force through. Diagnose, provide context, re-dispatch with more capable model, or escalate to user
 
 ### Iron Laws
@@ -359,6 +359,22 @@ If `domains_needed` contains ONLY non-build domains (marketing, sales, research,
 Rationale: without a design gate, master spawns agents before the user has confirmed what to build. The design gate replicates the superpowers workflow: questions → approaches → spec approval → plan → execute.
 </HARD-GATE>
 
+### Step 3.6 — Plan Gate
+
+<HARD-GATE>
+If the Design Gate ran (build work), do NOT skip planning. After `mastermind:design` returns with an approved spec:
+
+1. Invoke `Skill("mastermind-skills:plan")` NOW — pass `build_spec`, the brain context, and mode
+2. The plan skill produces `docs/mastermind/plans/YYYY-MM-DD-<feature>.md` with the complete header (Goal, Architecture, Tech Stack, Global Constraints), right-sized tasks with Interfaces (Consumes/Produces) blocks, bite-sized TDD steps, and no placeholders — then runs its self-review (spec coverage, placeholder scan, type consistency)
+3. The plan skill's Execution Handoff resolves the execution mode. Record it: `build_exec_mode` = `taskdev` (subagent-driven) or `execute` (inline), and save the plan path as `build_plan` in `current.json`
+4. Step 5 MUST NOT re-ask the execution-mode question when this gate already resolved `build_exec_mode`
+5. Only then continue to Step 4
+
+If `domains_needed` contains ONLY non-build domains: skip this gate (same rule as Step 3.5).
+
+Rationale: superpowers' pipeline is brainstorm → spec approval → writing-plans → execution handoff. Without a plan gate, master hands an un-planned spec straight to domain managers and the plan discipline (exact paths, complete code, interface contracts between tasks) is lost.
+</HARD-GATE>
+
 ### Step 4 — Decompose
 
 For each domain in `domains_needed`, assess complexity:
@@ -435,14 +451,14 @@ If mode = confirm: show plan and wait for user response. Valid responses:
 - Any modification (e.g. "add sales domain", "remove marketing") — apply the change, re-show the plan, wait again
 - "cancel" or "stop" — emit `session:complete` with `status: blocked`, reason "cancelled by user", then STOP
 
-After the user says "go" (and `build` is in `domains_needed`), ask once:
+If the Step 3.6 Plan Gate already resolved `build_exec_mode`, skip the question below and use that value. Otherwise, after the user says "go" (and `build` is in `domains_needed`), ask once:
 > "For the build work: **subagents** (recommended — fresh agent per task with 2-stage review, like mastermind:taskdev) or **inline** (direct execution, mastermind:execute)?"
 
 - "subagents" → `build_exec_mode = "taskdev"`
 - "inline" → `build_exec_mode = "execute"`
 - No answer / skipped → `build_exec_mode = "taskdev"` (default)
 
-If mode = auto: `build_exec_mode = "taskdev"` (default).
+If mode = auto and Step 3.6 did not set it: `build_exec_mode = "taskdev"` (default).
 
 **Persist `build_exec_mode` to `current.json`** (required — Phase C reads it from there):
 
@@ -745,7 +761,7 @@ Each Task call must include a complete briefing following the Monotask Task Brie
 - Instruction to create monotask cards directly using `monotask card create $BOARD_ID $COL_TODO_ID "<title>" --json` for all sub-tasks
 - Instruction to use `Skill("mastermind-skills:do")` to execute tasks (Task agents have Skill tool access — do NOT use slash command syntax)
 - Instruction to spawn specialized agents using the domain-appropriate swarm topology
-- **For the `build` domain only:** include `build_exec_mode` (value: `"taskdev"` or `"execute"`) and instruct the manager: "Use `Skill("mastermind-skills:taskdev")` if build_exec_mode is `taskdev`, or `Skill("mastermind-skills:execute")` if `execute`. This was chosen by the user in Step 5."
+- **For the `build` domain only:** include `build_exec_mode` (value: `"taskdev"` or `"execute"`) and instruct the manager: "Use `Skill("mastermind-skills:taskdev")` if build_exec_mode is `taskdev`, or `Skill("mastermind-skills:execute")` if `execute`. This was resolved in the Step 3.6 Plan Gate (or Step 5)." If `build_plan` is set in `current.json`, include the plan path and instruct the manager to execute THAT plan task-by-task rather than re-deriving tasks from the goal.
 - Instruction to return the unified output schema when done
 
 Example Task call for Development Manager. Substitute all **pre-known** `<…>` placeholders (project_name, SESSION_ID, board/col IDs, goals, manager name) before calling Task. Placeholders like `<status>`, `<path1>`, `<action1>` are filled at runtime by the spawned agent — do not attempt to substitute them. `subagent_type` is the **string value** of `$domain_manager_build` (e.g. `"Backend Architect"`), not a variable reference.

package/packages/@monomind/cli/.claude/commands/mastermind/runorg.md

@@ -19,7 +19,9 @@ Running an org starts an autonomous agent organization. There are two modes:
 **Your saved orgs:**
 
 ```bash
-ls .monomind/orgs/*.json 2>/dev/null | xargs -I{} basename {} .json 2>/dev/null || echo "(none — run /mastermind:createorg to define one)"
+npx -y monomind@latest org list 2>/dev/null \
+  || ls .monomind/orgs/*.json 2>/dev/null | grep -vE -- '-(state|goals|threads|activity|approvals|members|secrets|budgets|routines|issues|projects|workspaces|worktrees|environments|plugins|adapters|join-requests|bootstrap|project-workspaces|approval-comments|skills)\.json$' | xargs -I{} basename {} .json 2>/dev/null \
+  || echo "(none — run /mastermind:createorg to define one)"
 ```
 
 **Usage:**

package/packages/@monomind/cli/.claude/commands/mastermind/stoporg.md

@@ -29,11 +29,14 @@ active   →  (HIL)      →  paused    (set manually in .monomind/orgs/<name>.j
 paused   →  (set active) →  active  (resume by setting status back to "active" in the JSON)
 ```
 
-Your scheduled orgs:
+**Note:** v2 orgs (the default) are stopped via `monomind org stop <name>` — this
+command handles both: it routes v2 orgs to the CLI and legacy `.loop` orgs
+through the v1 status-flip path.
+
+Your orgs (with live runtime status):
 
 ```bash
-ls .monomind/orgs/*.json 2>/dev/null | grep -v -- '-approvals\|-state\|-activity' | \
-  xargs -I{} sh -c 'name=$(jq -r ".name" "{}"); status=$(jq -r ".status // \"no-loop\"" "{}"); interval=$(jq -r "if .loop.poll_interval_minutes then \"\(.loop.poll_interval_minutes)m\" else \"—\" end" "{}"); echo "  $name  ($status, $interval)"' 2>/dev/null || echo "(none)"
+npx -y monomind@latest org list 2>/dev/null || echo "(none — run /mastermind:createorg to define one)"
 ```
 
 ---

package/packages/@monomind/cli/.claude/skills/mastermind-skills/code-quality-reviewer-prompt.md

@@ -18,10 +18,10 @@ Task tool (general-purpose):
 
     ## Diff to Review
 
-    BASE_SHA: [commit before task]
-    HEAD_SHA: [current commit after task]
+    Read this file — it contains the commit list, stat summary, and full
+    diff from [BASE_SHA] to [HEAD_SHA]:
 
-    Review the changes introduced between these commits.
+    [DIFF_FILE_PATH — e.g. .monomind/taskdev/task-N-review.diff]
 
     ## What to Check
 

package/packages/@monomind/cli/.claude/skills/mastermind-skills/createorg.md

@@ -181,32 +181,25 @@ jq -n \
   > "${orgJson}.tmp" && mv "${orgJson}.tmp" "$orgJson"
 ```
 
-**POST-SAVE VALIDATION (run immediately after saving — abort if any check fails):**
+**POST-SAVE VALIDATION (run immediately after saving — abort if it fails):**
 
 ```bash
-# Check 1 — exactly one root role (reports_to null)
-root_count=$(jq '[.roles[] | select(.reports_to == null)] | length' "$orgJson")
-if [ "$root_count" -ne 1 ]; then
-  echo "ERROR: expected exactly one role with reports_to: null, found $root_count — fix the roles array and re-save."
-  exit 1
+# Parses with OrgDefSchema (the exact code path org run/serve use) and checks the
+# structural invariants: exactly one root role, every reports_to resolves, unique
+# role ids, parseable schedule, name/filename agreement.
+if npx -y monomind@latest org validate "$org_name"; then
+  echo "✓ Org config validated — ready for: monomind org run ${org_name}"
+else
+  # CLI < 2.1.8 has no `org validate` — fall back to the two structural checks:
+  root_count=$(jq '[.roles[] | select(.reports_to == null)] | length' "$orgJson")
+  bad_reports=$(jq -r '([.roles[].id]) as $ids |
+    [.roles[] | select(.reports_to != null and (.reports_to as $r | $ids | index($r) | not)) | .id] | join(", ")' "$orgJson")
+  if [ "$root_count" -ne 1 ] || [ -n "$bad_reports" ]; then
+    echo "ERROR: org config invalid (roots: $root_count, unresolved reports_to: ${bad_reports:-none}) — fix the roles array and re-save."
+    exit 1
+  fi
+  echo "✓ Structural checks passed (upgrade monomind for full schema validation)"
 fi
-echo "✓ Exactly one root role"
-
-# Check 2 — every non-root role's reports_to resolves to a real role id
-bad_reports=$(jq -r '
-  ([.roles[].id]) as $ids |
-  [.roles[] | select(.reports_to != null and (.reports_to as $r | $ids | index($r) | not)) | .id]
-  | join(", ")' "$orgJson")
-if [ -n "$bad_reports" ]; then
-  echo "ERROR: these roles have a reports_to that doesn't match any role id: $bad_reports"
-  exit 1
-fi
-echo "✓ All reports_to values resolve"
-
-# Check 3 — schema sanity check via the CLI itself (parses with OrgDefSchema, same code path org run/serve use)
-npx monomind@latest org list >/dev/null 2>&1 || echo "WARNING: could not verify via CLI — check .monomind/orgs manually"
-
-echo "✓ Org config validated — ready for: monomind org run ${org_name}"
 ```
 
 ---
@@ -228,7 +221,9 @@ lessons:
   - what_worked: "Auto-suggested roles matched user intent"
   - what_didnt: ""
 next_actions:
-  - "Run `monomind org run <org_name>` to start the organization in the foreground"
+  - "Run `monomind org run <org_name>` to start the organization in the foreground (add --dry-run to preview each role's briefing first)"
+  - "After hand-editing the config, re-check it with `monomind org validate <org_name>`"
+  - "While running: `monomind org logs <org_name> --follow`; afterwards: `monomind org report <org_name>` for outcome, per-role activity, and token usage"
   - "Or `monomind org serve` to host it (and any other scheduled orgs) as a background daemon"
   - "Edit .monomind/orgs/<org_name>.json directly, or use /mastermind:org-settings, to change goal/budget/roles"
   - "`monomind org status <org_name>` to check runtime state; `monomind org stop <org_name>` to stop a running org"

package/packages/@monomind/cli/.claude/skills/mastermind-skills/debug.md

@@ -101,6 +101,14 @@ You MUST complete each phase before proceeding to the next.
    echo "=== Final state: ==="
    ```
 
+5. **Trace Data Flow**
+
+   **WHEN the error is deep in a call stack:**
+   - Where does the bad value originate?
+   - What called this with the bad value?
+   - Keep tracing up until you find the source
+   - Fix at the source, not at the symptom — a `null` crashing in layer 4 usually entered in layer 1
+
 ---
 
 ### Phase 2: Pattern Analysis
@@ -112,11 +120,21 @@ Once you understand WHERE the break is, find existing working examples:
    - Check git history for when this worked
    - Find the canonical implementation to compare against
 
-2. **Compare broken vs. working**
+2. **Compare against references**
+   - If implementing a pattern, read the reference implementation COMPLETELY
+   - Don't skim — read every line
+   - Understand the pattern fully before applying it
+
+3. **Compare broken vs. working**
    - What's different?
-   - List every difference, not just the obvious one
+   - List every difference, not just the obvious one — don't assume "that can't matter"
    - Environment, config, data, timing
 
+4. **Understand dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
 ---
 
 ### Phase 3: Form and Test a Hypothesis
@@ -131,13 +149,15 @@ Once you understand WHERE the break is, find existing working examples:
 
 3. **If hypothesis is wrong:** Do NOT add more fixes. Return to Phase 1 with the new information.
 
+4. **When you don't know:** Say "I don't understand X". Don't pretend to know. Research more or ask the user — a stated unknown beats a confident guess.
+
 ---
 
 ### Phase 4: Implementation
 
 1. **Write a failing test first** (before touching production code)
-   - Automated test where possible
-   - Use `Skill("mastermind-skills:build")` with a test-only prompt if needed
+   - Automated test where possible; a one-off test script if no framework
+   - Use `Skill("mastermind-skills:tdd")` for writing proper failing tests
    - The test MUST fail before the fix proves it
 
 2. **Implement a single fix**
@@ -186,6 +206,9 @@ If you catch yourself thinking or doing any of these:
 | "Quick fix for now, investigate later" | You're skipping root cause. Return to Phase 1. |
 | "Just try changing X and see if it works" | Guessing. Return to Phase 1. |
 | "Add multiple changes, run tests" | Can't isolate what worked. Return to Phase 1. |
+| "Skip the test, I'll manually verify" | Untested fixes don't stick. Write the failing test. |
+| "Pattern says X but I'll adapt it differently" | Partial understanding guarantees bugs. Read the reference completely. |
+| "Here are the main problems: …" (listing fixes without investigation) | Solutions before evidence. Return to Phase 1. |
 | "It's probably X, let me fix that" | Assumed root cause. Verify it first. Return to Phase 1. |
 | "I don't fully understand but this might work" | You don't have a hypothesis. Return to Phase 1. |
 | Proposing solutions before tracing data flow | No root cause. Return to Phase 1. |
@@ -212,6 +235,7 @@ Watch for these redirections from the user:
 | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
 | "I'll write the test after confirming the fix works" | Untested fixes don't stick. Test first proves it. |
 | "Multiple fixes at once saves time" | Can't isolate what worked. Creates new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
 | "I can see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
 | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question the pattern. |
 
@@ -224,6 +248,27 @@ Watch for these redirections from the user:
 | **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
 | **4. Implementation** | Write failing test, fix, verify | Bug resolved, tests pass |
 
+## When the Process Reveals "No Root Cause"
+
+If systematic investigation reveals the issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, clear error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+- **Root-cause tracing:** when a bad value crashes deep in the stack, trace it backward caller by caller until you find where it was created; fix there. Adding a guard at the crash site only hides the origin.
+- **Defense in depth:** AFTER fixing the root cause, add validation at the layers the bad value passed through unchecked — so the next bad value fails loudly at its first boundary, not silently at its fourth.
+- **Condition-based waiting:** replace arbitrary sleeps/timeouts in flaky tests and scripts with polling for the actual condition ("wait until the file exists / the port answers"), with a hard cap. Timing guesses are bugs waiting for a slower machine.
+
+**Related skills:**
+- `Skill("mastermind-skills:tdd")` — for creating the failing test case (Phase 4, Step 1)
+- `Skill("mastermind-skills:verify")` — verify the fix worked before claiming success
+
 ## Impact
 
 Systematic approach vs random fixing:

package/packages/@monomind/cli/.claude/skills/mastermind-skills/design.md

@@ -37,7 +37,7 @@ Every feature goes through this process. A todo list, a single-function utility,
 Complete these items in order:
 
 1. **Explore project context** — check files, docs, recent commits
-2. **Offer visual companion** (if topic will involve visual questions) — own message, not combined with a clarifying question (see Visual Companion section below)
+2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message, not combined with a clarifying question). If no visual question ever arises, never offer it. See the Visual Companion section below.
 3. **Ask clarifying questions** — one at a time; understand purpose, constraints, success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity; get user approval after each section
@@ -53,10 +53,9 @@ Complete these items in order:
 ```
 Explore project context
         ↓
-Visual questions ahead?
-    yes → Offer Visual Companion (own message, no other content)
-    no  ↓
 Ask clarifying questions (one at a time)
+    (a question is clearer shown than described?
+     → offer Visual Companion just-in-time — own message, no other content)
         ↓
 Propose 2-3 approaches
         ↓
@@ -167,16 +166,18 @@ Wait for the user's response. If they request changes, make them and re-run the
 
 A browser-based companion for showing mockups, diagrams, and visual options during design sessions. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
 
-**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
 
-> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. Want to try it? (Requires opening a local URL)"
+> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."
 
-**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. Wait for the user's response before continuing. If they decline, proceed with text-only design.
+**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they decline, continue text-only and don't offer again unless they raise it.
 
-**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal.
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
 
-- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams
-- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, scope decisions
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
 
 If they agree to the companion, use `Skill("mastermind-skills:worktree")` to set up an isolated workspace, then invoke `Skill("agent-browser-testing")` to open the browser.
 

package/packages/@monomind/cli/.claude/skills/mastermind-skills/final-reviewer-prompt.md

@@ -0,0 +1,144 @@
+# Final Whole-Branch Reviewer Prompt Template
+
+Use this template when dispatching the final code reviewer subagent from `mastermind:taskdev` (after all tasks complete) or `mastermind:review`. Dispatch it on the **most capable available model**.
+
+**Purpose:** Review the entire branch against its plan/spec before merge — the one broad pass after all task-scoped gates.
+
+```
+Task tool (general-purpose):
+  description: "Final whole-branch review"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    [DESCRIPTION]
+
+    ## Requirements / Plan
+
+    [PLAN_OR_REQUIREMENTS]
+
+    ## Diff to Review
+
+    Read this file — it contains the commit list, stat summary, and full diff
+    from [BASE_SHA] to [HEAD_SHA]:
+
+    [DIFF_FILE_PATH]
+
+    ## Minor Findings Carried Forward
+
+    [MINOR_FINDINGS_LIST — from the progress ledger; triage which must be
+    fixed before merge]
+
+    ## Read-Only Review
+
+    Your review is read-only on this checkout. Do not mutate the working
+    tree, the index, HEAD, or branch state in any way. Use `git show`,
+    `git diff`, and `git log` to inspect history.
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `[DESCRIPTION]` — brief summary of what was built across the branch
+- `[PLAN_OR_REQUIREMENTS]` — the plan file path or spec text
+- `[BASE_SHA]` — the merge base (`git merge-base main HEAD`)
+- `[HEAD_SHA]` — branch head
+- `[DIFF_FILE_PATH]` — the diff file generated from BASE..HEAD (commit list + stat + `git diff -U10`)
+- `[MINOR_FINDINGS_LIST]` — accumulated Minor findings from per-task reviews
+
+**Acting on feedback (controller):**
+- Fix Critical issues immediately; fix Important issues before merge
+- Dispatch ONE fix subagent with the complete findings list — not one fixer per finding
+- Push back on findings that are wrong — with technical reasoning and evidence, never performative agreement
+- Never skip this review because "the per-task reviews all passed" — task gates are narrow by design

package/packages/@monomind/cli/.claude/skills/mastermind-skills/implementer-prompt.md

@@ -95,13 +95,18 @@ Task tool (general-purpose):
 
     ## Report Format
 
-    When done, report:
-    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    Write your full report to the report file named in this dispatch
+    ([REPORT_FILE_PATH]), covering:
     - What you implemented (or what you attempted, if blocked)
-    - What you tested and test results
+    - What you tested and test results (commands run + output summary)
     - Files changed
     - Self-review findings (if any)
-    - Any issues or concerns
+
+    Then return only:
+    - **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
+    - Commits created
+    - One-line test summary
+    - Any concerns
 
     Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
     Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need

package/packages/@monomind/cli/.claude/skills/mastermind-skills/org-settings.md

@@ -82,9 +82,14 @@ case "$field" in
     [ -f "$newOrgFile" ] && { echo "ERROR: An org named '${value}' already exists."; exit 1; }
     # Refuse to rename while the daemon has this org running — it holds the old
     # name's paths (defPath, cwd, runtime.json) in memory; a rename mid-run would
-    # orphan that live state instead of moving it.
+    # orphan that live state instead of moving it. A runtime.json left by a
+    # crashed daemon (dead pid) does NOT count as running — same semantics as
+    # isOrgRunning in packages/@monomind/cli/src/commands/org.ts.
     runtime_status=$(jq -r '.status // "stopped"' ".monomind/orgs/${org_name}/runtime.json" 2>/dev/null || echo "stopped")
-    [ "$runtime_status" = "running" ] && { echo "ERROR: org '${org_name}' is running — stop it first: monomind org stop ${org_name}"; exit 1; }
+    runtime_pid=$(jq -r '.pid // 0' ".monomind/orgs/${org_name}/runtime.json" 2>/dev/null || echo 0)
+    if [ "$runtime_status" = "running" ] && [ "$runtime_pid" -gt 0 ] && kill -0 "$runtime_pid" 2>/dev/null; then
+      echo "ERROR: org '${org_name}' is running (pid ${runtime_pid}) — stop it first: monomind org stop ${org_name}"; exit 1
+    fi
     # Update the name field inside the JSON
     jq --arg v "$value" '.name = $v' "$orgFile" > "$tmp" && mv "$tmp" "$orgFile"
     # Rename the main config file
@@ -144,6 +149,13 @@ case "$field" in
 esac
 ```
 
+After any edit, re-validate the config the same way createorg does (non-fatal — the file is already written; this tells the user immediately if the org can no longer start):
+
+```bash
+npx -y monomind@latest org validate "$org_name" \
+  || echo "WARNING: '${org_name}' no longer passes validation — fix it before 'monomind org run ${org_name}'"
+```
+
 Emit `org:settings:updated` event:
 
 ```bash
@@ -231,6 +243,12 @@ fi
 
 echo "Imported org '${targetOrg}' from ${import_path}"
 echo "Agents: $(jq '.config.roles | length' "$import_path")"
+
+# An imported bundle is untrusted input — validate before declaring success
+# (schema + single root role + resolvable reports_to + parseable schedule).
+npx -y monomind@latest org validate "$targetOrg" \
+  || { echo "ERROR: imported org failed validation — fix .monomind/orgs/${targetOrg}.json before running it."; exit 1; }
+
 echo "Run /mastermind:env --org ${targetOrg} --action validate to check provider keys."
 ```