ace-swarm 1.1.0 → 1.1.3

package/README.md

@@ -1,6 +1,8 @@
 # ACE Swarm MCP Server
 
-ACE Swarm packages the ACE framework (agents, skills, prompts, tasks, handoffs, and state scaffolding) as an MCP server and CLI.
+ACE Swarm packages the ACE framework (agents, skills, schemas, prompts, tasks, handoffs, and state scaffolding) as an MCP server and turnkey CLI.
+
+Swarm agents (`orchestrator`, `vos`, `ui`, `coders`) and composable agents (`skeptic`, `ops`, `research`, `spec`, `builder`, `qa`, `docs`) are treated as one unified agent system, with composable agents available as subagents for every swarm workflow.
 
 ## Install
 
@@ -16,92 +18,208 @@ ace mcp
 ace-swarm mcp
 ```
 
-For one-off execution without installing globally:
+For one-off execution:
 
 ```bash
 npx -y ace-swarm mcp
 ```
 
-If you prefer the `ace` package name at invocation time, npm aliasing also works:
+## Turnkey Setup (Recommended)
+
+Bootstrap everything into the current workspace, including `.agents`, `agent-state`, scripts, and multi-client MCP config bundle:
 
 ```bash
-npx -y ace@npm:ace-swarm mcp
+npx -y ace-swarm turnkey --project "My Project"
 ```
 
-For install-time aliasing:
+Equivalent command:
 
 ```bash
-npm install -g ace@npm:ace-swarm
+npx -y ace-swarm init --project "My Project"
 ```
 
+This writes:
+
+- `agent-state/*`
+- `.agents/ACE/*` and `.agents/skills/*`
+- `tasks/*`
+- `scripts/ace/*`
+- `.vscode/mcp.json`
+- `.mcp-config/{codex.config.toml,vscode.mcp.json,claude_desktop_config.json,cursor.mcp.json,antigravity.mcp.json}`
+
+### Turnkey with Ollama (Local Models)
+
+Bootstrap ACE + local model profile in one command:
+
+```bash
+npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b
+```
+
+Then enable and verify local runtime:
+
+```bash
+ollama serve
+ollama pull llama3.1:8b
+ace doctor --llm ollama --model llama3.1:8b
+```
+
+If you need to explicitly (re)write MCP config for your editor:
+
+```bash
+ace mcp-config --client vscode > .vscode/mcp.json
+# or choose codex|claude|cursor|antigravity
+```
+
+Artifacts written for local-model flow:
+
+- `.ace/llm-profile.json`
+- `.ace/doctor-checks.md`
+
+Rollout status:
+
+- `P0`: `init/turnkey` supports `--llm ollama --model --ollama-url`.
+- `P1`: `ace doctor` validates MCP config, Ollama endpoint, and model presence.
+- `P2`: MCP `bootstrap_state` supports `llm_provider`, `ollama_model`, `ollama_base_url`.
+
+## Client Compatibility
+
+ACE Swarm ships config templates for:
+
+- Codex
+- VS Code
+- Claude Desktop
+- Cursor
+- Antigravity
+
+### Get config snippets from CLI
+
+```bash
+ace mcp-config --client codex
+ace mcp-config --client vscode
+ace mcp-config --all
+```
+
+### Expected config targets
+
+- `codex`: `$CODEX_HOME/config.toml` (or `~/.codex/config.toml`)
+- `vscode`: `.vscode/mcp.json` (workspace)
+- `claude`: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux)
+- `cursor`: `~/.cursor/mcp.json`
+- `antigravity`: import/use `.mcp-config/antigravity.mcp.json` from the client MCP settings UI
+
 ## CLI Commands
 
 ```bash
-ace mcp                      # start MCP server on stdio
-ace init                     # bootstrap ACE files/state in current workspace
-ace init --project "My App" # set project name in global-state/MASTER_PLAN.md
-ace init --force             # overwrite scaffolded files
-ace mcp-config               # print .vscode/mcp.json snippet
-ace paths                    # show resolved package/workspace paths
+ace mcp                                 # start MCP server on stdio
+ace serve                               # alias for mcp
+ace init [options]                      # bootstrap ACE files into current workspace
+ace turnkey [options]                   # same as init (turnkey alias)
+ace doctor [options]                    # local LLM + MCP readiness checks
+ace mcp-config [--client <name>|--all]  # print one/all MCP client snippets
+ace paths                               # show resolved package/workspace paths
+```
+
+Options for `init` / `turnkey`:
+
+```bash
+--project <name>                # Project name for global-state/MASTER_PLAN.md
+--force                         # Overwrite scaffolded files
+--no-mcp-config                 # Skip .vscode/mcp.json
+--no-client-config-bundle       # Skip .mcp-config client bundle
+--llm <provider>                # ollama
+--model <name>                  # local model name (default: llama3.1:8b)
+--ollama-url <url>              # Ollama base URL (default: http://127.0.0.1:11434)
+```
+
+Options for `doctor`:
+
+```bash
+--llm <provider>                # ollama (or auto from .ace/llm-profile.json)
+--model <name>                  # override model to check
+--ollama-url <url>              # override Ollama URL to check
 ```
 
-## VS Code MCP Configuration
+## Initiate ACE Swarm
 
-Use this in `.vscode/mcp.json`:
+After bootstrap, start your MCP host and issue:
 
-```json
-{
-  "servers": {
-    "ace-swarm": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "ace-swarm", "mcp"]
-    }
-  }
-}
+```text
+initiate ACE
 ```
 
-## What Gets Packaged
+## Schema Validation (Runtime)
+
+Schema validation is wired into MCP tool execution paths:
+
+- `create_handoff`: validates handoff payload before write
+- `validate_handoff`: supports `schema_mode: auto|swarm|agent-state`
+- `write_workspace_file`: blocks invalid writes for:
+  - `agent-state/HANDOFF.json`
+  - `agent-state/HANDOFF_HISTORY/*.json`
+  - `agent-state/STATUS_EVENTS.ndjson`
+  - `ARTIFACT_MANIFEST.json`
+  - `SWARM_HANDOFF.*.json`
+
+Validation code is in `src/schemas.ts`.
+
+## Kanban Snapshot (Runtime)
+
+ACE Swarm now maintains a lightweight Kanban board in workspace state:
 
-- Agent instructions and manifests:
-  - Orchestrator, VOS, UI, Coders
-- Skills:
-  - `ace-orchestrator`, `codemunch`, `codesnipe`
-- Task artifacts:
-  - `todo.md`, `lessons.md`, `role_tasks.md`, `cli_work_split.md`
-  - `SWARM_HANDOFF.template.json` + examples
-- ACE state scaffolding:
-  - `agent-state/*` with module and gate manifests
-  - `global-state`, `venture-state`, `brand-state`, `engineering-state`
+- `agent-state/kanban.json`
+- `agent-state/kanban.html`
 
-## MCP Coverage
+You can regenerate manually with MCP tool `generate_kanban_ui`, and the server auto-refreshes Kanban after major artifact writes (`update_todo`, `create_handoff`, `bootstrap_state`, and `write_workspace_file` on ACE state/task/code paths).
 
-### Tools
+Resources:
 
-- Agent + manifest loaders
-- Skill listing and skill instructions
-- Handoff creation + validation
-- TODO and lessons management
-- Task routing
-- Workspace read/write/list
-- Bootstrap + framework status
-- MCP config snippet
+- `ace://kanban` (JSON)
+- `ace://kanban/html` (HTML)
 
-### Prompts
+## New Runtime State Stores
 
-- `ace-orchestrator`, `ace-vos`, `ace-ui`, `ace-coders`
-- `ace-initiate`, `ace-genesis`, `ace-handoff`, `ace-lessons`
-- `ace-skill`, `ace-codemunch`, `ace-codesnipe`, `ace-skills-index`
+ACE Swarm now persists additional orchestration stores:
 
-### Resources
+- `agent-state/run-ledger.json` (major updates + regressions)
+- `agent-state/todo-state.json` (explicit TODO statuses, dependencies, transition gates)
+- `agent-state/index.json` (workspace delta scan index)
+- `agent-state/handoff-registry.json` (handoff lifecycle: `open|accepted|blocked|completed`)
 
-- `ace://agents/{role}/instructions`
-- `ace://agents/{role}/manifest`
-- `ace://tasks/{key}`
-- `ace://handoffs/{key}`
-- `ace://skills`
-- `ace://skills/{name}/instructions`
-- `ace://workspace/{path+}`
+New/extended tools:
+
+- `update_todo` now supports either full board replacement (`new_content`) or gated node transitions (`node_id`, `status`)
+- `scan_workspace_delta` writes indexed changed/unchanged/deleted diffs
+- `ack_handoff` updates handoff lifecycle status
+- `get_run_ledger`, `get_todo_state`, `get_handoff_status` expose persisted store state
+
+New resources:
+
+- `ace://run-ledger`
+- `ace://index`
+- `ace://handoffs/status`
+- `ace://kernel/directive_kernel`
+- `ace://kernel/agent_registry`
+
+New tool:
+
+- `get_kernel_artifact` (`directive_kernel` | `agent_registry`)
+
+## ACE Assets Included
+
+### Agents (17)
+
+- **Swarm (4):** Orchestrator, VOS, UI, Coders
+- **Composable (13):** agent-astgrep, agent-skeptic, agent-ops, agent-research, agent-spec, agent-builder, agent-qa, agent-docs, agent-memory, agent-security, agent-observability, agent-eval, agent-release
+
+### Skills
+
+- Existing: `ace-orchestrator`, `codemunch`, `codesnipe`
+- New: `state-auditor`, `schema-forge`, `handoff-lint`, `memory-curator`, `risk-quant`, `eval-harness`, `incident-commander`, `release-sentry`
+
+### Tasks and Handoff Artifacts
+
+- `todo.md`, `lessons.md`, `role_tasks.md`, `cli_work_split.md`
+- `SWARM_HANDOFF.template.json` and examples
 
 ## Development
 
@@ -111,3 +229,11 @@ npm install
 npm run build
 npm run start
 ```
+
+## Documentation References
+
+- OpenAI Codex MCP config: [platform.openai.com/docs/codex/mcp](https://platform.openai.com/docs/codex/mcp)
+- VS Code MCP: [code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+- Cursor MCP: [docs.cursor.com/context/model-context-protocol](https://docs.cursor.com/context/model-context-protocol)
+- Claude Desktop MCP quickstart: [modelcontextprotocol.io/quickstart/user](https://modelcontextprotocol.io/quickstart/user)
+- Antigravity MCP server setup: [docs.antigravity.dev/how-to/configuring-an-mcp-server](https://docs.antigravity.dev/how-to/configuring-an-mcp-server)