monomind 1.16.11 → 1.17.1

package/.claude/commands/mastermind/master.md

@@ -41,15 +41,21 @@ If CLAUDE.md, GEMINI.md, or AGENTS.md says "skip review" and the skill says "alw
 
 **In Codex:** Skills load natively. Follow the instructions presented when a skill activates.
 
-**In other environments:** Check your platform's documentation for how skills are loaded. Skills speak in actions ("dispatch a subagent", "invoke the skill tool", "create a todo") rather than naming any one runtime's tools, so they translate across platforms.
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+### Platform Adaptation
+
+Mastermind skills speak in actions ("dispatch a subagent", "invoke the skill tool", "create a todo") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
 
 ### User Instructions vs. Skill Workflows
 
 User instructions say **WHAT** to do, not **HOW** to do it. "Build X" or "Fix Y" is a goal statement — it does not mean skip Brain Load, skip review, or bypass the domain decomposition flow. The skills define the how. Always apply the workflow unless the user explicitly opts out.
 
-### Command-to-Skill Routing
+### The Rule
+
+**Invoke the matching mastermind skill BEFORE any response or action.** Even a 1% chance a skill applies means you must check. If you invoke a skill and it turns out not to fit the situation, you don't need to follow it — but you must check first.
 
-Invoke the matching skill **before** doing anything else. Even a 1% chance a skill applies means you must check. If you invoke a skill and it turns out not to fit the situation, you don't need to follow it — but you must check first.
+### Command-to-Skill Routing
 
 ```dot
 digraph mastermind_routing {
@@ -341,6 +347,21 @@ curl -s -o /dev/null -X POST "${CTRL_URL}/api/mastermind/event" \
     '{type:"session:start",session:$sid,prompt:$prompt,mode:$mode,project:$proj,ts:(now*1000|floor)}')" || true
 ```
 
+### Step 3.5 — Design Gate
+
+<HARD-GATE>
+STOP before Step 4. If `domains_needed` includes `build` (or any code/feature/fix work):
+
+1. Invoke `Skill("mastermind:design")` NOW — pass `resolved_prompt` as the task description
+2. Do NOT write any code, do NOT spawn any domain managers, do NOT proceed to Step 4 until the design skill returns with an approved spec
+3. When design returns: save the approved spec as `build_spec` in `current.json`
+4. Only then continue to Step 4
+
+If `domains_needed` contains ONLY non-build domains (marketing, sales, research, content, ops, finance, idea): skip this gate and go directly to Step 4.
+
+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 4 — Decompose
 
 For each domain in `domains_needed`, assess complexity:
@@ -417,7 +438,39 @@ 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
 
-If mode = auto: proceed immediately.
+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).
+
+**Persist `build_exec_mode` to `current.json`** (required — Phase C reads it from there):
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+_get_mono_dir() {
+  local w="${1:-$(pwd)}"
+  if [ -d "$w/.git" ]; then echo "$w/.git/monomind"; return; fi
+  if [ -f "$w/.git" ]; then
+    local m; m=$(grep '^gitdir:' "$w/.git" | sed 's/gitdir: *//')
+    [ -z "$m" ] && { echo "$w/.monomind"; return; }
+    [[ "$m" != /* ]] && m="$w/$m"
+    echo "$(dirname "$(dirname "$m")")/monomind"; return
+  fi
+  echo "$w/.monomind"
+}
+MONO_DIR=$(_get_mono_dir "$REPO_ROOT")
+SESSION_STATE="$MONO_DIR/sessions/current.json"
+# LLM: replace EXEC_MODE_VALUE with the resolved value: taskdev or execute
+build_exec_mode="EXEC_MODE_VALUE"
+[ "$build_exec_mode" = "EXEC_MODE_VALUE" ] && build_exec_mode="taskdev"
+jq --arg m "$build_exec_mode" '. + {build_exec_mode: $m}' \
+  "$SESSION_STATE" > "$SESSION_STATE.tmp" && mv "$SESSION_STATE.tmp" "$SESSION_STATE"
+echo "build_exec_mode=$build_exec_mode written to current.json"
+```
 
 ### Step 6 — Monotask Setup
 
@@ -672,12 +725,15 @@ for domain in $(jq -r '.domains_needed[]? // empty' "$SESSION_STATE" | grep -v '
   if [ -z "$board_id" ]; then
     echo "WARN: DOMAIN=$domain has no board_id — Step 6 may not have run or monotask is missing. Task agent will run without board tracking."
   fi
+  exec_mode=""
+  [ "$domain" = "build" ] && exec_mode=$(jq -r '.build_exec_mode // "taskdev"' "$SESSION_STATE")
   echo "DOMAIN=$domain \
 MANAGER=$(jq -r --arg d "$domain" '.domain_managers[$d] // "coordinator"' "$SESSION_STATE") \
 BOARD=$board_id \
 TODO=$(jq -r --arg d "$domain" '.todo_cols[$d] // ""' "$SESSION_STATE") \
 DOING=$(jq -r --arg d "$domain" '.doing_cols[$d] // ""' "$SESSION_STATE") \
 DONE=$(jq -r --arg d "$domain" '.done_cols[$d] // ""' "$SESSION_STATE") \
+EXEC_MODE=$exec_mode \
 GOAL=$(jq -r --arg d "$domain" '.domain_goals[$d] // .prompt' "$SESSION_STATE" | tr -d '\n')"
 done
 ```
@@ -692,6 +748,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: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:taskdev")` if build_exec_mode is `taskdev`, or `Skill("mastermind:execute")` if `execute`. This was chosen by the user in Step 5."
 - 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/.claude/commands/mastermind/references/antigravity-tools.md

@@ -0,0 +1,60 @@
+# Antigravity CLI (`agy`) Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (`agy`) these resolve to the tools below.
+
+| Action skills request | Antigravity CLI equivalent |
+|----------------------|----------------------|
+| Read a file | `view_file` |
+| Create a new file | `write_to_file` |
+| Edit a file | `replace_file_content` |
+| Edit a file in several places at once | `multi_replace_file_content` |
+| Run a shell command | `run_command` |
+| Search file contents | `grep_search` |
+| Find files by name / list a directory | `list_dir` (no dedicated glob tool — combine `list_dir` with `grep_search`) |
+| Fetch a URL | `read_url_content` |
+| Search the web | `search_web` |
+| Pose a structured question to your human partner | `ask_question` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `invoke_subagent` with a built-in `TypeName` — `self` for full-capability work, `research` for read-only (see [Subagent support](#subagent-support)) |
+| Multiple parallel dispatches | Multiple entries in one `invoke_subagent` call's `Subagents` array |
+| Task tracking ("create a todo", "mark complete") | a **task artifact** — `write_to_file` with `IsArtifact: true` and `ArtifactType: "task"` (see [Task tracking](#task-tracking)). **Not** `manage_task`, which manages background processes. |
+
+## Invoking a skill — read its `SKILL.md`
+
+Antigravity surfaces every installed skill's `name` + `description` to you at the start of each session, but it has **no `Skill`/`activate_skill` tool**. To load a skill, **read its `SKILL.md` with `view_file`, setting `IsSkillFile: true`** when the skill applies — e.g. `view_file` on `.../mastermind/skills/<skill-name>/SKILL.md` with `IsSkillFile: true`.
+
+(`IsSkillFile` is agy's own signal that you're reading a file to *execute its instructions*, not to edit or preview it — set it whenever you load a skill.)
+
+This is the blessed skill-loading mechanism on this harness. The general rule "never read skill files manually" means "don't bypass your platform's skill-loading mechanism" — and on Antigravity, reading `SKILL.md` *is* that mechanism. Reading it honors the rule rather than breaking it.
+
+You already know which skills exist and what they're for: their names and descriptions are in front of you at session start. When a description matches what you're about to do, read that skill's `SKILL.md` before acting.
+
+## Subagent support
+
+Antigravity dispatches subagents with `invoke_subagent`, passing each one a `TypeName` in the `Subagents` array. Two `TypeName`s are **built in** — use them directly, no `define_subagent` needed:
+
+- **`self`** — a full clone of you, with every tool you have (including `write_to_file`/`replace_file_content`/`run_command`). The safe default for general-purpose work: implementing, fixing, anything that edits files or runs commands.
+- **`research`** — read-only (file reading, `grep_search`, web/URL fetch; no write or command access). Use it when you specifically want a subagent that can't make changes — investigation and read-only review.
+
+Call `define_subagent` only for a custom system prompt or capability mix: set `enable_write_tools: true` to grant file edits **and** `run_command`, `enable_subagent_tools` for nested dispatch, `enable_mcp_tools` for MCP. Then invoke it by the name you gave it.
+
+Skills dispatch with `Subagent (general-purpose):` and either reference a prompt-template file or supply an inline prompt. On Antigravity:
+
+| Skill dispatch form | Antigravity equivalent |
+|---------------------|----------------------|
+| An implementer-style template (writes code, runs tests) | Fill the template, then `invoke_subagent` with `TypeName: "self"` and the filled prompt |
+| A read-only reviewer template (`mastermind:review`) | `invoke_subagent` with `TypeName: "research"` and the filled review template |
+| Inline prompt (no template referenced) | `invoke_subagent` with `TypeName: "self"` (or `"research"` if the task only reads) 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_subagent`. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.
+
+### Parallel dispatch
+
+Put multiple entries in a single `invoke_subagent` call's `Subagents` array to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.
+
+## Task tracking
+
+Antigravity has **no todo / `TodoWrite` tool** (`manage_task` manages background processes — it is *not* a checklist). When a skill says to create a todo list or track tasks, maintain a **task artifact**: a markdown checklist saved with `write_to_file` (`IsArtifact: true`, `ArtifactMetadata.ArtifactType: "task"`), edited with `replace_file_content` / `multi_replace_file_content` as you go.
+
+At the start of any multi-step task, create the task artifact listing every step of your plan. As you complete each step, edit the artifact to mark it done (`- [x]`). If the plan changes, update the checklist. Keep it current — it is your source of truth for what remains; once the conversation gets long, re-read it before starting each step.

package/.claude/commands/mastermind/references/claude-code-tools.md

@@ -0,0 +1,50 @@
+# Claude Code Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Claude Code these resolve to the tools below.
+
+## Tools
+
+| Action skills request | Claude Code tool |
+|----------------------|------------------|
+| Read a file | `Read` |
+| Create a new file | `Write` |
+| Edit a file | `Edit` |
+| Run a shell command | `Bash` |
+| Search file contents | `Grep` |
+| Find files by name | `Glob` |
+| Fetch a URL | `WebFetch` |
+| Search the web | `WebSearch` |
+| Invoke a skill | `Skill` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `Agent` (older releases named this `Task`) |
+| Multiple parallel dispatches | Multiple `Agent` calls in one response |
+| Task tracking ("create a todo", "mark complete") | `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`; `TodoWrite` in `claude -p` / Agent SDK unless `CLAUDE_CODE_ENABLE_TASKS=1` is set |
+| Background-process / subagent lifecycle (read output, cancel) | `TaskOutput`, `TaskStop` — these are distinct from the todo tools above and apply to running shells, agents, and remote sessions |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Claude Code this is **`CLAUDE.md`**. Claude Code walks up the directory tree from the current working directory and concatenates every `CLAUDE.md` and `CLAUDE.local.md` it finds along the way. Standard locations:
+
+| Scope | Location |
+|-------|----------|
+| Project (team-shared) | `./CLAUDE.md` or `./.claude/CLAUDE.md` |
+| User global | `~/.claude/CLAUDE.md` |
+| Local-private (gitignored) | `./CLAUDE.local.md` |
+| Managed policy (org-wide) | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux/WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) |
+
+CLAUDE.md files can pull in additional content with `@path/to/file` imports (relative or absolute, max five hops deep). Subdirectory `CLAUDE.md` files are also discovered automatically and loaded on-demand when Claude Code reads files in those subdirectories.
+
+Claude Code does **not** read `AGENTS.md` directly. If a project already maintains `AGENTS.md` for other agents, import it from `CLAUDE.md` so both runtimes share the same instructions:
+
+```markdown
+@AGENTS.md
+
+## Claude Code
+
+(Claude-Code-specific instructions go here.)
+```
+
+For path-scoped rules and larger-project organization, see `.claude/rules/` (rules can be scoped to specific files via `paths` frontmatter and load on demand).
+
+## Personal skills directory
+
+User-level skills live at **`~/.claude/skills/`**. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter) plus any supporting files. Claude Code does not currently recognize the cross-runtime `~/.agents/skills/` path that Codex, Copilot CLI, and Gemini CLI read; if you're relying on cross-runtime support in the future, verify against the official skills docs.

package/.claude/commands/mastermind/references/codex-tools.md

@@ -0,0 +1,64 @@
+# Codex Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Codex these resolve to the tools below.
+
+| Action skills request | Codex equivalent |
+|----------------------|------------------|
+| Read a file | `shell` (e.g., `cat`, `head`, `tail`) — Codex reads files via shell |
+| Create / edit / delete a file | `apply_patch` (structured diff for create, update, delete) |
+| Run a shell command | `shell` |
+| Search file contents | `shell` (e.g., `grep`, `rg`) |
+| Find files by name | `shell` (e.g., `find`, `ls`) |
+| Fetch a URL | `shell` with `curl` / `wget` — Codex has no native fetch tool |
+| Search the web | `web_search` (enabled by default; configurable in `config.toml` via the top-level `web_search` setting — `live`, `cached`, or `disabled`) |
+| Invoke a skill | Skills load natively — just follow the instructions |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `spawn_agent` (see [Subagent dispatch requires multi-agent support](#subagent-dispatch-requires-multi-agent-support)) |
+| Multiple parallel dispatches | Multiple `spawn_agent` calls in one response |
+| Wait for subagent result | `wait_agent` |
+| Free up subagent slot when done | `close_agent` |
+| Task tracking ("create a todo", "mark complete") | `update_plan` |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Codex this is **`AGENTS.md`** at the project root. Codex also reads `~/.codex/AGENTS.md` for global context, and an `AGENTS.override.md` (in the project tree or `~/.codex/`) takes precedence when present. Codex walks from the project root down to the current working directory, concatenating `AGENTS.md` files it finds along the way, up to `project_doc_max_bytes` (32 KiB by default).
+
+## Personal skills directory
+
+User-level skills live at **`$CODEX_HOME/skills/`** (default `~/.codex/skills/`). Codex also reads the cross-runtime path **`~/.agents/skills/`** (shared with Copilot CLI and Gemini CLI). When both directories exist at the same scope, Codex loads them both as separate skill catalogs. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+
+## Subagent dispatch requires multi-agent support
+
+Add to your Codex config (`~/.codex/config.toml`):
+
+```toml
+[features]
+multi_agent = true
+```
+
+This enables `spawn_agent`, `wait_agent`, and `close_agent` for skills like `mastermind:taskdev` and `mastermind:review`.
+
+Legacy note: Codex builds before `rust-v0.115.0` exposed spawned-agent waiting as `wait`. Current Codex uses `wait_agent` for spawned agents. The `wait` name now belongs to code-mode `exec/wait`, which resumes a yielded exec cell by `cell_id`; it is not the spawned-agent result tool.
+
+## Environment Detection
+
+Skills that create worktrees or finish branches should detect their environment with read-only git commands before proceeding:
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+- `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
+- `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
+
+See `mastermind:worktree` Step 0 and `mastermind:finish` Step 1 for how each skill uses these signals.
+
+## Codex App Finishing
+
+When the sandbox blocks branch/push operations (detached HEAD in an externally managed worktree), the agent commits all work and informs the user to use the App's native controls:
+
+- **"Create branch"** — names the branch, then commit/push/PR via App UI
+- **"Hand off to local"** — transfers work to the user's local checkout
+
+The agent can still run tests, stage files, and output suggested branch names, commit messages, and PR descriptions for the user to copy.

package/.claude/commands/mastermind/references/copilot-tools.md

@@ -0,0 +1,49 @@
+# Copilot CLI Tool Mapping
+
+Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Copilot CLI these resolve to the tools below.
+
+| Action skills request | Copilot CLI equivalent |
+|----------------------|----------------------|
+| Read a file | `view` |
+| Create / edit / delete a file | `apply_patch` (Copilot CLI has no separate create/edit/write tools) |
+| Run a shell command | `bash` |
+| Search file contents | `rg` (ripgrep; Copilot CLI does not expose a `grep` tool) |
+| Find files by name | `glob` |
+| Fetch a URL | `web_fetch` |
+| Search the web | `web_search` |
+| Invoke a skill | `skill` |
+| Dispatch a subagent (`Subagent (general-purpose):` template) | `task` with `agent_type: "general-purpose"` (other accepted types: `explore`, `task`, `code-review`, `research`, `configure-copilot`) |
+| Multiple parallel dispatches | Multiple `task` calls in one response |
+| Subagent status/output/control | `read_agent`, `list_agents`, `write_agent` |
+| Task tracking ("create a todo", "mark complete") | `update_todo` |
+| Enter / exit plan mode | No equivalent — stay in the main session |
+
+## Instructions file
+
+When a skill mentions "your instructions file", on Copilot CLI this is **`AGENTS.md`** at the repository root. If both `AGENTS.md` and `.github/copilot-instructions.md` are present, Copilot reads both.
+
+## Personal skills directory
+
+User-level skills live at **`~/.copilot/skills/`**. Copilot CLI also recognizes the cross-runtime alias **`~/.agents/skills/`**, which is shared with Codex and Gemini CLI. Each skill is a subdirectory containing a `SKILL.md` (with `name` and `description` frontmatter).
+
+## Async shell sessions
+
+Copilot CLI supports persistent async shell sessions:
+
+| Tool | Purpose |
+|------|---------|
+| `bash` with `mode: "async"` (and optionally `detach: true`) | Start a long-running command in the background; returns a `shellId` |
+| `write_bash` | Send input to a running async session |
+| `read_bash` | Read output from an async session |
+| `stop_bash` | Terminate an async session |
+| `list_bash` | List all active shell sessions |
+
+## Additional Copilot CLI tools
+
+| Tool | Purpose |
+|------|---------|
+| `store_memory` | Persist facts about the codebase for future sessions |
+| `report_intent` | Update the UI status line with current intent |
+| `sql` | Query the session's SQLite database (todos, metadata) |
+| `fetch_copilot_cli_documentation` | Look up Copilot CLI documentation |
+| GitHub MCP tools (`github-mcp-server-*`) | Native GitHub API access (issues, PRs, code search) |

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

@@ -0,0 +1,63 @@
+# 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 |

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

@@ -0,0 +1,28 @@
+# 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.

package/.claude/helpers/mastermind-activate.cjs

@@ -0,0 +1,53 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+
+// Walk up from cwd to find the project root containing master.md
+function findMasterPath() {
+  const candidates = [];
+  if (process.env.CLAUDE_PROJECT_DIR) candidates.push(process.env.CLAUDE_PROJECT_DIR);
+  let dir = process.cwd();
+  for (let i = 0; i < 12; i++) {
+    candidates.push(dir);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  for (const base of candidates) {
+    const p = path.join(base, '.claude', 'commands', 'mastermind', 'master.md');
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+// Extract only the MASTERMIND PROTOCOL section (before the capability menu / execution flow).
+// The protocol section ends at the separator before "**If $ARGUMENTS is empty:**"
+function extractProtocol(content) {
+  const marker = '\n---\n\n**If $ARGUMENTS is empty:**';
+  const idx = content.indexOf(marker);
+  if (idx !== -1) return content.slice(0, idx).trim();
+  // Fallback: everything before the capability menu header
+  const fallback = content.indexOf('\n**MASTERMIND** —');
+  if (fallback !== -1) return content.slice(0, fallback).trim();
+  return content.trim();
+}
+
+const masterPath = findMasterPath();
+if (!masterPath) {
+  process.stderr.write('[mastermind-activate] master.md not found — skipping injection\n');
+  process.exit(0);
+}
+
+let raw;
+try {
+  raw = fs.readFileSync(masterPath, 'utf8');
+} catch (e) {
+  process.stderr.write('[mastermind-activate] Could not read master.md: ' + e.message + '\n');
+  process.exit(0);
+}
+
+// Strip YAML frontmatter
+const body = raw.replace(/^---[\s\S]*?---\s*/, '');
+const protocol = extractProtocol(body);
+
+process.stdout.write(protocol + '\n');

package/.claude/scheduled_tasks.lock

@@ -1 +1 @@
-{"sessionId":"db24c21a-e929-4aba-911b-4cdb7fc5c3d5","pid":2346,"procStart":"Wed Jun 24 16:31:36 2026","acquiredAt":1782380072591}
+{"sessionId":"361cc64c-bfbe-4774-a739-e3b982e26b21","pid":85888,"procStart":"Thu Jul  2 11:48:13 2026","acquiredAt":1782999721096}

package/.claude/settings.json

@@ -185,6 +185,10 @@
       }
     ],
     "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/mastermind-activate.cjs\"", "timeout": 5000 }]
+      },
       {
         "matcher": "",
         "hooks": [{ "type": "command", "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/monolean-activate.cjs\"", "timeout": 5000 }]

package/.claude/skills/mastermind/_repeat.md

@@ -27,6 +27,8 @@ If the stop file exists:
 
 ## Step 2 — Tillend termination check (tillend mode only — skip for fixed-count)
 
+**`LOOP_ASYNC_PENDING` escape hatch:** If the calling skill set `LOOP_ASYNC_PENDING=true` before invoking this postamble (because it spawned background agents whose results have not yet arrived), skip the empty-round check and go directly to Step 4 to schedule the next run. Output: `[tillend] Async work in flight — deferring empty-round check to run <next_rep>.`
+
 Evaluate now whether this run produced **zero findings AND zero actions**:
 
 - **Findings**: issues found, problems detected, items flagged, security vulnerabilities, tasks discovered, errors reported

package/.claude/skills/mastermind/runorg.md

@@ -477,6 +477,20 @@ If the file exists: write run:complete to run file, emit org:complete via curl,
 OPERATING LOOP:
 1. Check for stop signal (above). Exit with run:complete + org:complete events if found.
 
+1b. Check user mailbox for pending messages:
+   _threads="${REPO_ROOT}/.monomind/orgs/${orgName}-threads.json"
+   if [ -f "$_threads" ]; then
+     _pending=$(jq '[.[] | select(.status == "pending")]' "$_threads" 2>/dev/null || echo "[]")
+     if [ "$(echo "$_pending" | jq 'length')" -gt 0 ]; then
+       echo "$_pending" | jq -r '.[] | .text // .msg // ""'
+       jq '[.[] | if .status == "pending" then .status = "processed" else . end]' "$_threads" > "${_threads}.tmp" && mv "${_threads}.tmp" "$_threads" || true
+       curl -s -X POST "${CTRL_URL}/api/mastermind/event" -H "Content-Type: application/json" \
+         -d "$(jq -cn --arg s "${sessionId}" --arg o "${orgName}" --arg rid "${runId}" \
+           --arg msg "Received user message — adjusting plan if needed" \
+           '{type:"org:comms",session:$s,org:$o,runId:$rid,from:"boss",to:"user",msg:$msg,ts:(now*1000|floor)}')" || true
+     fi
+   fi
+
 2. List unclaimed Todo cards:
    monotask card list ${board_id} --col ${todo_col} --json | jq '[.[] | select(.labels | index("claimed") | not)]'
 

package/.claude/skills/mastermind/techport.md

@@ -27,7 +27,7 @@ If invoked directly (not by `mastermind:master`):
 - `focus_hint`: optional — what to look for ("CLI commands", "animation", "hooks", "skills"); default: `"core architecture skills commands hooks agents"`
 - `mode`: confirm | auto
 - `partial`: boolean — if true, skip strategy (a) Copy-As-Is; force (b) Adapt or (c) Extract only
-- `source_brand`: derived in Phase 1A — PascalCase brand name of the source project (e.g. `RuvSwarm`, `ClaudeFlow`); used in all `rg -i "{source_brand}"` brand contamination checks
+- `source_brand`: derived in Phase 1A — PascalCase brand name of the source project (e.g. `Monomind`, `ClaudeFlow`); used in all `rg -i "{source_brand}"` brand contamination checks
 - `candidate_file`: derived during Phase 1E–1F — absolute path to a specific source file under analysis; substituted before running per-candidate coupling checks
 
 ---
@@ -192,11 +192,11 @@ head -80 "{source_path}/README.md" 2>/dev/null
 **BRAND EXTRACTION — required before Phase 2B collision detection:**
 
 Extract `source_brand` from three signals, pick the most specific:
-1. `package.json` `name` field: strip `@scope/` prefix, convert to PascalCase (e.g., `claude-flow` → `ClaudeFlow`, `ruv-swarm` → `RuvSwarm`)
+1. `package.json` `name` field: strip `@scope/` prefix, convert to PascalCase (e.g., `claude-flow` → `ClaudeFlow`, `monomind` → `Monomind`)
 2. README H1 title: extract the project name word(s) before any tagline
-3. Class name prefixes: run `grep -rhn "^export class\|^export abstract class" "{source_path}/src" --include="*.ts" 2>/dev/null | grep -oE "(class) [A-Z][A-Za-z0-9]+" | awk '{print $2}' | grep -oE "^[A-Z][a-z]+" | sort | uniq -c | sort -rn | head -5` — the most frequent leading word (e.g., `Ruv` from `RuvSwarm`, `Claude` from `ClaudeFlow`) is the brand prefix; convert to PascalCase compound if needed
+3. Class name prefixes: run `grep -rhn "^export class\|^export abstract class" "{source_path}/src" --include="*.ts" 2>/dev/null | grep -oE "(class) [A-Z][A-Za-z0-9]+" | awk '{print $2}' | grep -oE "^[A-Z][a-z]+" | sort | uniq -c | sort -rn | head -5` — the most frequent leading word (e.g., `Mono` from `Monomind`, `Claude` from `ClaudeFlow`) is the brand prefix; convert to PascalCase compound if needed
 
-Set `source_brand` to the PascalCase result (e.g., `RuvSwarm`, `ClaudeFlow`, `SourceProject`). This variable is used verbatim in all subsequent `rg -i "{source_brand}"` calls and the collision-detection Python script.
+Set `source_brand` to the PascalCase result (e.g., `Monomind`, `ClaudeFlow`, `SourceProject`). This variable is used verbatim in all subsequent `rg -i "{source_brand}"` calls and the collision-detection Python script.
 
 ### 1B — Repo-Map (Structural Index)
 
@@ -359,7 +359,7 @@ grep -rhn "^export" "{source_path}/src" --include="*.ts" 2>/dev/null | \
   grep -oE "(class|interface|function|const|type|enum) [A-Z][A-Za-z0-9]+" | awk '{print $2}' | \
   python3 -c "
 import sys, re
-source_brand = '{source_brand}'  # LLM substitutes the PascalCase value from Phase 1A before running (e.g. 'RuvSwarm', 'ClaudeFlow')
+source_brand = '{source_brand}'  # LLM substitutes the PascalCase value from Phase 1A before running (e.g. 'Monomind', 'ClaudeFlow')
 # Mono prefix: the domain prefix used in monomind for this context (e.g. 'Mono', 'Agent', 'Graph')
 # LLM: substitute the actual mono prefix from Phase 0B's MNS before running
 mono_prefix = '{mono_prefix}'

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/monoes/monomind/main/assets/mascot.png" alt="Monomind" width="140" />
+  <img src="assets/banner.png" alt="Monomind" width="600" />
 </p>
 
 <h1 align="center">Monomind</h1>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monomind",
-  "version": "1.16.11",
+  "version": "1.17.1",
   "description": "Monomind - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",
@@ -63,7 +63,7 @@
   "dependencies": {
     "semver": "^7.6.0",
     "zod": "^3.22.0",
-    "@monoes/monograph": "^1.2.5",
+    "@monoes/monograph": "^1.2.2",
     "@monoes/monobrowse": "^1.0.0"
   },
   "overrides": {
@@ -123,7 +123,6 @@
     "url": "https://github.com/monoes/monomind.git"
   },
   "keywords": [
-    "ruvflow",
     "claude",
     "claude-code",
     "anthropic",
@@ -152,10 +151,12 @@
     "embeddings",
     "machine-learning",
     "neural-network",
-    "hive-mind",
+    "monomind",
     "distributed-systems",
     "consensus",
-    "self-learning"
+    "self-learning",
+    "harness",
+    "organizations"
   ],
   "author": {
     "name": "nokhodian",

package/packages/@monomind/cli/.claude/agents/engineering/engineering-security-engineer.md

@@ -24,7 +24,7 @@ capability:
   model_preference: opus
   termination: All identified vulnerabilities have remediation steps documented
   triggers:
-    - pattern: "\\b(auth|jwt|session|oauth|saml|oidc|csrf|xss|sql.injection|ssrf|rce|lfi)\\b"
+    - pattern: "\\b(jwt|oauth|saml|oidc|csrf|xss|sql.injection|ssrf|rce|lfi|session\\W{0,3}(hijack|fixation|token\\W{0,3}theft)\\w*|auth\\w*\\W{0,3}(bypass|bug|vuln|flaw|exploit)\\w*)\\b"
       mode: "inject"
     - pattern: "CVE-\\d{4}-\\d+"
       mode: "inject"