@monoes/monomindcli 2.10.4 → 2.10.6

package/.claude/helpers/handlers/gates-handler.cjs

@@ -227,14 +227,6 @@ const FALLBACK_DESTRUCTIVE_PATTERNS = [
 ];
 
 const FALLBACK_SECRET_PATTERNS = [
-  /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{8,}['"]/gi,
-  /(?:secret|password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/gi,
-  /(?:token|bearer)\s*[:=]\s*['"][^'"]{10,}['"]/gi,
-  // Unquoted variants — env-style `KEY=value` / `key: value` with no quotes,
-  // e.g. `ANTHROPIC_API_KEY=sk-ant-...` in a .env file or shell export. The
-  // quoted patterns above never match these, which was the single most
-  // common real leak pattern (P1-25).
-  /(?:api[_-]?key|apikey|token|secret|password|passwd|pwd)\s*[:=]\s*[^\s'"]{8,}/gi,
   /-----BEGIN (?:RSA |EC |DSA )?PRIVATE KEY-----/g,
   /sk-ant-[a-zA-Z0-9_-]{20,}/g,
   /sk-[a-zA-Z0-9_-]{20,}/g,
@@ -243,6 +235,35 @@ const FALLBACK_SECRET_PATTERNS = [
   /AKIA[0-9A-Z]{16}/g,
 ];
 
+// Field names alone do not make a value a credential: schemas, API wire
+// contracts, and ordinary fixtures legitimately use names such as `token` or
+// `apiKey`. Check an assigned value separately, and only block it when it has
+// the characteristics of an actual generated secret. Recognizable provider
+// formats remain covered by the precise patterns above.
+const GENERIC_SECRET_ASSIGNMENT =
+  /(?:api[_-]?key|apikey|token|secret|password|passwd|pwd|bearer)\s*[:=]\s*(?:'[^'\r\n]*'|"[^"\r\n]*"|[^\s'"\r\n]+)/gi;
+
+function isFixtureOrPlaceholder(value) {
+  return /(?:test|fixture|example|sample|placeholder|dummy|fake|not[-_ ]?(?:a[-_ ]?)?real)/i.test(value);
+}
+
+function hasSecretLikeEntropy(value) {
+  if (value.length < 20 || /\s/.test(value)) return false;
+  var characterClasses = 0;
+  if (/[a-z]/.test(value)) characterClasses++;
+  if (/[A-Z]/.test(value)) characterClasses++;
+  if (/\d/.test(value)) characterClasses++;
+  if (/[^a-zA-Z0-9]/.test(value)) characterClasses++;
+  return characterClasses >= 3 && new Set(value).size >= 10;
+}
+
+function isLikelySecretAssignment(match) {
+  var separator = match.search(/[:=]/);
+  if (separator === -1) return true;
+  var value = match.slice(separator + 1).trim().replace(/^(?:'|")|(?:'|")$/g, '');
+  return !isFixtureOrPlaceholder(value) && hasSecretLikeEntropy(value);
+}
+
 // ─── Compiled config loader ─────────────────────────────────────────────────
 
 var MAX_CONFIG_SIZE = 256 * 1024; // 256 KiB — compiled gate config is small
@@ -317,20 +338,32 @@ function checkDestructive(command, patterns) {
 
 function checkSecrets(content, patterns) {
   var list = patterns || FALLBACK_SECRET_PATTERNS;
-  const found = [];
+  const found = new Set();
   for (const pattern of list) {
     pattern.lastIndex = 0;
     const matches = content.match(pattern);
     if (matches) {
-      for (const m of matches) found.push(redact(m));
+      for (const m of matches) {
+        if (isLikelySecretAssignment(m)) found.add(redact(m));
+      }
+    }
+  }
+  // Value-aware handling for generic field names. This is intentionally kept
+  // out of FALLBACK_SECRET_PATTERNS so callers cannot mistake an identifier
+  // match for proof that the value is a credential.
+  GENERIC_SECRET_ASSIGNMENT.lastIndex = 0;
+  const assignments = content.match(GENERIC_SECRET_ASSIGNMENT);
+  if (assignments) {
+    for (const assignment of assignments) {
+      if (isLikelySecretAssignment(assignment)) found.add(redact(assignment));
     }
   }
-  if (found.length === 0) return { triggered: false };
+  if (found.size === 0) return { triggered: false };
   return {
     triggered: true,
-    count: found.length,
-    redacted: found,
-    reason: `Potential secret(s) detected in file content (${found.length} match${found.length > 1 ? 'es' : ''}): ${found.join(', ')}. Move secrets to environment variables or a .env file (add to .gitignore).`,
+    count: found.size,
+    redacted: [...found],
+    reason: `Potential secret(s) detected in file content (${found.size} match${found.size > 1 ? 'es' : ''}): ${[...found].join(', ')}. Move secrets to environment variables or a .env file (add to .gitignore).`,
   };
 }
 

package/.claude/settings.json

@@ -443,4 +443,4 @@
   "enabledMcpjsonServers": [
     "monomind"
   ]
-}
+}

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

@@ -19,3 +19,18 @@ Use Monograph before broad repository search when the platform exposes the
 Monomind MCP server. Without native skills, run
 `monomind mastermind run <skill> --print` and follow the printed procedure.
 Platform tool mappings are in [references/](references/).
+# monomind:start skills:claude:mastermind
+# Mastermind
+
+Load only the workflow that matches the current task:
+- `mastermind` — Route a request to the relevant Mastermind workflow.
+- `mastermind-plan` — Write a detailed implementation plan before changing code.
+- `mastermind-review` — Review code, content, strategy, or security work.
+- `mastermind-debug` — Investigate a failure or unexpected behavior before fixing it.
+- `mastermind-research` — Research an open question before making a decision.
+- `mastermind-execute` — Execute a written implementation plan step by step.
+- `mastermind-org` — Create, run, inspect, and manage a Mastermind organization.
+- `mastermind-memory` — Store, retrieve, and maintain persistent organization knowledge.
+
+If skills cannot be loaded natively, run `monomind mastermind run <skill> --print`.
+# monomind:end skills:claude:mastermind

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

@@ -58,3 +58,65 @@ Put multiple entries in a single `invoke_subagent` call's `Subagents` array to r
 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.
+# monomind:start skills:claude:mastermind:references/antigravity-tools.md
+# 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.
+# monomind:end skills:claude:mastermind:references/antigravity-tools.md

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

@@ -48,3 +48,55 @@ For path-scoped rules and larger-project organization, see `.claude/rules/` (rul
 ## 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.
+# monomind:start skills:claude:mastermind:references/claude-code-tools.md
+# 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.
+# monomind:end skills:claude:mastermind:references/claude-code-tools.md

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

@@ -62,3 +62,69 @@ When the sandbox blocks branch/push operations (detached HEAD in an externally m
 - **"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.
+# monomind:start skills:claude:mastermind:references/codex-tools.md
+# 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.
+# monomind:end skills:claude:mastermind:references/codex-tools.md

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

@@ -47,3 +47,54 @@ Copilot CLI supports persistent async shell sessions:
 | `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) |
+# monomind:start skills:claude:mastermind:references/copilot-tools.md
+# 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) |
+# monomind:end skills:claude:mastermind:references/copilot-tools.md

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

@@ -61,3 +61,68 @@ 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,3 +26,33 @@ 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

@@ -71,11 +71,19 @@ Exactly one role must have `reports_to: null`. If the user's role list has none,
 
 A role is **persona-based** if its title is a named real person, a well-known fictional character, or a celebrity/historical figure referred to by name. An org is persona-based if ≥50% of its roles are character names, or the goal/prompt contains `panel`, `debate`, `simulation`, `roleplay`, `celebrity`, `character`, `virtual [name]`, `impersonate`, `as [name]`.
 
-Persona roles work the same as any other role in v2 — there is no separate `agent_type`/subagent registry to resolve against. Put the character depth directly into `responsibilities` (the only field `buildRolePrompt` — `orgrt/session.ts:27-39` — actually feeds into the agent's role briefing): write 3-6 specific, voice-defining responsibilities drawn from the character's known career, positions, and communication style, not generic duties. For a living public figure, base it on documented public behavior — do not invent positions they haven't taken.
+Persona roles work the same as any other role in v2 — there is no separate `agent_type`/subagent registry to resolve against. Put the character depth directly into `responsibilities` (fed into the agent's role briefing by `buildRolePrompt` in `orgrt/session.ts`, alongside `ui.icon`'s built-in archetype content and `instructions_file`, if either is set — see Step 2.3): write 3-6 specific, voice-defining responsibilities drawn from the character's known career, positions, and communication style, not generic duties. For a living public figure, base it on documented public behavior — do not invent positions they haven't taken.
 
 ---
 
-## Step 2.3 — Optional Per-Role Settings
+## Step 2.3 — Built-in Archetype Best-Practices (fully optional — skip freely)
+
+createorg does **not** need to use these bundled archetypes for anything — a role built entirely from `responsibilities` is complete and normal. This step is a shortcut to reach for only when a role you're scaffolding happens to match one of the ~111 bundled role archetypes (the same set the MonoAgent Org Designer's palette offers — coder, security-auditor, devops-automator, sales-engineer, and so on; see `src/orgrt/role-skills/` for the full list of ids). When it does, set that role's `ui.icon` to the matching archetype id: `"ui": { "icon": "security-auditor" }`. At session start, `buildRolePrompt` then injects that archetype's bundled best-practices document into the role's briefing — real, researched guidance (tool checklists, common pitfalls, domain-specific techniques) for free, with zero extra fields to author. This is purely additive to `responsibilities` (which still carries the role's specific duties for THIS org) — don't duplicate general best-practices guidance into `responsibilities` when a matching `ui.icon` would supply it automatically; do still use `responsibilities` for anything specific to this particular org/goal.
+
+Skip `ui.icon` whenever there isn't a clean match — an unmatched or omitted `icon` is normal and not an error, it just means the role gets no bundled content (still fine; `responsibilities` alone is enough for most roles). Never force-fit a role into a nearby-but-wrong archetype just to get the bundled content.
+
+---
+
+## Step 2.4 — Optional Per-Role Settings
 
 For any role that needs non-default behavior, set (all optional — omit to inherit defaults):
 
@@ -125,7 +133,7 @@ Produce an org config object matching `OrgDefSchema` exactly:
 
 `status` starts `"stopped"` regardless of whether `schedule` is set — the org does not run until `monomind org run <name>` (one-shot) or `monomind org serve` (picks up any org whose `schedule` is set) is invoked.
 
-Only include `adapter_config`, `provider`, or `policy` on a role when Step 2.3 populated them for it — leave them out entirely rather than writing empty objects.
+Only include `adapter_config`, `provider`, `policy`, or `ui` on a role when Step 2.3/2.4 populated them for it — leave them out entirely rather than writing empty objects.
 
 ---