monomind 1.16.10 → 1.17.0

package/packages/@monomind/cli/.claude/agents/github/swarm-pr.md

@@ -17,14 +17,14 @@ Create and manage AI swarms directly from GitHub Pull Requests, enabling seamles
 
 ```bash
 # Create swarm from PR description using gh CLI
-gh pr view 123 --json body,title,labels,files | npx ruv-swarm swarm create-from-pr
+gh pr view 123 --json body,title,labels,files | npx monomind swarm create-from-pr
 
 # Auto-spawn agents based on PR labels
-gh pr view 123 --json labels | npx ruv-swarm swarm auto-spawn
+gh pr view 123 --json labels | npx monomind swarm auto-spawn
 
 # Create swarm with PR context
 gh pr view 123 --json body,labels,author,assignees | \
-  npx ruv-swarm swarm init --from-pr-data
+  npx monomind swarm init --from-pr-data
 ```
 
 ### 2. PR Comment Commands
@@ -59,7 +59,7 @@ jobs:
       - name: Handle Swarm Command
         run: |
           if [[ "${{ github.event.comment.body }}" == /swarm* ]]; then
-            npx ruv-swarm github handle-comment \
+            npx monomind github handle-comment \
               --pr ${{ github.event.pull_request.number }} \
               --comment "${{ github.event.comment.body }}"
           fi
@@ -89,7 +89,7 @@ Map PR labels to agent types:
 # Small PR (< 100 lines): ring topology
 # Medium PR (100-500 lines): mesh topology
 # Large PR (> 500 lines): hierarchical topology
-npx ruv-swarm github pr-topology --pr 123
+npx monomind github pr-topology --pr 123
 ```
 
 ## PR Swarm Commands
@@ -101,7 +101,7 @@ npx ruv-swarm github pr-topology --pr 123
 PR_DIFF=$(gh pr diff 123)
 PR_INFO=$(gh pr view 123 --json title,body,labels,files,reviews)
 
-npx ruv-swarm github pr-init 123 \
+npx monomind github pr-init 123 \
   --auto-agents \
   --pr-data "$PR_INFO" \
   --diff "$PR_DIFF" \
@@ -112,7 +112,7 @@ npx ruv-swarm github pr-init 123 \
 
 ```bash
 # Post swarm progress to PR using gh CLI
-PROGRESS=$(npx ruv-swarm github pr-progress 123 --format markdown)
+PROGRESS=$(npx monomind github pr-progress 123 --format markdown)
 
 gh pr comment 123 --body "$PROGRESS"
 
@@ -129,7 +129,7 @@ fi
 PR_FILES=$(gh pr view 123 --json files --jq '.files[].path')
 
 # Run swarm review
-REVIEW_RESULTS=$(npx ruv-swarm github pr-review 123 \
+REVIEW_RESULTS=$(npx monomind github pr-review 123 \
   --agents "security,performance,style" \
   --files "$PR_FILES")
 
@@ -149,7 +149,7 @@ done
 
 ```bash
 # Coordinate swarms across related PRs
-npx ruv-swarm github multi-pr \
+npx monomind github multi-pr \
   --prs "123,124,125" \
   --strategy "parallel" \
   --share-memory
@@ -159,7 +159,7 @@ npx ruv-swarm github multi-pr \
 
 ```bash
 # Analyze PR dependencies
-npx ruv-swarm github pr-deps 123 \
+npx monomind github pr-deps 123 \
   --spawn-agents \
   --resolve-conflicts
 ```
@@ -168,7 +168,7 @@ npx ruv-swarm github pr-deps 123 \
 
 ```bash
 # Auto-fix PR issues
-npx ruv-swarm github pr-fix 123 \
+npx monomind github pr-fix 123 \
   --issues "lint,test-failures" \
   --commit-fixes
 ```
@@ -209,7 +209,7 @@ required_status_checks:
 ```bash
 # Auto-merge when swarm completes using gh CLI
 # Check swarm completion status
-SWARM_STATUS=$(npx ruv-swarm github pr-status 123)
+SWARM_STATUS=$(npx monomind github pr-status 123)
 
 if [[ "$SWARM_STATUS" == "complete" ]]; then
   # Check review requirements
@@ -236,7 +236,7 @@ createServer((req, res) => {
     const event = JSON.parse(body);
 
     if (event.action === "opened" && event.pull_request) {
-      execSync(`npx ruv-swarm github pr-init ${event.pull_request.number}`);
+      execSync(`npx monomind github pr-init ${event.pull_request.number}`);
     }
 
     res.writeHead(200);
@@ -251,7 +251,7 @@ createServer((req, res) => {
 
 ```bash
 # PR #456: Add user authentication
-npx ruv-swarm github pr-init 456 \
+npx monomind github pr-init 456 \
   --topology hierarchical \
   --agents "architect,coder,tester,security" \
   --auto-assign-tasks
@@ -261,7 +261,7 @@ npx ruv-swarm github pr-init 456 \
 
 ```bash
 # PR #789: Fix memory leak
-npx ruv-swarm github pr-init 789 \
+npx monomind github pr-init 789 \
   --topology mesh \
   --agents "debugger,analyst,tester" \
   --priority high
@@ -271,7 +271,7 @@ npx ruv-swarm github pr-init 789 \
 
 ```bash
 # PR #321: Update API docs
-npx ruv-swarm github pr-init 321 \
+npx monomind github pr-init 321 \
   --topology ring \
   --agents "researcher,writer,reviewer" \
   --validate-links
@@ -283,7 +283,7 @@ npx ruv-swarm github pr-init 321 \
 
 ```bash
 # Generate PR swarm report
-npx ruv-swarm github pr-report 123 \
+npx monomind github pr-report 123 \
   --metrics "completion-time,agent-efficiency,token-usage" \
   --format markdown
 ```
@@ -292,7 +292,7 @@ npx ruv-swarm github pr-report 123 \
 
 ```bash
 # Export to GitHub Insights
-npx ruv-swarm github export-metrics \
+npx monomind github export-metrics \
   --pr 123 \
   --to-insights
 ```

package/packages/@monomind/cli/.claude/agents/github/workflow-automation.md

@@ -34,7 +34,7 @@ jobs:
 
       - name: Analyze Changes
         run: |
-          npx ruv-swarm actions analyze \
+          npx monomind actions analyze \
             --commit ${{ github.sha }} \
             --suggest-tests \
             --optimize-pipeline
@@ -44,7 +44,7 @@ jobs:
 
 ```bash
 # Generate workflows based on code analysis
-npx ruv-swarm actions generate-workflow \
+npx monomind actions generate-workflow \
   --analyze-codebase \
   --detect-languages \
   --create-optimal-pipeline
@@ -56,7 +56,7 @@ npx ruv-swarm actions generate-workflow \
 # Smart test runner
 - name: Swarm Test Selection
   run: |
-    npx ruv-swarm actions smart-test \
+    npx monomind actions smart-test \
       --changed-files ${{ steps.files.outputs.all }} \
       --impact-analysis \
       --parallel-safe
@@ -80,12 +80,12 @@ jobs:
       - name: Detect Languages
         id: detect
         run: |
-          npx ruv-swarm actions detect-stack \
+          npx monomind actions detect-stack \
             --output json > stack.json
 
       - name: Dynamic Build Matrix
         run: |
-          npx ruv-swarm actions create-matrix \
+          npx monomind actions create-matrix \
             --from stack.json \
             --parallel-builds
 ```
@@ -107,7 +107,7 @@ jobs:
       - name: Security Analysis Swarm
         run: |
           # Use gh CLI for issue creation
-          SECURITY_ISSUES=$(npx ruv-swarm actions security \
+          SECURITY_ISSUES=$(npx monomind actions security \
             --deep-scan \
             --format json)
 
@@ -129,7 +129,7 @@ jobs:
 
 ```bash
 # Optimize existing workflows
-npx ruv-swarm actions optimize \
+npx monomind actions optimize \
   --workflow ".github/workflows/ci.yml" \
   --suggest-parallelization \
   --reduce-redundancy \
@@ -141,7 +141,7 @@ npx ruv-swarm actions optimize \
 ```bash
 # Analyze failed runs using gh CLI
 gh run view ${{ github.run_id }} --json jobs,conclusion | \
-  npx ruv-swarm actions analyze-failure \
+  npx monomind actions analyze-failure \
     --suggest-fixes \
     --auto-retry-flaky
 
@@ -158,7 +158,7 @@ fi
 
 ```bash
 # Optimize resource usage
-npx ruv-swarm actions resources \
+npx monomind actions resources \
   --analyze-usage \
   --suggest-runners \
   --cost-optimize
@@ -180,7 +180,7 @@ jobs:
     steps:
       - name: Diagnose and Fix
         run: |
-          npx ruv-swarm actions self-heal \
+          npx monomind actions self-heal \
             --run-id ${{ github.event.workflow_run.id }} \
             --auto-fix-common \
             --create-pr-complex
@@ -202,13 +202,13 @@ jobs:
       - name: Analyze Risk
         id: risk
         run: |
-          npx ruv-swarm actions deploy-risk \
+          npx monomind actions deploy-risk \
             --changes ${{ github.sha }} \
             --history 30d
 
       - name: Choose Strategy
         run: |
-          npx ruv-swarm actions deploy-strategy \
+          npx monomind actions deploy-strategy \
             --risk ${{ steps.risk.outputs.level }} \
             --auto-execute
 ```
@@ -226,7 +226,7 @@ jobs:
     steps:
       - name: Performance Analysis
         run: |
-          npx ruv-swarm actions perf-test \
+          npx monomind actions perf-test \
             --baseline main \
             --threshold 10% \
             --auto-profile-regression
@@ -246,7 +246,7 @@ runs: using: "node16";
 main: "dist/index.js";
 
 // index.js
-const { SwarmAction } = require("ruv-swarm");
+const { SwarmAction } = require("monomind");
 
 async function run() {
   const swarm = new SwarmAction({
@@ -271,7 +271,7 @@ jobs:
     steps:
       - id: set-matrix
         run: |
-          MATRIX=$(npx ruv-swarm actions test-matrix \
+          MATRIX=$(npx monomind actions test-matrix \
             --detect-frameworks \
             --optimize-coverage)
           echo "matrix=${MATRIX}" >> $GITHUB_OUTPUT
@@ -286,7 +286,7 @@ jobs:
 
 ```bash
 # Determine optimal parallelization
-npx ruv-swarm actions parallel-strategy \
+npx monomind actions parallel-strategy \
   --analyze-dependencies \
   --time-estimates \
   --cost-aware
@@ -298,7 +298,7 @@ npx ruv-swarm actions parallel-strategy \
 
 ```bash
 # Analyze workflow performance
-npx ruv-swarm actions analytics \
+npx monomind actions analytics \
   --workflow "ci.yml" \
   --period 30d \
   --identify-bottlenecks \
@@ -309,7 +309,7 @@ npx ruv-swarm actions analytics \
 
 ```bash
 # Optimize GitHub Actions costs
-npx ruv-swarm actions cost-optimize \
+npx monomind actions cost-optimize \
   --analyze-usage \
   --suggest-caching \
   --recommend-self-hosted
@@ -319,7 +319,7 @@ npx ruv-swarm actions cost-optimize \
 
 ```bash
 # Identify failure patterns
-npx ruv-swarm actions failure-patterns \
+npx monomind actions failure-patterns \
   --period 90d \
   --classify-failures \
   --suggest-preventions
@@ -343,7 +343,7 @@ jobs:
           PR_DATA=$(gh pr view ${{ github.event.pull_request.number }} --json files,labels)
 
           # Run validation with swarm
-          RESULTS=$(npx ruv-swarm actions pr-validate \
+          RESULTS=$(npx monomind actions pr-validate \
             --spawn-agents "linter,tester,security,docs" \
             --parallel \
             --pr-data "$PR_DATA")
@@ -367,7 +367,7 @@ jobs:
     steps:
       - name: Release Swarm
         run: |
-          npx ruv-swarm actions release \
+          npx monomind actions release \
             --analyze-changes \
             --generate-notes \
             --create-artifacts \
@@ -388,7 +388,7 @@ jobs:
     steps:
       - name: Documentation Swarm
         run: |
-          npx ruv-swarm actions update-docs \
+          npx monomind actions update-docs \
             --analyze-changes \
             --update-api-docs \
             --check-examples
@@ -423,7 +423,7 @@ jobs:
 
 ```bash
 # Predict potential failures
-npx ruv-swarm actions predict \
+npx monomind actions predict \
   --analyze-history \
   --identify-risks \
   --suggest-preventive
@@ -433,7 +433,7 @@ npx ruv-swarm actions predict \
 
 ```bash
 # Get workflow recommendations
-npx ruv-swarm actions recommend \
+npx monomind actions recommend \
   --analyze-repo \
   --suggest-workflows \
   --industry-best-practices
@@ -443,7 +443,7 @@ npx ruv-swarm actions recommend \
 
 ```bash
 # Continuously optimize workflows
-npx ruv-swarm actions auto-optimize \
+npx monomind actions auto-optimize \
   --monitor-performance \
   --apply-improvements \
   --track-savings
@@ -456,7 +456,7 @@ npx ruv-swarm actions auto-optimize \
 ```yaml
 - name: Debug Swarm
   run: |
-    npx ruv-swarm actions debug \
+    npx monomind actions debug \
       --verbose \
       --trace-agents \
       --export-logs
@@ -466,7 +466,7 @@ npx ruv-swarm actions auto-optimize \
 
 ```bash
 # Profile workflow performance
-npx ruv-swarm actions profile \
+npx monomind actions profile \
   --workflow "ci.yml" \
   --identify-slow-steps \
   --suggest-optimizations

package/packages/@monomind/cli/.claude/agents/reengineer-squad/git-manager.md

@@ -58,8 +58,8 @@ feat(port): <description> (from <source-module>)
 
 Examples:
 ```
-feat(port): add EventBus with typed subscribers (from ruv-swarm/event-system)
-feat(port): add PluginLoader with lazy resolution (from ruv-swarm/plugins)
+feat(port): add EventBus with typed subscribers (from upstream/event-system)
+feat(port): add PluginLoader with lazy resolution (from upstream/plugins)
 test(port): add EventBus behavioral contract tests
 ```
 

package/packages/@monomind/cli/.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 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.
+**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.
+
+### Command-to-Skill Routing
 
 ```dot
 digraph mastermind_routing {

package/packages/@monomind/cli/.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/packages/@monomind/cli/.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/packages/@monomind/cli/.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/packages/@monomind/cli/.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) |