@monoes/monomindcli 2.9.3 → 2.9.4

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`