monomind 1.8.0 → 1.9.0

package/.claude/commands/workflows/research.md

@@ -1,63 +1,89 @@
+---
+name: workflows:research
+description: Research workflow coordination pattern — mesh swarm for comprehensive exploration using real MCP tools and npx monomind workflow run -t research
+---
+
 # Research Workflow Coordination
 
-## Purpose
-Coordinate Claude Code's research activities for comprehensive, systematic exploration.
+Coordinate multi-agent research activities for comprehensive, systematic exploration.
 
-## Step-by-Step Coordination
+## How to Invoke
 
-### 1. Initialize Research Framework
 ```
-Tool: mcp__monomind__swarm_init
-Parameters: {"topology": "mesh", "maxAgents": 5, "strategy": "balanced"}
+Skill("workflows:research")
 ```
-Creates a mesh topology for comprehensive exploration from multiple angles.
 
-### 2. Define Research Perspectives
-```
-Tool: mcp__monomind__agent_spawn
-Parameters: {"type": "researcher", "name": "Literature Review"}
-```
-```
-Tool: mcp__monomind__agent_spawn  
-Parameters: {"type": "analyst", "name": "Data Analysis"}
-```
-Sets up different analytical approaches for Claude Code to use.
+---
 
-### 3. Execute Coordinated Research
-```
-Tool: mcp__monomind__task_orchestrate
-Parameters: {
-  "task": "Research modern web frameworks performance",
-  "strategy": "adaptive",
-  "priority": "medium"
-}
-```
+## Quick Start
+
+```bash
+# Run the built-in research workflow
+npx monomind workflow run -t research --task "Analyze modern web framework performance"
 
-### 4. Store Research Findings
+# Preview stages without executing
+npx monomind workflow run -t research --dry-run
+
+# Show template details
+npx monomind workflow template show research
 ```
-Tool: mcp__monomind__memory_usage
-Parameters: {
-  "action": "store",
-  "key": "research_findings",
-  "value": "framework performance analysis results",
-  "namespace": "research"
-}
+
+## Stages
+
+The `research` template runs these stages:
+1. **Discovery** — Identify sources, gather raw information
+2. **Analysis** — Evaluate and compare findings
+3. **Synthesis** — Combine into coherent conclusions
+4. **Documentation** — Write up findings
+
+Agents: `researcher`, `analyst` (mesh topology for broad coverage)
+
+## MCP Coordination
+
+For custom research coordination via MCP:
+
+```javascript
+// Initialize mesh swarm for broad exploration
+mcp__monomind__swarm_init({
+  topology: "mesh",
+  maxAgents: 5,
+  strategy: "balanced"
+})
+
+// Run the research workflow
+mcp__monomind__workflow_run({
+  template: "research",
+  task: "Research modern web frameworks performance",
+  options: { parallel: true, maxAgents: 4 }
+})
+
+// Store research findings in memory
+mcp__monomind__memory_store({
+  key: "research-web-frameworks-2026",
+  value: "React/Next.js leads for SSR; Astro for static; Svelte for performance",
+  namespace: "research"
+})
+
+// Search past research before starting
+mcp__monomind__memory_search({
+  query: "web framework performance analysis",
+  namespace: "research",
+  limit: 5
+})
 ```
 
 ## What Claude Code Actually Does
-1. Uses **WebSearch** tool for finding resources
-2. Uses **Read** tool for analyzing documentation
-3. Uses **Task** tool for parallel exploration
-4. Synthesizes findings using coordination patterns
-5. Stores insights in memory for future reference
 
-Remember: The swarm coordinates HOW Claude Code researches, not WHAT it finds.
+1. **WebSearch** tool — finds relevant resources
+2. **Read** tool — analyzes documentation and code
+3. **Task** tool — spawns parallel research agents for different angles
+4. Synthesizes findings in the conversation
+5. Stores insights in memory for future sessions
 
-## CLI Usage
-```bash
-# Start research workflow via CLI
-npx monomind workflow research "modern web frameworks"
+The workflow template coordinates the research strategy; Claude Code does the actual searching and reading.
+
+## Related Skills
 
-# Export research workflow
-npx monomind workflow export research --format json
-```
+- `workflows:workflow-execute` — Full workflow run reference
+- `swarm:research` — Direct swarm-based research coordination
+- `memory:memory-search` — Search past research findings

package/.claude/commands/workflows/workflow-create.md

@@ -1,25 +1,84 @@
-# workflow-create
+---
+name: workflows:workflow-create
+description: Create and save custom workflow templates using npx monomind workflow template create — save successful workflows for reuse
+---
 
-Create reusable workflow templates.
+# Workflow Create
+
+Create and save custom workflow templates for reuse.
+
+## How to Invoke
 
-## Usage
-```bash
-npx monomind workflow create [options]
 ```
+Skill("workflows:workflow-create")
+```
+
+---
 
-## Options
-- `--name <name>` - Workflow name
-- `--from-history` - Create from history
-- `--interactive` - Interactive creation
+## CLI Reference
 
-## Examples
 ```bash
-# Create workflow
-npx monomind workflow create --name "deploy-api"
+# Create a template from a workflow ID
+npx monomind workflow template create --name "my-api-workflow" --workflow wf-abc123
 
-# From history
-npx monomind workflow create --name "test-suite" --from-history
+# Create a template from a workflow file
+npx monomind workflow template create --name "deploy-workflow" --file ./workflow.yaml
 
-# Interactive mode
-npx monomind workflow create --interactive
+# List existing templates
+npx monomind workflow template list
+
+# Show a specific template's stages and agents
+npx monomind workflow template show development
+npx monomind workflow template show sparc
 ```
+
+## Template Create Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--name` | `-n` | Template name (required) |
+| `--workflow` | `-w` | Workflow ID to save as template |
+| `--file` | `-f` | Workflow file to save as template |
+
+## MCP Tools
+
+```javascript
+// Create a workflow definition
+mcp__monomind__workflow_create({
+  name: "my-workflow",
+  template: "development",
+  task: "Build auth system"
+})
+
+// List available templates
+mcp__monomind__workflow_template({})
+
+// Execute workflow from template
+mcp__monomind__workflow_run({
+  template: "my-workflow",
+  task: "Build feature X"
+})
+```
+
+## Workflow
+
+1. Run a workflow that works well:
+   ```bash
+   npx monomind workflow run -t development --task "Build auth"
+   # Note the workflowId in the output
+   ```
+
+2. Save it as a reusable template:
+   ```bash
+   npx monomind workflow template create --name "auth-workflow" --workflow <workflowId>
+   ```
+
+3. Reuse it:
+   ```bash
+   npx monomind workflow run -t auth-workflow --task "New auth task"
+   ```
+
+## Related Skills
+
+- `workflows:workflow-execute` — Run workflows from templates
+- `workflows:workflow-export` — Browse and manage templates

package/.claude/commands/workflows/workflow-execute.md

@@ -1,25 +1,103 @@
-# workflow-execute
+---
+name: workflows:workflow-execute
+description: Run multi-agent workflows using built-in templates (development, research, testing, sparc, security-audit, etc.) via real npx monomind workflow run CLI
+---
 
-Execute saved workflows.
+# Workflow Execute
+
+Run multi-agent workflows using built-in templates or custom workflow files.
+
+## How to Invoke
 
-## Usage
-```bash
-npx monomind workflow execute [options]
 ```
+Skill("workflows:workflow-execute")
+```
+
+---
 
-## Options
-- `--name <name>` - Workflow name
-- `--params <json>` - Workflow parameters
-- `--dry-run` - Preview execution
+## CLI Reference
 
-## Examples
 ```bash
-# Execute workflow
-npx monomind workflow execute --name "deploy-api"
+# Run a built-in template
+npx monomind workflow run -t development --task "Build REST API with auth"
+npx monomind workflow run -t research --task "Analyze performance bottlenecks"
+npx monomind workflow run -t testing
+npx monomind workflow run -t security-audit
+npx monomind workflow run -t sparc --task "New payment module"
 
-# With parameters
-npx monomind workflow execute --name "test-suite" --params '{"env": "staging"}'
+# Run from a workflow file
+npx monomind workflow run -f ./workflow.yaml
+npx monomind workflow run -f ./workflow.json
 
-# Dry run
-npx monomind workflow execute --name "deploy-api" --dry-run
+# Validate without executing
+npx monomind workflow run -t development --dry-run
 ```
+
+## All Flags
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--template` | `-t` | — | Built-in template name |
+| `--file` | `-f` | — | Workflow definition file (YAML/JSON) |
+| `--task` | — | — | Task description passed to the workflow |
+| `--parallel` | `-p` | `true` | Enable parallel agent execution |
+| `--max-agents` | `-m` | `5` | Maximum agents to spawn |
+| `--timeout` | — | `30` | Timeout in minutes |
+| `--dry-run` | `-d` | `false` | Validate without executing |
+
+## Built-in Templates
+
+| Template | Stages | Agent Types |
+|----------|--------|-------------|
+| `development` | Planning → Implementation → Testing → Review → Integration | coder, tester, reviewer |
+| `research` | Discovery → Analysis → Synthesis → Documentation | researcher, analyst |
+| `testing` | Unit → Integration → E2E → Performance | tester, coder |
+| `security-audit` | Threat Model → Static → Dynamic → Report | security-architect, auditor |
+| `code-review` | Initial → Security → Quality → Feedback | reviewer, auditor, analyst |
+| `refactoring` | Analysis → Planning → Refactor → Validation | architect, coder, reviewer |
+| `sparc` | Spec → Pseudocode → Architecture → Refinement → Completion | architect, coder, tester, reviewer |
+| `custom` | Define your own | configurable |
+
+## MCP Tools
+
+```javascript
+// Run a workflow
+mcp__monomind__workflow_run({
+  template: "development",
+  task: "Build REST API with auth",
+  options: {
+    parallel: true,
+    maxAgents: 6,
+    timeout: 30,
+    dryRun: false
+  }
+})
+
+// Check workflow status after launch
+mcp__monomind__workflow_status({ workflowId: "wf-123" })
+
+// List all workflows
+mcp__monomind__workflow_list({ status: "running", limit: 10 })
+
+// Stop a running workflow
+mcp__monomind__workflow_cancel({ workflowId: "wf-123" })
+```
+
+## After Launch
+
+Track progress:
+
+```bash
+# Check status by ID (shown after run)
+npx monomind workflow status <workflowId>
+
+# List all running workflows
+npx monomind workflow list --status running
+```
+
+## Related Skills
+
+- `workflows:workflow-create` — Save a custom workflow template
+- `workflows:development` — Development workflow coordination pattern
+- `workflows:research` — Research workflow coordination pattern
+- `swarm:swarm` — Direct swarm init for custom coordination

package/.claude/commands/workflows/workflow-export.md

@@ -1,25 +1,90 @@
-# workflow-export
+---
+name: workflows:workflow-export
+description: Browse, inspect, and manage workflow templates — list built-in templates, show template details and stages, validate workflow files
+---
 
-Export workflows for sharing.
+# Workflow Templates
+
+Browse and manage workflow templates — inspect built-in templates and validate custom workflow files.
+
+## How to Invoke
 
-## Usage
-```bash
-npx monomind workflow export [options]
 ```
+Skill("workflows:workflow-export")
+```
+
+---
 
-## Options
-- `--name <name>` - Workflow to export
-- `--format <type>` - Export format
-- `--include-history` - Include execution history
+## CLI Reference
 
-## Examples
 ```bash
-# Export workflow
-npx monomind workflow export --name "deploy-api"
+# List all available templates
+npx monomind workflow template list
+
+# Show details for a specific template (stages, agents, estimated duration)
+npx monomind workflow template show development
+npx monomind workflow template show sparc
+npx monomind workflow template show security-audit
 
-# As YAML
-npx monomind workflow export --name "test-suite" --format yaml
+# Validate a custom workflow file
+npx monomind workflow validate -f ./workflow.yaml
+npx monomind workflow validate -f ./workflow.json --strict
 
-# With history
-npx monomind workflow export --name "deploy-api" --include-history
+# List past workflow runs
+npx monomind workflow list --status completed --limit 20
+npx monomind workflow list --status all
 ```
+
+## Built-in Templates Reference
+
+| Template | Stages | Estimated Duration |
+|----------|--------|--------------------|
+| `development` | Planning → Implementation → Testing → Review → Integration | 15-30 min |
+| `research` | Discovery → Analysis → Synthesis → Documentation | 10-20 min |
+| `testing` | Unit → Integration → E2E → Performance | 5-15 min |
+| `security-audit` | Threat Model → Static → Dynamic → Report | 20-40 min |
+| `code-review` | Initial → Security → Quality → Feedback | 10-25 min |
+| `refactoring` | Analysis → Planning → Refactor → Validation | 15-35 min |
+| `sparc` | Spec → Pseudocode → Architecture → Refinement → Completion | 25-45 min |
+| `custom` | Define your own stages | varies |
+
+## MCP Tools
+
+```javascript
+// List templates
+mcp__monomind__workflow_template({})
+
+// List past workflow runs
+mcp__monomind__workflow_list({ status: "completed", limit: 20 })
+
+// Get status of a specific run
+mcp__monomind__workflow_status({ workflowId: "wf-123" })
+```
+
+## Workflow File Format
+
+To create a custom workflow file for use with `workflow run -f`:
+
+```yaml
+name: my-workflow
+stages:
+  - name: Planning
+    agents: [architect]
+  - name: Implementation
+    agents: [coder]
+  - name: Testing
+    agents: [tester]
+  - name: Review
+    agents: [reviewer]
+```
+
+Validate before running:
+
+```bash
+npx monomind workflow validate -f ./my-workflow.yaml --strict
+```
+
+## Related Skills
+
+- `workflows:workflow-execute` — Run workflows from templates
+- `workflows:workflow-create` — Save a custom workflow as a template

package/.claude/helpers/control-start.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Monomind Control Start
+ * Ensures the Monomind Neural Control Room (web UI) is running.
+ * Called from SessionStart hook — exits immediately after spawning.
+ *
+ * Status written to: .monomind/control.json
+ * Port: 4242 (default, auto-increments on collision)
+ */
+
+/* eslint-disable @typescript-eslint/no-var-requires */
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const STATUS_FILE = path.join(CWD, '.monomind', 'control.json');
+const DEFAULT_PORT = 4242;
+
+function readStatus() {
+  try {
+    if (fs.existsSync(STATUS_FILE)) {
+      return JSON.parse(fs.readFileSync(STATUS_FILE, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+  return null;
+}
+
+function isPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function writeStatus(pid, port) {
+  try {
+    fs.mkdirSync(path.dirname(STATUS_FILE), { recursive: true });
+    fs.writeFileSync(STATUS_FILE, JSON.stringify({
+      pid,
+      port,
+      url: `http://localhost:${port}`,
+      startedAt: new Date().toISOString(),
+    }), 'utf-8');
+  } catch { /* ignore */ }
+}
+
+function findCliPath() {
+  // Try local monorepo server.mjs first (direct — no CLI subcommand needed)
+  const serverMjs = path.join(CWD, 'packages', '@monomind', 'cli', 'dist', 'src', 'ui', 'server.mjs');
+  if (fs.existsSync(serverMjs)) return { cmd: process.execPath, args: [serverMjs], usePort: true };
+
+  // Try local CLI bin as fallback
+  const local = path.join(CWD, 'packages', '@monomind', 'cli', 'bin', 'cli.js');
+  if (fs.existsSync(local)) return { cmd: process.execPath, args: [local], usePort: false };
+
+  // Try npx monomind as last resort
+  return { cmd: 'npx', args: ['monomind@latest'], usePort: false };
+}
+
+function main() {
+  // If already running, do nothing
+  const status = readStatus();
+  if (status && status.pid && isPidAlive(status.pid)) {
+    process.stdout.write(`[control] already running on port ${status.port} (pid ${status.pid})\n`);
+    process.exit(0);
+  }
+
+  const { cmd, args, usePort } = findCliPath();
+  // server.mjs accepts port as second positional arg; CLI uses 'ui --no-open --port N'
+  const allArgs = usePort
+    ? [...args, String(DEFAULT_PORT)]
+    : [...args, 'ui', '--no-open', '--port', String(DEFAULT_PORT)];
+
+  const child = spawn(cmd, allArgs, {
+    detached: true,
+    stdio: 'ignore',
+    cwd: CWD,
+    env: { ...process.env, CLAUDE_PROJECT_DIR: CWD },
+  });
+
+  child.unref();
+
+  writeStatus(child.pid, DEFAULT_PORT);
+  process.stdout.write(`[control] started Neural Control Room on port ${DEFAULT_PORT} (pid ${child.pid})\n`);
+  process.exit(0);
+}
+
+main();