@monoes/monomindcli 2.10.9 → 2.10.13

package/.claude/skills/mastermind/references/gemini-tools.md

@@ -61,68 +61,3 @@ These tools are unique to Gemini CLI:
 | `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
 | `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
 | `read_mcp_resource`, `list_mcp_resources` | MCP resource access |
-# monomind:start skills:claude:mastermind:references/gemini-tools.md
-# Gemini CLI Tool Mapping
-
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.
-
-| Action skills request | Gemini CLI equivalent |
-|----------------------|----------------------|
-| Read a file | `read_file` |
-| Read multiple files at once | `read_many_files` |
-| Create a new file | `write_file` |
-| Edit a file | `replace` |
-| Run a shell command | `run_shell_command` |
-| Search file contents | `grep_search` |
-| Find files by name | `glob` |
-| List files and subdirectories | `list_directory` |
-| Fetch a URL | `web_fetch` |
-| Search the web | `google_web_search` |
-| Invoke a skill | `activate_skill` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_agent` with `agent_name: "generalist"` (invocable via `@generalist` chat syntax — see [Subagent support](#subagent-support)) |
-| Multiple parallel dispatches | Multiple `invoke_agent` calls in the same response |
-| Task tracking ("create a todo", "mark complete") | `write_todos` (statuses: pending, in_progress, completed, cancelled, blocked) |
-
-## Instructions file
-
-When a skill mentions "your instructions file", on Gemini CLI this is **`GEMINI.md`**. Gemini CLI loads `GEMINI.md` hierarchically: global at `~/.gemini/GEMINI.md`, project-level files in workspace directories and their ancestors, and sub-directory `GEMINI.md` files when a tool accesses files in those directories.
-
-## Personal skills directory
-
-User-level skills live at **`~/.gemini/skills/`**, with **`~/.agents/skills/`** as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, `.agents/skills/` takes precedence. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
-
-## Subagent support
-
-Gemini CLI dispatches subagents through the `invoke_agent` tool, which takes `agent_name` and `prompt` parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing `@generalist <prompt>` is equivalent to calling `invoke_agent` with `agent_name: "generalist"`. Built-in agent names include `generalist`, `cli_help`, `codebase_investigator`, and (with browser tooling enabled) `browser_agent`.
-
-Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file or supply an inline prompt. On Gemini CLI:
-
-| Skill dispatch form | Gemini CLI equivalent |
-|---------------------|----------------------|
-| References an implementer template (writes code, runs tests) | Fill the template, then `invoke_agent` with `agent_name: "generalist"` and the filled prompt |
-| References a code-reviewer template (`mastermind:review`) | `invoke_agent` with `agent_name: "generalist"` and the filled review template |
-| Inline prompt (no template referenced) | `invoke_agent` with `agent_name: "generalist"` and your inline prompt |
-
-### Prompt filling
-
-Skills provide prompt templates with placeholders like `{WHAT_WAS_IMPLEMENTED}` or `[FULL TEXT of task]`. Fill all placeholders before passing the complete prompt to `invoke_agent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
-
-### Parallel dispatch
-
-Gemini CLI supports parallel subagent dispatch. Issue multiple `invoke_agent` calls in the same response to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
-
-## Additional Gemini CLI tools
-
-These tools are unique to Gemini CLI:
-
-| Tool | Purpose |
-|------|---------|
-| `save_memory` (legacy) | Persist facts across sessions when `experimental.memoryV2 = false` |
-| `get_internal_docs` | Look up Gemini CLI's bundled documentation |
-| `ask_user` | Pose structured questions to the user (text / single-select / multi-select) |
-| `enter_plan_mode` / `exit_plan_mode` | Switch into and out of read-only plan mode |
-| `update_topic` | Update the current conversation's topic / strategic-intent metadata |
-| `complete_task` | Signal that a Gemini subagent has completed and return its result to the parent agent |
-| `tracker_create_task`, `tracker_update_task`, `tracker_get_task`, `tracker_list_tasks`, `tracker_add_dependency`, `tracker_visualize` | Rich task tracker with dependency and visualization support |
-| `read_mcp_resource`, `list_mcp_resources` | MCP resource access |
-# monomind:end skills:claude:mastermind:references/gemini-tools.md

package/.claude/skills/mastermind/references/pi-tools.md

@@ -26,33 +26,3 @@ Pi core does not ship a standard subagent tool. The `pi-subagents` package is a
 ## Task lists
 
 Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Mastermind plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking. Older docs may refer to `TodoWrite`; treat that as the task-tracking action above.
-# monomind:start skills:claude:mastermind:references/pi-tools.md
-# Pi Tool Mapping
-
-Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.
-
-| Action skills request | Pi equivalent |
-| --- | --- |
-| Invoke a skill | Pi native skills: load the relevant `SKILL.md` with `read`, or let the human use `/skill:name` |
-| Read a file | `read` |
-| Create a file | `write` |
-| Edit a file | `edit` |
-| Run a shell command | `bash` |
-| Search file contents | `grep` when active; otherwise `bash` with `rg`/`grep` |
-| Find files by name | `find` or `bash` with shell globs |
-| List files and subdirectories | `ls` when active; otherwise `bash` with `ls` |
-| Dispatch a subagent (`Subagent (general-purpose):` template) | Use an installed subagent tool such as `subagent` from `pi-subagents` if available |
-| Task tracking ("create a todo", "mark complete") | Use an installed todo/task tool if available, otherwise track tasks in the plan or `TODO.md` |
-
-## Skills
-
-Pi discovers skills from configured skill directories and installed Pi packages. A Mastermind Pi package should expose `skills/` through its `pi.skills` manifest entry. Pi does not expose Claude Code's `Skill` tool, but the agent should still follow the Mastermind rule: when a skill applies, load and follow it before responding.
-
-## Subagents
-
-Pi core does not ship a standard subagent tool. The `pi-subagents` package is a strong optional companion and provides a `subagent` tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate `Task` calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.
-
-## Task lists
-
-Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Mastermind plan files, checklists in Markdown, or a repo-local `TODO.md` for task tracking. Older docs may refer to `TodoWrite`; treat that as the task-tracking action above.
-# monomind:end skills:claude:mastermind:references/pi-tools.md

package/.claude/skills/mastermind-createorg/SKILL.md

@@ -96,7 +96,9 @@ For any role that needs non-default behavior, set (all optional — omit to inhe
   - `"codex"` — ChatGPT subscription via `codex login` (no env vars needed). Auto-resolves `runtime: 'codex'`.
   - `"antigravity"` — Google AI Pro/Ultra subscription via `agy` CLI (Google OAuth in OS keyring). Auto-resolves `runtime: 'antigravity'`. This is the replacement for the consumer-OAuth path of Gemini CLI (sunset June 18, 2026).
 - `runtime`: `"claude"` | `"kimicode"` | `"opencode"` | `"vercel"` | `"codex"` | `"antigravity"` — per-role override of the agent loop backend. Usually unnecessary (auto-resolved from `provider.kind`); set explicitly only when you need to force a specific runner regardless of provider.
-- `policy`: `{ allowTools?, denyTools?, fileWrite?, fileRead?, webAllow?, maxTokens? }` — glob-based tool/file/web restrictions for that role; leave unset unless the user asked for sandboxing
+- `policy`: `{ allowTools?, denyTools?, fileWrite?, fileRead?, webAllow?, autoApproveTools?, maxTokens? }` — leave the whole object unset for a role that doesn't need it (most roles). But `webAllow` unset/empty means **no web access at all**, and Bash/WebFetch/WebSearch/`org_complete` pause for human approval by default on every call — that's a restriction, not a neutral default, so don't leave it unset for a role whose responsibilities clearly require it (e.g. a role tasked with "gather headlines from news sources" needs `webAllow` populated, not omitted). Set proactively, at creation time, for any role whose stated responsibilities need it:
+  - `webAllow: ["*"]` (or specific domains) for a role that does WebSearch/WebFetch as part of its job — an empty/unset `webAllow` silently blocks the exact task you just assigned it.
+  - `autoApproveTools: [...]` — tool/action names this role may use without pausing for a human approval, even though they're normally on the sensitive-actions list (`Bash`, `WebFetch`, `WebSearch`, `org_complete`). **Mandatory, not optional, for any org with a `schedule` set** (an unattended/scheduled org): a role that pauses on `WebSearch` or `org_complete` waiting for a human who isn't there to click approve will deadlock forever on every scheduled run, repeatedly re-asking through both `ask_human` and `org_gate` with nothing to show for it. Grant every tool a scheduled org's roles routinely need — including `org_complete` for the boss role — rather than leaving the default human-approval gate in place for automation that's supposed to run with nobody watching.
 
 Do not invent values for these — only populate a field the user actually specified or clearly implied (e.g. "the researcher should use Opus" → that role's `adapter_config.model`).
 

package/.claude/skills/mastermind-debug/SKILL.md

@@ -157,7 +157,7 @@ Once you understand WHERE the break is, find existing working examples:
 
 1. **Write a failing test first** (before touching production code)
    - Automated test where possible; a one-off test script if no framework
-   - Use `Skill("mastermind-tdd")` for writing proper failing tests
+   - Write the test so it fails for the stated root cause, not for a setup error
    - The test MUST fail before the fix proves it
 
 2. **Implement a single fix**
@@ -266,8 +266,8 @@ If systematic investigation reveals the issue is truly environmental, timing-dep
 - **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-tdd")` — for creating the failing test case (Phase 4, Step 1)
-- `Skill("mastermind-verify")` — verify the fix worked before claiming success
+- `Skill("mastermind-review")` — verify the fix worked before claiming success
+- `Skill("mastermind-plan")` — when the root cause turns out to need a multi-file change
 
 ## Impact
 
@@ -275,277 +275,3 @@ Systematic approach vs random fixing:
 - Time to fix: 15-30 min vs 2-3 hours of thrashing
 - First-time fix rate: ~95% vs ~40%
 - New bugs introduced by the fix: near zero vs common
-# monomind:start skills:claude:mastermind-debug
-# mastermind:debug — Systematic Debugging
-
-## Overview
-
-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
-
-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
-
-**Violating the letter of this process is violating the spirit of debugging.**
-
-## The Iron Law
-
-```
-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-```
-
-If you haven't completed Phase 1, you cannot propose fixes.
-
-## When to Use
-
-Use for ANY technical issue:
-- Test failures
-- Bugs in production or staging
-- Unexpected behavior
-- Performance regressions
-- Build failures
-- Integration issues
-
-**Use this ESPECIALLY when:**
-- Under time pressure (emergencies make guessing tempting)
-- "Just one quick fix" seems obvious
-- You've already tried multiple fixes that didn't work
-- Previous fix didn't resolve the issue
-- You don't fully understand what's happening
-
-**Don't skip when:**
-- Issue seems simple (simple bugs have root causes too)
-- You're in a hurry (systematic is faster than thrashing)
-- The user wants it fixed immediately (systematic approach finds the real fix faster)
-
-## The Four Phases
-
-You MUST complete each phase before proceeding to the next.
-
----
-
-### Phase 1: Root Cause Investigation
-
-**BEFORE attempting ANY fix:**
-
-1. **Read Error Messages Carefully**
-   - Don't skim errors or warnings
-   - They often contain the exact solution
-   - Read stack traces completely
-   - Note line numbers, file paths, error codes
-
-2. **Reproduce Consistently**
-   - Can you trigger the issue reliably?
-   - What are the exact steps?
-   - Does it happen every time?
-   - If not reproducible → gather more data, don't guess
-
-3. **Check Recent Changes**
-   - What changed that could cause this?
-   - `git diff`, recent commits, new dependencies, config changes
-   - Environmental differences between working and broken states
-
-4. **Gather Evidence in Multi-Component Systems**
-
-   **WHEN the system has multiple components (CI → build → deploy, API → service → database):**
-
-   **BEFORE proposing fixes, add diagnostic instrumentation:**
-   ```
-   For EACH component boundary:
-     - Log what data enters the component
-     - Log what data exits the component
-     - Verify config/env propagation at each layer
-     - Check state at each boundary
-
-   Run once to gather evidence showing WHERE it breaks
-   THEN analyze evidence to identify the failing component
-   THEN investigate that specific component
-   ```
-
-   **Example:**
-   ```bash
-   # Layer 1: entry point
-   echo "=== Input received: ==="
-   echo "VAR: ${VAR:+SET}${VAR:-UNSET}"
-
-   # Layer 2: processing
-   echo "=== State after processing: ==="
-   env | grep VAR || echo "VAR not in environment"
-
-   # Layer 3: output/result
-   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
-
-Once you understand WHERE the break is, find existing working examples:
-
-1. **Find working code that solves the same problem**
-   - Search the codebase for similar patterns
-   - Check git history for when this worked
-   - Find the canonical implementation to compare against
-
-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 — 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
-
-1. **State your hypothesis explicitly:**
-   > "I believe the root cause is [X] because [evidence Y] and [evidence Z]."
-
-2. **Test the hypothesis minimally**
-   - Change one thing and observe the result
-   - If it doesn't confirm or deny, gather more evidence
-   - A confirmed hypothesis means you understand the root cause
-
-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; a one-off test script if no framework
-   - Use `Skill("mastermind-tdd")` for writing proper failing tests
-   - The test MUST fail before the fix proves it
-
-2. **Implement a single fix**
-   - Address the root cause identified in Phase 3
-   - ONE change at a time
-   - No "while I'm here" improvements
-   - No bundled refactoring
-
-3. **Verify the fix**
-   - Test passes now?
-   - No other tests broken?
-   - Issue actually resolved?
-   - Use `Skill("mastermind-review")` to verify before declaring done
-
-4. **If the fix doesn't work:**
-   - STOP
-   - Count: How many fixes have you tried?
-   - If < 3: Return to Phase 1, re-analyze with the new information
-   - **If ≥ 3: STOP — this is likely an architectural problem (see Phase 4.5 below)**
-   - Do NOT attempt a 4th fix without architectural discussion
-
----
-
-### Phase 4.5 — If 3+ Fixes Have Failed: Question the Architecture
-
-**Pattern indicating an architectural problem:**
-- Each fix reveals new coupling or shared state issues in a different place
-- Each fix creates new symptoms elsewhere
-- Fixes require "massive refactoring" to implement cleanly
-
-**STOP and question fundamentals:**
-- Is this design pattern fundamentally sound?
-- Are we continuing out of inertia?
-- Should we refactor the architecture rather than continue patching?
-
-**Discuss with the user before attempting more fixes.** This is not a failed hypothesis — this is the wrong architecture.
-
----
-
-## Red Flags — STOP and Return to Phase 1
-
-If you catch yourself thinking or doing any of these:
-
-| Thought / Action | What it means |
-|---|---|
-| "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. |
-| "One more fix attempt" (already tried 2+) | 3+ failures = architectural problem. Phase 4.5. |
-| Each fix reveals a new problem in a different place | Architectural problem. Phase 4.5. |
-
-## User Signals You're Doing It Wrong
-
-Watch for these redirections from the user:
-
-| Signal | What it means |
-|---|---|
-| "Is that actually happening?" | You assumed without verifying. Add evidence gathering. |
-| "What does the output show?" | You should have checked before proposing a fix. |
-| "Stop guessing" | You're proposing fixes without root cause. Phase 1. |
-| "We keep going in circles" | 3+ fix attempts = architectural problem. Phase 4.5. |
-
-## Common Rationalizations
-
-| Excuse | Reality |
-|---|---|
-| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
-| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
-| "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. |
-
-## Quick Reference
-
-| Phase | Key Activities | Success Criteria |
-|---|---|---|
-| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identified differences |
-| **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-tdd")` — for creating the failing test case (Phase 4, Step 1)
-- `Skill("mastermind-verify")` — verify the fix worked before claiming success
-
-## Impact
-
-Systematic approach vs random fixing:
-- Time to fix: 15-30 min vs 2-3 hours of thrashing
-- First-time fix rate: ~95% vs ~40%
-- New bugs introduced by the fix: near zero vs common
-# monomind:end skills:claude:mastermind-debug

package/.claude/skills/mastermind-design/SKILL.md

@@ -79,6 +79,7 @@ Invoke Skill("mastermind-plan")  ← TERMINAL STATE
 ### Understanding the idea
 
 - Check current project state first (files, docs, recent commits)
+- Check `brain_context` for relevant prior decisions, lessons, or patterns for this domain/project before drafting questions — if it surfaces something relevant (a past constraint, a lesson from a similar feature, a decision already made), say so to the user and let it steer which questions actually need asking. Do not silently re-ask what's already answered in `brain_context`.
 - Before asking detailed questions, assess scope: if the request describes multiple independent subsystems, flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
 - If too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order to build? Then design the first sub-project through the normal flow. Each sub-project gets its own spec → plan → implementation cycle.
 - For appropriately-scoped projects, ask questions one at a time
@@ -88,6 +89,7 @@ Invoke Skill("mastermind-plan")  ← TERMINAL STATE
 
 ### Exploring approaches
 
+- Check `brain_context` for approaches tried (and their outcomes) on similar past work before proposing new ones — prefer what worked, flag what didn't, and say when a proposed approach is informed by recalled history
 - Propose 2-3 different approaches with trade-offs
 - Present options conversationally with your recommendation and reasoning
 - Lead with the recommended option and explain why

package/.claude/skills/mastermind-execute/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mastermind-execute
-description: Load a written implementation plan, review it critically, execute all tasks step by step, and hand off to mastermind:finish when complete.
+description: Load a written implementation plan, review it critically, execute all tasks step by step, and hand off to mastermind:review when complete.
 type: domain-skill
 default_mode: confirm
 ---
@@ -11,7 +11,7 @@ Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the mastermind:execute skill to implement this plan."
 
-**Note:** This skill works best with subagent support (Claude Code). When subagents are available, prefer `Skill("mastermind-taskdev")` for parallel task execution.
+**Note:** This skill works best with subagent support (Claude Code). When subagents are available, dispatch one subagent per independent task in a single message.
 
 ---
 
@@ -47,116 +47,43 @@ For each task in the plan:
 3. Run verifications as specified in the plan
 4. Mark as `completed`
 
-When the plan references skills:
-- `mastermind:taskdev` → invoke `Skill("mastermind-taskdev")`
-- `mastermind:verify` → invoke `Skill("mastermind-verify")`
-- Any other `mastermind:*` skill → invoke `Skill("mastermind-<name>")`
-
-### Step 3: Complete Development
-
-After all tasks complete and are verified:
-
-- Announce: "All tasks complete. Handing off to mastermind:finish."
-- **REQUIRED SUB-SKILL:** invoke `Skill("mastermind-finish")`
-- Follow that skill to verify tests, present options, and execute the chosen finish action
-
----
-
-## When to Stop and Ask for Help
-
-**STOP executing immediately when:**
-- A blocker is encountered (missing dependency, failing test, unclear instruction)
-- The plan has critical gaps preventing a task from starting
-- An instruction cannot be understood without guessing
-- A verification fails repeatedly (more than twice)
-
-**Ask for clarification rather than guessing.** Never invent steps not in the plan.
-
----
-
-## When to Revisit Earlier Steps
-
-**Return to Step 1 (Review) when:**
-- The user updates the plan based on feedback
-- A fundamental approach needs rethinking due to new information
+**Dispatching subagents (when available):** when independent tasks can run in parallel, dispatch one subagent per task in a single message via the Task tool. Each subagent starts with no memory of this session — embed the plan step and the `brain_context` received in Inputs directly in its prompt so it has the same grounding this skill was given.
 
-**Do not force through blockers.** Stop and ask.
+**CRITICAL — variable substitution required:** before constructing the Task prompt, replace `${brain_context}` and `${project_name}` below with their actual literal values (the BRAIN CONTEXT block from Inputs, and the project name) — an unsubstituted `${brain_context}` placeholder means the subagent executes blind to prior decisions and constraints. This is the same substitution discipline `mastermind-idea/SKILL.md` uses for its Task prompts.
 
----
-
-## Rules
-
-- Review the plan critically before touching any code
-- Follow plan steps exactly — do not improvise
-- Do not skip verifications
-- Reference skills when the plan says to invoke them
-- Stop when blocked; never guess
-- Never start implementation on `main` or `master` without explicit user consent
+```javascript
+Task({
+  subagent_type: "coder", // pick per task, per the plan's agent recommendation
+  description: "<task title from plan>",
+  run_in_background: false, // true only when running independently alongside other parallel tasks
+  prompt: `You are executing one task from an implementation plan for project "${project_name}".
 
----
+BRAIN CONTEXT:
+${brain_context}
 
-## Integration
+TASK: <task title>
+STEPS:
+<verbatim bite-sized steps for this task from the plan>
 
-**Skills used by this skill:**
-- `Skill("mastermind-plan")` — creates the plan this skill executes
-- `Skill("mastermind-taskdev")` — subagent-driven parallel task execution (preferred for complex plans)
-- `Skill("mastermind-finish")` — complete the development branch after all tasks
-- `Skill("mastermind-verify")` — verification gate before finishing
-# monomind:start skills:claude:mastermind-execute
-# Mastermind Execute
+VERIFICATION:
+<verification command(s) from the plan>
 
-Load plan, review critically, execute all tasks, report when complete.
-
-**Announce at start:** "I'm using the mastermind:execute skill to implement this plan."
-
-**Note:** This skill works best with subagent support (Claude Code). When subagents are available, prefer `Skill("mastermind-taskdev")` for parallel task execution.
-
----
-
-## Inputs
-
-- `brain_context`: BRAIN CONTEXT block (injected by master, or loaded standalone via mastermind-protocol/SKILL.md brain load)
-- `plan_path`: path to the plan file to execute
-- `project_name`: monotask space name
-- `board_id`: monotask board ID
-- `mode`: auto | confirm
-
----
-
-## The Process
-
-### Step 1: Load and Review Plan
-
-1. Read the plan file at `plan_path`
-2. Review critically — identify any questions or concerns:
-   - Missing dependencies or prerequisites
-   - Ambiguous instructions
-   - Steps that contradict each other
-   - Verifications that cannot be run
-3. If concerns exist: raise them with the user before starting
-4. If no concerns: create a TodoWrite with each task and proceed
-
-### Step 2: Execute Tasks
-
-For each task in the plan:
-
-1. Mark as `in_progress`
-2. Follow each step exactly — the plan has bite-sized steps; do not skip or reorder
-3. Run verifications as specified in the plan
-4. Mark as `completed`
+Follow the steps exactly — do not skip, reorder, or invent steps not listed. Run the verification before reporting done.`
+})
+```
 
 When the plan references skills:
-- `mastermind:taskdev` → invoke `Skill("mastermind-taskdev")`
-- `mastermind:verify` → invoke `Skill("mastermind-verify")`
+- `mastermind:taskdev` → this skill; continue inline (no separate taskdev skill exists)
+- `mastermind:verify` → invoke `Skill("mastermind-review")`
 - Any other `mastermind:*` skill → invoke `Skill("mastermind-<name>")`
 
 ### Step 3: Complete Development
 
 After all tasks complete and are verified:
 
-- Announce: "All tasks complete. Handing off to mastermind:finish."
-- **REQUIRED SUB-SKILL:** invoke `Skill("mastermind-finish")`
-- Follow that skill to verify tests, present options, and execute the chosen finish action
+- Announce: "All tasks complete. Handing off to mastermind:review."
+- **REQUIRED SUB-SKILL:** invoke `Skill("mastermind-review")`
+- Follow that skill to verify the work before any merge, PR, or release step
 
 ---
 
@@ -170,6 +97,37 @@ After all tasks complete and are verified:
 
 **Ask for clarification rather than guessing.** Never invent steps not in the plan.
 
+**Required stop-report format.** When any condition above fires, report using this exact structure — never just "I'm stuck" or a bare "please advise":
+
+```
+STOP — <one-line description of what blocked>
+
+Task:      <the specific plan task/step that stopped, e.g. "Task 3: Add rate limiter">
+Tried:     <what was actually attempted — commands run, files checked, approaches tried — not just "it failed">
+Result:    <the actual error, output, or contradiction observed>
+Need:      <the exact decision or input required to unblock — a choice between named options,
+           a missing value, or explicit permission for a specific next step>
+```
+
+Example:
+
+```
+STOP — verification fails repeatedly on Task 3
+
+Task:      Task 3: Add rate limiter to /api/upload
+Tried:     Ran `npm test -- rate-limiter.test.ts` 3x after adding express-rate-limit
+           middleware per plan step 3.2. Confirmed middleware order matches the plan.
+           Checked for port conflicts (none). Re-read plan steps 3.1-3.4 — no gap found.
+Result:    Test "blocks after 100 requests/min" fails every run: expected 429, got 200.
+           express-rate-limit v7's `max` option appears to be silently ignored — same
+           failure with max:1.
+Need:      Decide between (a) pin express-rate-limit to v6 (last version where `max`
+           worked as documented) or (b) switch to a different limiter library — the plan
+           doesn't specify a version. Confirm which, or provide the correct v7 config.
+```
+
+The report must let the user act without re-deriving the investigation themselves — never a vague "please advise" with no Task/Tried/Result/Need detail.
+
 ---
 
 ## When to Revisit Earlier Steps
@@ -188,7 +146,7 @@ After all tasks complete and are verified:
 - Follow plan steps exactly — do not improvise
 - Do not skip verifications
 - Reference skills when the plan says to invoke them
-- Stop when blocked; never guess
+- Stop when blocked; never guess — use the required stop-report format above
 - Never start implementation on `main` or `master` without explicit user consent
 
 ---
@@ -197,7 +155,5 @@ After all tasks complete and are verified:
 
 **Skills used by this skill:**
 - `Skill("mastermind-plan")` — creates the plan this skill executes
-- `Skill("mastermind-taskdev")` — subagent-driven parallel task execution (preferred for complex plans)
-- `Skill("mastermind-finish")` — complete the development branch after all tasks
-- `Skill("mastermind-verify")` — verification gate before finishing
-# monomind:end skills:claude:mastermind-execute
+- `Skill("mastermind-review")` — verification gate after all tasks complete
+- `Skill("mastermind-debug")` — when a task fails for a reason the plan did not anticipate