@monoes/monomindcli 2.9.6 → 2.9.8

package/.claude/skills/specialagent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: specialagent
-description: Find the single best specialized agent from the full 160+ agent roster using two-stage LLM domain→agent selection
+description: Find the single best specialized agent from the verified ~98-agent roster using two-stage LLM domain→agent selection
 version: 2.0.0
 triggers:
   - /specialagent
@@ -33,157 +33,55 @@ Stage 2: Give LLM agent names in that domain → LLM picks best agent
 
 ## Stage 1: Domain Selection
 
-The available domains and their agent counts are:
+The verified roster is ~98 agent definitions (97 registered in `packages/@monomind/cli/.monomind/registry.json`). Domains and representative agents from each:
 
-| Domain | Count |
+| Domain | Representative agents (NOT exhaustive — run `ls .claude/agents/` for the full set) |
 |---|---|
-| development | 20 |
-| testing | 10 |
-| security | 6 |
-| devops | 5 |
-| data-ai | 5 |
-| architecture | 6 |
-| research | 5 |
-| marketing | 27 |
-| sales | 8 |
-| paid-media | 7 |
-| design | 8 |
-| product | 5 |
-| project-management | 6 |
-| specialized | 26 |
-| academic | 5 |
-| support | 6 |
+| development | coder · Backend Architect · Frontend Developer · mobile-dev · Mobile App Builder · Rapid Prototyper · Software Architect · Senior Developer · AI Engineer · Data Engineer · Database Optimizer · AI Data Remediation Engineer · LSP/Index Engineer · Embedded Firmware Engineer · Solidity Smart Contract Engineer · WeChat Mini Program Developer · Feishu Integration Developer · Model QA Specialist |
+| testing | tester · tdd-london-swarm · production-validator · API Tester · Accessibility Auditor · Evidence Collector · Performance Benchmarker · Test Results Analyzer · Tool Evaluator · Workflow Optimizer · Code Reviewer |
+| security | Security Engineer · Compliance Auditor · Blockchain Security Auditor · Threat Detection Engineer · Agentic Identity & Trust Architect · Identity Graph Operator · ZK Steward |
+| devops | DevOps Automator · SRE (Site Reliability Engineer) · Git Workflow Master · Incident Response Commander |
+| architecture | system-architect · Software Architect · Backend Architect · Workflow Architect · Autonomous Optimization Architect · Automation Governance Architect · v1-integration-architect |
+| research | researcher · Technical Writer · Developer Advocate · goal-planner |
+| marketing | Competitive Content Strategist · CRO Specialist · Email Marketing Specialist · Launch Strategist · Pricing Strategist |
+| design | Monodesign · Cultural Intelligence Strategist |
+| github | pr-manager · issue-tracker · release-manager · repo-architect · code-review-swarm · multi-repo-swarm · sync-coordinator · workflow-automation · project-board-sync |
+| swarm / consensus | mesh-coordinator · collective-intelligence-coordinator · scout-explorer · swarm-memory-manager · worker-specialist · coordinator · planner · smart-agent · swarm-init · crdt-synchronizer · quorum-manager |
+| optimization | Benchmark Suite · Load Balancing Coordinator · Performance Monitor · Resource Allocator · Topology Optimizer |
+| specialized | MCP Builder · Document Generator · Agents Orchestrator · dashboard-verifier |
+
+**The filesystem is authoritative** — run `ls .claude/agents/` (and `ls packages/@monomind/cli/.claude/agents/`) for the current full list; agents are added over time. Only recommend agents that actually exist there.
 
 **Stage 1 prompt to yourself:**
-> "Given the task: `<task>` — which single domain from this list best fits: development, testing, security, devops, data-ai, architecture, research, marketing, sales, paid-media, design, product, project-management, specialized, academic, support? Answer with just the domain name."
+> "Given the task: `<task>` — which single domain from this list best fits: development, testing, security, devops, architecture, research, marketing, design, github, swarm, optimization, specialized? Answer with just the domain name."
 
 ## Stage 2: Agent Selection Per Domain
 
-Once the domain is selected, use only the agent names for that domain:
-
-### development
-coder, backend-dev, Frontend Developer, mobile-dev, ml-developer, Rapid Prototyper, base-template-generator, LSP/Index Engineer, macOS Spatial/Metal Engineer, Terminal Integration Specialist, Embedded Firmware Engineer, Solidity Smart Contract Engineer, WeChat Mini Program Developer, Feishu Integration Developer, Roblox Systems Scripter, Godot Gameplay Scripter, Unity Architect, Unreal Systems Engineer, visionOS Spatial Engineer
-
-### testing
-tdd-london-swarm, API Tester, production-validator, Evidence Collector, agent-browser-testing, Accessibility Auditor, Reality Checker, Code Reviewer, code-analyzer, feature-dev:code-reviewer
-
-### security
-Security Engineer, Compliance Auditor, Blockchain Security Auditor, v1-security-architect, Threat Detection Engineer, Agentic Identity & Trust Architect
-
-### devops
-DevOps Automator, SRE, cicd-engineer, Incident Response Commander, Git Workflow Master
-
-### data-ai
-Data Engineer, AI Engineer, Database Optimizer, AI Data Remediation Engineer, Model QA Specialist
-
-### architecture
-system-architect, Software Architect, Backend Architect, Plan, UX Architect, Workflow Architect
-
-### research
-Explore, Trend Researcher, Technical Writer, api-docs
-
-### marketing
-AI Citation Strategist, App Store Optimizer, Baidu SEO Specialist, Bilibili Content Strategist, Carousel Growth Engine, China E-Commerce Operator, Content Creator, Cross-Border E-Commerce Specialist, Developer Advocate, Douyin Strategist, Growth Hacker, Healthcare Marketing Compliance Specialist, Instagram Curator, Kuaishou Strategist, LinkedIn Content Creator, Podcast Strategist, Reddit Community Builder, SEO Specialist, Short-Video Editing Coach, Social Media Strategist, TikTok Strategist, Twitter Engager, WeChat Official Account Manager, Weibo Strategist, Xiaohongshu Specialist, Zhihu Strategist, Livestream Commerce Coach
-
-### sales
-Account Strategist, Sales Coach, Deal Strategist, Discovery Coach, Outbound Strategist, Pipeline Analyst, Sales Engineer, Proposal Strategist
-
-### paid-media
-Paid Media Auditor, Ad Creative Strategist, Paid Social Strategist, PPC Campaign Strategist, Programmatic & Display Buyer, Search Query Analyst, Tracking & Measurement Specialist
-
-### design
-Brand Guardian, Image Prompt Engineer, Inclusive Visuals Specialist, Cultural Intelligence Strategist, Behavioral Nudge Engine, Whimsy Injector, UI Designer, Visual Storyteller
-
-### product
-Feedback Synthesizer, Product Manager, Sprint Prioritizer, Experiment Tracker, UX Researcher
-
-### project-management
-Jira Workflow Steward, Project Shepherd, Studio Operations, Studio Producer, Automation Governance Architect, Autonomous Optimization Architect
-
-### specialized
-Accounts Payable Agent, Agents Orchestrator, Analytics Reporter, Book Co-Author, Corporate Training Designer, Document Generator, Executive Summary Generator, Finance Tracker, French Consulting Market Navigator, Government Digital Presales Consultant, Identity Graph Operator, Infrastructure Maintainer, Korean Business Navigator, Legal Compliance Checker, MCP Builder, Narrative Designer, Private Domain Operator, Recruitment Specialist, Report Distribution Agent, Salesforce Architect, Supply Chain Strategist, Support Responder, Tool Evaluator, ZK Steward, agentic-payments, adaptive-coordinator
-
-### academic
-Anthropologist, Geographer, Historian, Narratologist, Psychologist
-
-### support
-Analytics Reporter, Executive Summary Generator, Finance Tracker, Support Responder, Study Abroad Advisor, Trend Researcher
+From the chosen domain's agents (table above), pick the best fit. **Before recommending, verify the name exists** as a `.md` file under `.claude/agents/` (or `packages/@monomind/cli/.claude/agents/`). If the name you want is not on disk, fall back to another agent in the domain or to a core agent (`coder`, `reviewer`, `tester`, `researcher`, `planner`).
 
 **Stage 2 prompt to yourself:**
-> "Given the task: `<task>` — which single agent from this list is the best fit: `<comma-separated agent names for selected domain>`? Answer with just the agent name."
+> "Given the task: `<task>` — which single agent from this domain's list is the best fit: `<comma-separated agent names for the selected domain>`? Answer with just the agent name."
 
 ## Execution Steps
 
 1. Read the user's task
 2. **Stage 1**: Internally reason through the domain list → select one domain
 3. **Stage 2**: Internally reason through agent names in that domain → select one agent
-4. Retrieve that agent's `subagent_type` slug from the mapping below
+4. Verify the agent exists: `ls .claude/agents/**/<slug>.md` (names double as slugs; confirm via the frontmatter `name:` field)
 5. Output the recommendation
 
-## Slug Mapping (agent name → subagent_type)
+## Slug Mapping
 
-Use this to convert the chosen agent name to a callable slug:
+Agent names double as their `subagent_type` slug — the slug is the agent's frontmatter `name` (or the filename without `.md`). Resolve a name to its slug from the definition on disk:
 
+```bash
+# list every available agent definition
+ls .claude/agents/ packages/@monomind/cli/.claude/agents/
+# read a specific agent's registered name
+grep -m1 "^name:" .claude/agents/**/<file>.md
 ```
-coder → coder
-backend-dev → backend-dev
-Frontend Developer → Frontend Developer
-mobile-dev → mobile-dev
-ml-developer → ml-developer
-Rapid Prototyper → Rapid Prototyper
-LSP/Index Engineer → LSP/Index Engineer
-macOS Spatial/Metal Engineer → macOS Spatial/Metal Engineer
-Agentic Identity & Trust Architect → Agentic Identity & Trust Architect
-tdd-london-swarm → tdd-london-swarm
-API Tester → API Tester
-production-validator → production-validator
-Evidence Collector → Evidence Collector
-agent-browser-testing → agent-browser-testing
-Accessibility Auditor → Accessibility Auditor
-Reality Checker → Reality Checker
-Security Engineer → Security Engineer
-Compliance Auditor → Compliance Auditor
-Blockchain Security Auditor → Blockchain Security Auditor
-DevOps Automator → DevOps Automator
-SRE → SRE
-cicd-engineer → cicd-engineer
-Incident Response Commander → Incident Response Commander
-Git Workflow Master → Git Workflow Master
-Data Engineer → Data Engineer
-AI Engineer → AI Engineer
-Database Optimizer → Database Optimizer
-system-architect → system-architect
-Software Architect → Software Architect
-Backend Architect → Backend Architect
-Plan → Plan
-UX Architect → UX Architect
-Explore → Explore
-Trend Researcher → Trend Researcher
-Technical Writer → Technical Writer
-api-docs → api-docs
-Code Reviewer → Code Reviewer
-code-analyzer → code-analyzer
-feature-dev:code-reviewer → feature-dev:code-reviewer
-TikTok Strategist → TikTok Strategist
-SEO Specialist → SEO Specialist
-Content Creator → Content Creator
-LinkedIn Content Creator → LinkedIn Content Creator
-Growth Hacker → Growth Hacker
-Product Manager → Product Manager
-Project Shepherd → Project Shepherd
-Sales Coach → Sales Coach
-Deal Strategist → Deal Strategist
-Legal Compliance Checker → Legal Compliance Checker
-Finance Tracker → Finance Tracker
-Support Responder → Support Responder
-Analytics Reporter → Analytics Reporter
-Brand Guardian → Brand Guardian
-UI Designer → UI Designer
-Anthropologist → Anthropologist
-Historian → Historian
-Psychologist → Psychologist
-```
-(For any agent not listed, use the agent name directly as the slug.)
+
+If unsure, pass the agent name as the slug. The authoritative set is whatever currently exists in those directories (~98 definitions).
 
 ## Output Format
 
@@ -202,5 +100,5 @@ Then ask: "Should I spawn this agent now?"
 
 1. Only pass names at each stage — no descriptions, no keyword dumps, no scoring tables
 2. Pick exactly one domain, then exactly one agent
-3. For dev tasks that clearly need a specialized tool (e.g. CI/CD → cicd-engineer, not DevOps Automator), prefer the more specific agent
+3. For tasks that clearly need a specialized tool (e.g. accessibility audits → Accessibility Auditor, not tester), prefer the more specific agent
 4. Never recommend a generic role (coder, tester) when a specialized agent in the right domain exists

package/.claude/skills/swarm-advanced/SKILL.md

@@ -13,10 +13,10 @@ Master advanced swarm patterns for distributed research, development, and testin
 ### Prerequisites
 ```bash
 # Ensure Monomind is installed
-npm install -g monomind@alpha
+npm install -g monomind@latest
 
 # Add MCP server (if using MCP tools)
-claude mcp add monomind npx monomind@alpha mcp start
+claude mcp add monomind npx monomind@latest mcp start
 ```
 
 ### Basic Pattern

package/.claude/skills/swarm-orchestration/SKILL.md

@@ -1,179 +1,249 @@
 ---
 name: swarm-orchestration
-description: "Orchestrate multi-agent swarms with monomind for parallel task execution, dynamic topology, and intelligent coordination. Use when scaling beyond single agents, implementing complex workflows, or building distributed AI systems."
+description: Orchestrate in-process multi-agent swarms with monomind for parallel task execution, topology selection, and shared memory coordination. Use when scaling beyond a single agent on tasks with clear decomposition.
 ---
 
 # Swarm Orchestration
 
 ## What This Skill Does
 
-Orchestrates multi-agent swarms using monomind's advanced coordination system. Supports mesh, hierarchical, and adaptive topologies with automatic task distribution, load balancing, and fault tolerance.
+Coordinates multiple Claude Code Task-tool agents inside a single monomind process. The swarm layer tracks topology, agent lifecycle, and task assignment. **Real work happens in spawned Task-tool agents** — the swarm coordinates, agents execute.
+
+## What Swarm Is (and Is Not)
+
+**Is:** In-process coordination — topology bookkeeping, agent lifecycle, task routing, vote-count consensus. State persists to `.monomind/swarm/`.
+
+**Is not:** A distributed system. There is no networking between separate machines. "Consensus" strategies (`raft`, `bft`, `quorum`) are vote-count thresholds applied inside one process — not Raft/Paxos protocols.
+
+If you need persistent, scheduled, autonomous agent organizations, use `monomind org run` instead. **Swarm coordinates a single task; org runtime governs a long-running org.** (See "Successor: Org Runtime" below.)
 
 ## Prerequisites
 
-- monomind v1.8.0+
-- Node.js 18+
-- Understanding of distributed systems (helpful)
+- monomind v2.9.4+
+- Claude Code's Task tool available (agents execute via Task tool, not CLI alone)
+- A task that decomposes into 2+ independent subtasks
+
+## Topology Selection
+
+Choose topology by task shape:
+
+| Topology | When | Example |
+|---|---|---|
+| `hierarchical` | Default — clear task decomposition, one coordinator | Feature build (architect → coders → testers) |
+| `mesh` | Peer-to-peer exploration, research, knowledge sharing | Multi-source research synthesis |
+| `hierarchical-mesh` | 10+ agents — hierarchy with peer side-channels | Large refactor touching many modules |
+| `ring` | Circular handoff (review → fix → re-review) | Code review cycle |
+| `star` | Central hub with specialist spokes | Coordinator dispatching to niche experts |
+| `hybrid` | Mixed work needing both hierarchy and peer comms | Migration + new feature in parallel |
+
+**Rule of thumb:** ≤8 agents → `hierarchical`. 10+ agents → `hierarchical-mesh`. Research/exploration → `mesh`.
+
+## Strategy Selection
+
+| Strategy | When |
+|---|---|
+| `specialized` | Fixed roles (default for feature work) |
+| `balanced` | Even work distribution, homogeneous tasks |
+| `development` | Dev pipeline (plan → code → test → review) |
+
+## Lifecycle
 
-## Quick Start
+### 1. Initialize
 
 ```bash
-# Initialize swarm
-npx monomind swarm init --topology mesh --max-agents 5
-
-# Spawn agents
-npx monomind agent spawn --type coder
-npx monomind agent spawn --type tester
-npx monomind agent spawn --type reviewer
-
-# Orchestrate task
-npx monomind task run \
-  --task "Build REST API with tests" \
-  --mode parallel
-```
-
-## Topology Patterns
-
-### 1. Mesh (Peer-to-Peer)
-```typescript
-// Equal peers, distributed decision-making
-await swarm.init({
-  topology: 'mesh',
-  agents: ['coder', 'tester', 'reviewer'],
-  communication: 'broadcast'
-});
-```
-
-### 2. Hierarchical (Queen-Worker)
-```typescript
-// Centralized coordination, specialized workers
-await swarm.init({
-  topology: 'hierarchical',
-  queen: 'architect',
-  workers: ['backend-dev', 'frontend-dev', 'db-designer']
-});
-```
-
-### 3. Adaptive (Dynamic)
-```typescript
-// Automatically switches topology based on task
-await swarm.init({
-  topology: 'adaptive',
-  optimization: 'task-complexity'
-});
-```
-
-## Task Orchestration
-
-### Parallel Execution
-```typescript
-// Execute tasks concurrently
-const results = await swarm.execute({
-  tasks: [
-    { agent: 'coder', task: 'Implement API endpoints' },
-    { agent: 'frontend', task: 'Build UI components' },
-    { agent: 'tester', task: 'Write test suite' }
-  ],
-  mode: 'parallel',
-  timeout: 300000 // 5 minutes
-});
-```
-
-### Pipeline Execution
-```typescript
-// Sequential pipeline with dependencies
-await swarm.pipeline([
-  { stage: 'design', agent: 'architect' },
-  { stage: 'implement', agent: 'coder', after: 'design' },
-  { stage: 'test', agent: 'tester', after: 'implement' },
-  { stage: 'review', agent: 'reviewer', after: 'test' }
-]);
-```
-
-### Adaptive Execution
-```typescript
-// Let swarm decide execution strategy
-await swarm.autoOrchestrate({
-  goal: 'Build production-ready API',
-  constraints: {
-    maxTime: 3600,
-    maxAgents: 8,
-    quality: 'high'
-  }
-});
-```
-
-## Memory Coordination
-
-```typescript
-// Share state across swarm
-await swarm.memory.store('api-schema', {
-  endpoints: [...],
-  models: [...]
-});
-
-// Agents read shared memory
-const schema = await swarm.memory.retrieve('api-schema');
-```
-
-## Advanced Features
-
-### Load Balancing
-```typescript
-// Automatic work distribution
-await swarm.enableLoadBalancing({
-  strategy: 'dynamic',
-  metrics: ['cpu', 'memory', 'task-queue']
-});
-```
-
-### Fault Tolerance
-```typescript
-// Handle agent failures
-await swarm.setResiliency({
-  retry: { maxAttempts: 3, backoff: 'exponential' },
-  fallback: 'reassign-task'
-});
-```
-
-### Performance Monitoring
-```typescript
-// Track swarm metrics
-const metrics = await swarm.getMetrics();
-// { throughput, latency, success_rate, agent_utilization }
-```
+npx monomind@latest swarm init \
+  --topology hierarchical \
+  --max-agents 8 \
+  --strategy specialized
+```
+
+### 2. Spawn agents (CLI or MCP)
+
+```bash
+npx monomind@latest agent spawn -t coordinator --name lead
+npx monomind@latest agent spawn -t coder       --name impl
+npx monomind@latest agent spawn -t tester      --name qa
+```
 
-## Integration with Hooks
+Equivalent MCP: `mcp__monomind__agent_spawn { type: "...", name: "..." }`.
+
+### 3. Start work
 
 ```bash
-# Pre-task coordination
-npx monomind hooks pre-task --description "Build API"
+npx monomind@latest swarm start \
+  --objective "Add OAuth2 login with tests" \
+  --strategy specialized \
+  --agents 4
+```
 
-# Post-task synchronization
-npx monomind hooks post-task --task-id "task-123"
+### 4. Monitor and stop
 
-# Session restore
-npx monomind hooks session-restore --session-id "swarm-001"
+```bash
+npx monomind@latest swarm status
+npx monomind@latest agent list
+npx monomind@latest agent status <id>
+npx monomind@latest swarm stop
 ```
 
+## Agent Role Assignment
+
+Match agent type to task category. Use `mcp__monomind__hooks_route` to auto-pick instead of guessing:
+
+```
+mcp__monomind__hooks_route { task: "implement JWT auth" }
+# → returns the recommended agent type
+```
+
+Common assignments (see `doc/concepts/swarm.md` for the full routing table):
+
+| Task | Recommended agents |
+|---|---|
+| Bug fix | coordinator, researcher, coder, tester |
+| Feature | coordinator, architect, coder, tester, reviewer |
+| Refactor | coordinator, architect, coder, reviewer |
+| Performance | coordinator, performance-engineer, coder |
+| Security | coordinator, security-architect, security-auditor |
+| Docs | researcher, documenter |
+
+## Workflow Patterns
+
+### Sequential pipeline (design → code → test → review)
+
+```bash
+npx monomind@latest swarm init --topology hierarchical --strategy development --max-agents 4
+npx monomind@latest swarm start --objective "Build user-profile API with full test coverage"
+```
+
+Drive each stage via task assignment — the next stage picks up when the previous completes:
+
+```
+mcp__monomind__task_create { description: "Design schema", agent_type: "architect" }
+# after architect completes:
+mcp__monomind__task_assign { task_id: "...", agent_id: "<coder-id>" }
+# after coder completes:
+mcp__monomind__task_assign { task_id: "...", agent_id: "<tester-id>" }
+```
+
+### Parallel fan-out (independent subtasks)
+
+```bash
+npx monomind@latest swarm init --topology mesh --strategy balanced --max-agents 6
+npx monomind@latest swarm start --objective "Audit 6 modules for security issues" --agents 6
+```
+
+Spawn one Task-tool agent per module; each writes findings to the shared namespace.
+
+### Mixed (parallel sub-trees, sequential stages)
+
+Use `hierarchical-mesh` — the coordinator fans out parallel work while stages run sequentially. Best for 10+ agent workloads:
+
+```
+mcp__monomind__swarm_init { topology: "hierarchical-mesh", max_agents: 12, strategy: "specialized" }
+```
+
+## Memory Sharing Across Agents
+
+Swarm agents share state through monomind memory (SQLite/JSON) — there is no separate "swarm memory" API. Each agent reads/writes the same namespace.
+
+Store context once (CLI), or via MCP inside an agent:
+
+```bash
+npx monomind@latest memory store \
+  --key "feature-spec" \
+  --value "OAuth2 with PKCE, refresh tokens, 15-min access TTL" \
+  --namespace swarm-001 --tags spec,auth
+```
+
+```
+mcp__monomind__memory_kg_ingest { key: "feature-spec", value: "...", namespace: "swarm-001" }
+```
+
+Retrieve during work:
+
+```bash
+npx monomind@latest memory retrieve --key feature-spec --namespace swarm-001
+npx monomind@latest memory search --query "auth requirements"
+```
+
+**Use one shared namespace per swarm run** so every agent sees the same context.
+
+## Load Balancing (Concept)
+
+In-process "load balancing" is task routing, not network LB. Two mechanisms: `hooks_route` (picks the optimal agent type from the routing table) and `strategy` (`balanced` evens work, `specialized` keeps roles fixed).
+
+For uneven workloads, scale up and reassign stalled tasks:
+
+```bash
+npx monomind@latest swarm scale --agents 12
+npx monomind@latest swarm status
+npx monomind@latest agent status <id>
+```
+
+```
+mcp__monomind__task_assign { task_id: "...", agent_id: "<idle-agent-id>" }
+```
+
+## Full Example: Feature Build
+
+```bash
+npx monomind@latest swarm init --topology hierarchical --max-agents 5 --strategy specialized
+
+# Share the spec once — all agents read this
+npx monomind@latest memory store \
+  --key "feature-spec" \
+  --value "Add CSV import: parse, validate, persist, report errors" \
+  --namespace swarm-csv
+
+npx monomind@latest agent spawn -t coordinator --name lead
+npx monomind@latest agent spawn -t coder       --name impl
+npx monomind@latest agent spawn -t tester      --name qa
+npx monomind@latest agent spawn -t reviewer    --name audit
+
+npx monomind@latest swarm start --objective "Implement CSV import end-to-end" --agents 4
+npx monomind@latest swarm status
+npx monomind@latest swarm stop
+```
+
+Execution happens in Claude Code Task-tool agents. The CLI coordinates; Task agents do the work.
+
+## Successor: Org Runtime
+
+For autonomous, recurring, or long-running work, prefer `monomind org run`:
+
+```bash
+npx monomind@latest org run my-team --task "Maintain CI hygiene"
+npx monomind@latest org status
+npx monomind@latest org logs my-team --follow
+npx monomind@latest org stop my-team
+```
+
+Org runtime adds: scheduled wakeups, governance gates, budget enforcement, persistent state across runs. **Swarm is a single coordinated session; org runtime is a durable organization.**
+
+- Use **swarm** for: one-off parallel tasks today.
+- Use **org runtime** for: recurring autonomous work, scheduled agents, multi-session goals.
+
 ## Best Practices
 
-1. **Start small**: Begin with 2-3 agents, scale up
-2. **Use memory**: Share context through swarm memory
-3. **Monitor metrics**: Track performance and bottlenecks
-4. **Enable hooks**: Automatic coordination and sync
-5. **Set timeouts**: Prevent hung tasks
+1. **Right-size the swarm.** Start with 3–4 agents; scale only when utilization is high.
+2. **One shared memory namespace per run.** All agents read/write the same context.
+3. **Pick topology by agent count.** ≤8 → `hierarchical`; 10+ → `hierarchical-mesh`.
+4. **Route before assigning.** `hooks_route` picks better agent types than guessing.
+5. **Let Task-tool agents do the work.** CLI coordinates; execution lives in Claude Code Task agents.
+6. **Set clear boundaries.** Every subtask needs clear inputs and outputs, or agents will thrash.
 
 ## Troubleshooting
 
-### Issue: Agents not coordinating
-**Solution**: Verify memory access and enable hooks
-
-### Issue: Poor performance
-**Solution**: Check topology (use adaptive) and enable load balancing
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Agents not coordinating | Different namespace per agent | Use one shared `--namespace` |
+| Stalled agent | Blocked on upstream stage | `agent status <id>`, then reassign task |
+| Poor throughput | Wrong topology for count | Switch to `hierarchical-mesh` at 10+ agents |
+| Duplicate work | No shared memory | `memory store` the spec; agents `retrieve` before acting |
+| Swarm won't start | Bad topology/strategy combo | Verify flags against `doc/concepts/swarm.md` |
 
 ## Learn More
 
-- Swarm Guide: docs/swarm/orchestration.md
-- Topology Patterns: docs/swarm/topologies.md
-- Hooks Integration: docs/hooks/coordination.md
+- `doc/concepts/swarm.md` — honest scope, topologies, agent types, full MCP tool list
+- Hive-mind (MCP only): `mcp__monomind__hive-mind_*` tools for vote-count consensus
+- `/mastermind:topology` — interactive topology picker
+- Org runtime: `npx monomind@latest org --help`