crewx 0.8.1 → 0.8.2-rc.2

package/README.md

@@ -1,268 +1,268 @@
-# CrewX
-
-> Build your AI agent team — bring any model, orchestrate any workflow
-
-[![npm version](https://img.shields.io/npm/v/crewx)](https://www.npmjs.com/package/crewx)
-[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
-[![License](https://img.shields.io/badge/license-see%20below-blue)](#license)
-
-## What is CrewX?
-
-CrewX is a developer tool for building and managing AI agent teams. Define agents in YAML, wire them into workflows, and let them collaborate using built-in tools — all from a single CLI or web dashboard.
-
-- **Bring Your Own AI** — Claude, Gemini, Copilot, Codex, or any OpenAI-compatible model
-- **One command to start** — `npx crewx` launches everything
-- **Team orchestration** — agents work together through threads, workflows, and shared memory
-
-## Quick Start
-
-```bash
-npx crewx
-```
-
-That's it. This launches the CrewX dashboard at `http://localhost:8150` where you can manage agents, create threads, and monitor workflows.
-
-### Initialize a new project
-
-```bash
-npx crewx init
-```
-
-This creates a `crewx.yaml` in your project with default agents and settings.
-
-### Talk to your agents
-
-```bash
-# Ask a question (query mode)
-npx crewx q "@claude review this codebase"
-
-# Execute a task (agents can edit files)
-npx crewx x "@copilot implement login component"
-
-# Multi-agent collaboration
-npx crewx q "@claude @gemini compare approaches for caching"
-```
-
-## Key Features
-
-### BYOA (Bring Your Own AI)
-
-Use your existing AI subscriptions — or run fully local with Ollama. No vendor lock-in.
-
-| Provider | CLI | Status |
-|----------|-----|--------|
-| Claude | `claude` | Supported |
-| Gemini | `gemini` | Supported |
-| GitHub Copilot | `copilot` | Supported |
-| Codex | `codex` | Supported |
-| Ollama (local LLM) | API provider | Supported |
-| OpenAI-compatible | API provider | Supported |
-
-Build a **fully local AI team** with Ollama — no cloud, no API costs, complete data privacy. Mix and match cloud and local models in the same team.
-
-### Agent Teams
-
-Define your team in `crewx.yaml`:
-
-```yaml
-agents:
-  - id: reviewer
-    name: Code Reviewer
-    provider: cli/claude
-    inline:
-      model: claude-sonnet-4-6
-      prompt: |
-        You are a senior code reviewer.
-        Focus on correctness, performance, and security.
-
-  - id: implementer
-    name: Implementer
-    provider: cli/copilot
-    inline:
-      prompt: |
-        You are a full-stack developer.
-        Write clean, tested code following project conventions.
-```
-
-### Thread Conversations
-
-Thread-based conversations keep context across multiple interactions. Agents remember previous messages and can build on each other's work.
-
-```bash
-# Start a thread
-npx crewx q "@reviewer review PR #42" --thread="pr-42-review"
-
-# Continue the conversation
-npx crewx q "@implementer fix the issues found" --thread="pr-42-review"
-```
-
-### Semantic Workflows
-
-Define agent collaboration as semantic workflow YAML — branching, parallel execution, approval gates, and loops:
-
-```yaml
-# workflows/code-review.yaml
-workflows:
-  code-review:
-    metadata:
-      name: "Code Review Workflow"
-    nodes:
-      review:
-        type: agent_task
-        agent: reviewer
-        mode: query
-        input: "Review the latest changes for bugs and security issues"
-        output: review_result
-        next: fix
-
-      fix:
-        type: agent_task
-        agent: implementer
-        mode: execute
-        input: "Fix the issues found: {{review_result}}"
-        next: end
-
-      end:
-        type: end
-```
-
-### Built-in Tools
-
-Each tool is a standalone npm package — install individually or use all out of the box:
-
-| Package | npm | Description |
-|---------|-----|-------------|
-| `@crewx/memory` | [![npm](https://img.shields.io/npm/v/@crewx/memory)](https://www.npmjs.com/package/@crewx/memory) | Persistent agent memory (markdown + frontmatter) |
-| `@crewx/doc` | [![npm](https://img.shields.io/npm/v/@crewx/doc)](https://www.npmjs.com/package/@crewx/doc) | Document TOC extraction and section reader |
-| `@crewx/search` | [![npm](https://img.shields.io/npm/v/@crewx/search)](https://www.npmjs.com/package/@crewx/search) | BM25 full-text code/document search |
-| `@crewx/cron` | [![npm](https://img.shields.io/npm/v/@crewx/cron)](https://www.npmjs.com/package/@crewx/cron) | Scheduled task execution |
-| `@crewx/wbs` | [![npm](https://img.shields.io/npm/v/@crewx/wbs)](https://www.npmjs.com/package/@crewx/wbs) | Work breakdown structure management |
-| `@crewx/workflow` | [![npm](https://img.shields.io/npm/v/@crewx/workflow)](https://www.npmjs.com/package/@crewx/workflow) | Semantic workflow engine (branch, parallel, approval) |
-| `@crewx/skill` | [![npm](https://img.shields.io/npm/v/@crewx/skill)](https://www.npmjs.com/package/@crewx/skill) | Reusable skill system (Claude Code compatible) |
-| `@crewx/knowledge-core` | [![npm](https://img.shields.io/npm/v/@crewx/knowledge-core)](https://www.npmjs.com/package/@crewx/knowledge-core) | Knowledge graph engine |
-| `@crewx/shared` | [![npm](https://img.shields.io/npm/v/@crewx/shared)](https://www.npmjs.com/package/@crewx/shared) | Shared utilities for built-in tools |
-
-### Desktop & Server
-
-- **Web Dashboard** — `npx crewx` serves a full management UI
-- **Electron Desktop App** — native app with the same features
-- **MCP Server** — JSON-RPC 2.0 endpoint for IDE integration (Claude Code, Cursor, etc.)
-
-## Use Cases
-
-### Development Workflow Automation
-Set up AI-powered code review, testing, and deployment pipelines. Multiple agents handle different stages of your development process.
-
-### Team Productivity
-Distribute tasks across specialized agents. A reviewer checks code quality while an implementer writes features — in parallel.
-
-### AI-Powered Business Automation
-Build agent teams that handle business processes end-to-end. From customer research to content generation, agents collaborate through workflows and shared knowledge.
-
-## Supported Providers
-
-### CLI Providers
-Use AI tools you already have installed:
-
-| Provider | CLI | Notes |
-|----------|-----|-------|
-| Claude (Anthropic) | `claude` | Complex reasoning, system design |
-| Gemini (Google) | `gemini` | Research, data analysis |
-| GitHub Copilot | `copilot` | Code generation |
-| Codex (OpenAI) | `codex` | General-purpose coding |
-
-### API Providers
-Connect any API-compatible model — including local LLMs:
-
-| Provider | Type | Notes |
-|----------|------|-------|
-| Ollama | Local LLM | Run fully local — zero cloud, zero cost, full privacy |
-| OpenAI API | Cloud API | GPT-4o, o1, etc. |
-| OpenAI-compatible | Cloud/Local | Any endpoint following OpenAI API spec |
-
-Mix CLI and API providers in the same team. For example, Claude for planning + Ollama for execution — best of both worlds.
-
-## Requirements
-
-- **Node.js** >= 22 (required by Copilot CLI provider)
-- **OS**: macOS, Windows, or Linux
-- At least one AI CLI installed: `claude`, `gemini`, `copilot`, or `codex`
-
-## Configuration
-
-### Minimal `crewx.yaml`
-
-```yaml
-agents:
-  - id: assistant
-    provider: cli/claude
-    inline:
-      prompt: "You are a helpful coding assistant."
-```
-
-### Full example with skills and workflows
-
-```yaml
-skills:
-  paths:
-    - ./skills          # Custom skill directory
-
-agents:
-  - id: lead
-    name: Tech Lead
-    provider: cli/claude
-    skills:
-      include:
-        - code-reviewer
-        - api-designer
-    inline:
-      model: claude-opus-4-6
-      prompt: |
-        You are a tech lead responsible for architecture decisions
-        and code quality.
-
-  - id: dev
-    name: Developer
-    provider: cli/copilot
-    inline:
-      prompt: |
-        You are a full-stack developer.
-        Follow the tech lead's guidance.
-```
-
-### CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `npx crewx` | Launch web dashboard |
-| `npx crewx init` | Initialize project with `crewx.yaml` |
-| `npx crewx q "@agent message"` | Query an agent (read-only) |
-| `npx crewx x "@agent message"` | Execute a task (can edit files) |
-| `npx crewx agent list` | List configured agents |
-| `npx crewx doctor` | Check system health |
-| `npx crewx skill list` | List available skills |
-| `npx crewx workflow list` | List workflows |
-| `npx crewx memory index <agent>` | View agent memory |
-| `npx crewx search "query"` | Full-text search |
-
-## Documentation
-
-- **Web Dashboard**: Launch with `npx crewx` and explore at `http://localhost:8150`
-- **API Reference**: Swagger UI available at `http://localhost:8150/api/docs`
-- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
-
-## License
-
-CrewX is built on an open-source CLI engine:
-
-| Component | License | Notes |
-|-----------|---------|-------|
-| CLI Engine + SDK | Apache-2.0 | Open source — [sowonlabs/crewx](https://github.com/sowonlabs/crewx) |
-| Built-in Tools (`@crewx/*`) | Proprietary | Free to use via npm, source not published |
-| Web UI + Server | Proprietary | Included in this package |
-
-The open-source CLI ([sowonlabs/crewx](https://github.com/sowonlabs/crewx)) is the foundation of this project. New CLI features are developed here first and periodically contributed back to the open-source repository.
-
----
-
-**[SowonLabs](https://sowonlabs.com)** | [GitHub](https://github.com/sowonlabs/crewx) | hello@sowonlabs.com
+# CrewX
+
+> Build your AI agent team — bring any model, orchestrate any workflow
+
+[![npm version](https://img.shields.io/npm/v/crewx)](https://www.npmjs.com/package/crewx)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org/)
+[![License](https://img.shields.io/badge/license-see%20below-blue)](#license)
+
+## What is CrewX?
+
+CrewX is a developer tool for building and managing AI agent teams. Define agents in YAML, wire them into workflows, and let them collaborate using built-in tools — all from a single CLI or web dashboard.
+
+- **Bring Your Own AI** — Claude, Gemini, Copilot, Codex, or any OpenAI-compatible model
+- **One command to start** — `npx crewx` launches everything
+- **Team orchestration** — agents work together through threads, workflows, and shared memory
+
+## Quick Start
+
+```bash
+npx crewx
+```
+
+That's it. This launches the CrewX dashboard at `http://localhost:8150` where you can manage agents, create threads, and monitor workflows.
+
+### Initialize a new project
+
+```bash
+npx crewx init
+```
+
+This creates a `crewx.yaml` in your project with default agents and settings.
+
+### Talk to your agents
+
+```bash
+# Ask a question (query mode)
+npx crewx q "@claude review this codebase"
+
+# Execute a task (agents can edit files)
+npx crewx x "@copilot implement login component"
+
+# Multi-agent collaboration
+npx crewx q "@claude @gemini compare approaches for caching"
+```
+
+## Key Features
+
+### BYOA (Bring Your Own AI)
+
+Use your existing AI subscriptions — or run fully local with Ollama. No vendor lock-in.
+
+| Provider | CLI | Status |
+|----------|-----|--------|
+| Claude | `claude` | Supported |
+| Gemini | `gemini` | Supported |
+| GitHub Copilot | `copilot` | Supported |
+| Codex | `codex` | Supported |
+| Ollama (local LLM) | API provider | Supported |
+| OpenAI-compatible | API provider | Supported |
+
+Build a **fully local AI team** with Ollama — no cloud, no API costs, complete data privacy. Mix and match cloud and local models in the same team.
+
+### Agent Teams
+
+Define your team in `crewx.yaml`:
+
+```yaml
+agents:
+  - id: reviewer
+    name: Code Reviewer
+    provider: cli/claude
+    inline:
+      model: claude-sonnet-4-6
+      prompt: |
+        You are a senior code reviewer.
+        Focus on correctness, performance, and security.
+
+  - id: implementer
+    name: Implementer
+    provider: cli/copilot
+    inline:
+      prompt: |
+        You are a full-stack developer.
+        Write clean, tested code following project conventions.
+```
+
+### Thread Conversations
+
+Thread-based conversations keep context across multiple interactions. Agents remember previous messages and can build on each other's work.
+
+```bash
+# Start a thread
+npx crewx q "@reviewer review PR #42" --thread="pr-42-review"
+
+# Continue the conversation
+npx crewx q "@implementer fix the issues found" --thread="pr-42-review"
+```
+
+### Semantic Workflows
+
+Define agent collaboration as semantic workflow YAML — branching, parallel execution, approval gates, and loops:
+
+```yaml
+# workflows/code-review.yaml
+workflows:
+  code-review:
+    metadata:
+      name: "Code Review Workflow"
+    nodes:
+      review:
+        type: agent_task
+        agent: reviewer
+        mode: query
+        input: "Review the latest changes for bugs and security issues"
+        output: review_result
+        next: fix
+
+      fix:
+        type: agent_task
+        agent: implementer
+        mode: execute
+        input: "Fix the issues found: {{review_result}}"
+        next: end
+
+      end:
+        type: end
+```
+
+### Built-in Tools
+
+Each tool is a standalone npm package — install individually or use all out of the box:
+
+| Package | npm | Description |
+|---------|-----|-------------|
+| `@crewx/memory` | [![npm](https://img.shields.io/npm/v/@crewx/memory)](https://www.npmjs.com/package/@crewx/memory) | Persistent agent memory (markdown + frontmatter) |
+| `@crewx/doc` | [![npm](https://img.shields.io/npm/v/@crewx/doc)](https://www.npmjs.com/package/@crewx/doc) | Document TOC extraction and section reader |
+| `@crewx/search` | [![npm](https://img.shields.io/npm/v/@crewx/search)](https://www.npmjs.com/package/@crewx/search) | BM25 full-text code/document search |
+| `@crewx/cron` | [![npm](https://img.shields.io/npm/v/@crewx/cron)](https://www.npmjs.com/package/@crewx/cron) | Scheduled task execution |
+| `@crewx/wbs` | [![npm](https://img.shields.io/npm/v/@crewx/wbs)](https://www.npmjs.com/package/@crewx/wbs) | Work breakdown structure management |
+| `@crewx/workflow` | [![npm](https://img.shields.io/npm/v/@crewx/workflow)](https://www.npmjs.com/package/@crewx/workflow) | Semantic workflow engine (branch, parallel, approval) |
+| `@crewx/skill` | [![npm](https://img.shields.io/npm/v/@crewx/skill)](https://www.npmjs.com/package/@crewx/skill) | Reusable skill system (Claude Code compatible) |
+| `@crewx/knowledge-core` | [![npm](https://img.shields.io/npm/v/@crewx/knowledge-core)](https://www.npmjs.com/package/@crewx/knowledge-core) | Knowledge graph engine |
+| `@crewx/shared` | [![npm](https://img.shields.io/npm/v/@crewx/shared)](https://www.npmjs.com/package/@crewx/shared) | Shared utilities for built-in tools |
+
+### Desktop & Server
+
+- **Web Dashboard** — `npx crewx` serves a full management UI
+- **Electron Desktop App** — native app with the same features
+- **MCP Server** — JSON-RPC 2.0 endpoint for IDE integration (Claude Code, Cursor, etc.)
+
+## Use Cases
+
+### Development Workflow Automation
+Set up AI-powered code review, testing, and deployment pipelines. Multiple agents handle different stages of your development process.
+
+### Team Productivity
+Distribute tasks across specialized agents. A reviewer checks code quality while an implementer writes features — in parallel.
+
+### AI-Powered Business Automation
+Build agent teams that handle business processes end-to-end. From customer research to content generation, agents collaborate through workflows and shared knowledge.
+
+## Supported Providers
+
+### CLI Providers
+Use AI tools you already have installed:
+
+| Provider | CLI | Notes |
+|----------|-----|-------|
+| Claude (Anthropic) | `claude` | Complex reasoning, system design |
+| Gemini (Google) | `gemini` | Research, data analysis |
+| GitHub Copilot | `copilot` | Code generation |
+| Codex (OpenAI) | `codex` | General-purpose coding |
+
+### API Providers
+Connect any API-compatible model — including local LLMs:
+
+| Provider | Type | Notes |
+|----------|------|-------|
+| Ollama | Local LLM | Run fully local — zero cloud, zero cost, full privacy |
+| OpenAI API | Cloud API | GPT-4o, o1, etc. |
+| OpenAI-compatible | Cloud/Local | Any endpoint following OpenAI API spec |
+
+Mix CLI and API providers in the same team. For example, Claude for planning + Ollama for execution — best of both worlds.
+
+## Requirements
+
+- **Node.js** >= 22 (required by Copilot CLI provider)
+- **OS**: macOS, Windows, or Linux
+- At least one AI CLI installed: `claude`, `gemini`, `copilot`, or `codex`
+
+## Configuration
+
+### Minimal `crewx.yaml`
+
+```yaml
+agents:
+  - id: assistant
+    provider: cli/claude
+    inline:
+      prompt: "You are a helpful coding assistant."
+```
+
+### Full example with skills and workflows
+
+```yaml
+skills:
+  paths:
+    - ./skills          # Custom skill directory
+
+agents:
+  - id: lead
+    name: Tech Lead
+    provider: cli/claude
+    skills:
+      include:
+        - code-reviewer
+        - api-designer
+    inline:
+      model: claude-opus-4-6
+      prompt: |
+        You are a tech lead responsible for architecture decisions
+        and code quality.
+
+  - id: dev
+    name: Developer
+    provider: cli/copilot
+    inline:
+      prompt: |
+        You are a full-stack developer.
+        Follow the tech lead's guidance.
+```
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx crewx` | Launch web dashboard |
+| `npx crewx init` | Initialize project with `crewx.yaml` |
+| `npx crewx q "@agent message"` | Query an agent (read-only) |
+| `npx crewx x "@agent message"` | Execute a task (can edit files) |
+| `npx crewx agent list` | List configured agents |
+| `npx crewx doctor` | Check system health |
+| `npx crewx skill list` | List available skills |
+| `npx crewx workflow list` | List workflows |
+| `npx crewx memory index <agent>` | View agent memory |
+| `npx crewx search "query"` | Full-text search |
+
+## Documentation
+
+- **Web Dashboard**: Launch with `npx crewx` and explore at `http://localhost:8150`
+- **API Reference**: Swagger UI available at `http://localhost:8150/api/docs`
+- **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+CrewX is built on an open-source CLI engine:
+
+| Component | License | Notes |
+|-----------|---------|-------|
+| CLI Engine + SDK | Apache-2.0 | Open source — [sowonlabs/crewx](https://github.com/sowonlabs/crewx) |
+| Built-in Tools (`@crewx/*`) | Proprietary | Free to use via npm, source not published |
+| Web UI + Server | Proprietary | Included in this package |
+
+The open-source CLI ([sowonlabs/crewx](https://github.com/sowonlabs/crewx)) is the foundation of this project. New CLI features are developed here first and periodically contributed back to the open-source repository.
+
+---
+
+**[SowonLabs](https://sowonlabs.com)** | [GitHub](https://github.com/sowonlabs/crewx) | hello@sowonlabs.com

package/bin/cli-commands.js

@@ -0,0 +1,34 @@
+/**
+ * SSOT for CLI subcommand whitelist.
+ *
+ * These are all commands that the launcher routes to the CLI engine (packages/cli).
+ * Must stay in sync with KNOWN_COMMANDS ∪ BUILTIN_COMMAND_NAMES ∪ NOT_YET_MIGRATED
+ * in packages/cli/src/commands/registry.ts.
+ *
+ * Verified by bin/__tests__/crewx-entrypoint.test.ts SSOT assertion test.
+ */
+export const CLI_SUBCOMMANDS = new Set([
+  // Query / Execute
+  'q', 'query',
+  'x', 'execute',
+
+  // Agent / Task
+  'agent',
+  'ps', 'kill', 'result', 'log',
+
+  // Diagnostics / Init
+  'doctor', 'init',
+  'help',
+
+  // Built-in tools
+  'memory', 'search', 'doc', 'wbs', 'cron', 'workflow', 'skill',
+
+  // Hook platform
+  'hook', 'hook-dispatch',
+
+  // Slack / Adapters
+  'slack', 'slack:files',
+
+  // Not-yet-migrated
+  'template', 'templates', 'chat', 'mcp',
+]);