@enderfga/claw-orchestrator 3.0.0

package/skills/references/cli.md

@@ -0,0 +1,187 @@
+# CLI Reference
+
+The CLI is an HTTP client that talks to the Claw Orchestrator embedded server. In plugin mode, the server auto-starts. In standalone mode, run `clawo serve` first.
+
+> **v2.x → v3.0:** The binary was renamed from `claude-code-skill` to `clawo`. The old binary is still installed as an alias for the duration of v3.0.x and will be removed in v3.1. Update scripts to use `clawo` before upgrading.
+
+## Server
+
+```bash
+clawo serve [-p, --port <port>]
+```
+
+Start standalone embedded server (default port 18796). Set `CLAUDE_CODE_API_URL` to override the base URL.
+
+### Rate Limiting
+
+The embedded server enforces a sliding-window rate limit of 100 requests per minute per IP address. Requests exceeding the limit receive HTTP 429 (Too Many Requests). This prevents accidental runaway scripts from overwhelming the server.
+
+### OpenAI-Compatible API
+
+The server exposes an OpenAI-compatible chat completions endpoint, enabling any webchat frontend to use it as a backend.
+
+**Endpoints:**
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/chat/completions` | POST | Chat completions (streaming + non-streaming) |
+| `/v1/models` | GET | List available models |
+
+**Request format** (same as OpenAI):
+```json
+{
+  "model": "claude-sonnet-4-6",
+  "messages": [{"role": "user", "content": "Hello!"}],
+  "stream": true
+}
+```
+
+**Session routing:** Each conversation maps to a persistent session for prompt cache reuse. Session key resolved from (in priority order):
+1. `X-Session-Id` header
+2. `user` field in the request body
+3. Default singleton session
+
+**Model routing:** The `model` field auto-routes to the correct engine:
+- `claude-*`, `opus`, `sonnet`, `haiku` → Claude engine
+- `gpt-*` → Codex engine
+- `composer-*` → Cursor engine
+- `gemini-*` → Gemini engine
+
+**CORS:** `/v1/` paths allow cross-origin requests by default. Set `OPENCLAW_CORS_ORIGINS=*` to allow all origins on all paths.
+
+**Auto-compact:** When a session's context utilization exceeds 80%, the endpoint automatically compacts the session before sending the next message.
+
+## Session Management
+
+### session-start
+
+```bash
+clawo session-start [name] [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-d, --cwd <dir>` | Working directory |
+| `-e, --engine <engine>` | Engine: `claude` (default), `codex`, or `gemini` |
+| `-m, --model <model>` | Model name or alias |
+| `--permission-mode <mode>` | `acceptEdits`, `plan`, `auto`, `bypassPermissions` |
+| `--effort <level>` | `low`, `medium`, `high`, `max`, `auto` |
+| `--allowed-tools <tools>` | Comma-separated tool whitelist |
+| `--max-turns <n>` | Max agent loop turns |
+| `--max-budget <usd>` | API cost ceiling |
+| `--system-prompt <text>` | Replace system prompt |
+| `--append-system-prompt <text>` | Append to system prompt |
+| `--agents <json>` | Custom sub-agents JSON |
+| `--agent <name>` | Default agent |
+| `--bare` | No CLAUDE.md, no git context |
+| `-w, --worktree [name]` | Git worktree |
+| `--fallback-model <model>` | Fallback model |
+| `--json-schema <schema>` | JSON Schema for structured output |
+| `--mcp-config <paths>` | MCP config files (comma-separated) |
+| `--settings <path>` | Settings.json path |
+| `--skip-persistence` | Disable session persistence |
+| `--betas <headers>` | Beta headers (comma-separated) |
+| `--enable-agent-teams` | Enable agent teams |
+| `--include-hook-events` | Stream hook lifecycle events (PreToolUse/PostToolUse) |
+| `--permission-prompt-tool <tool>` | Delegate permission prompts to an MCP tool (non-interactive use) |
+| `--exclude-dynamic-system-prompt-sections` | Move cwd/env/git context to user message for better prompt cache hits (auto-enabled with `--bare`) |
+| `--debug <categories>` | Enable targeted debug output by category (e.g. `"api,mcp"`) |
+| `--debug-file <path>` | Write debug output to file |
+| `--from-pr <n>` | Resume a session linked to a GitHub PR number or URL |
+| `--channels <spec>` | MCP channel subscription (research preview) |
+| `--dangerously-load-development-channels <spec>` | Development MCP channel subscriptions (research preview) |
+| `ENABLE_PROMPT_CACHING_1H=1` (env var) | Enable 1-hour prompt cache TTL (auto-set with `--bare`) |
+
+### session-send
+
+```bash
+clawo session-send <name> <message> [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--effort <level>` | Override effort for this message |
+| `--plan` | Enable plan mode |
+| `-s, --stream` | Collect streaming chunks |
+| `-t, --timeout <ms>` | Timeout (default 300000) |
+
+### session-stop
+
+```bash
+clawo session-stop <name>
+```
+
+### session-list
+
+```bash
+clawo session-list
+```
+
+### session-status
+
+```bash
+clawo session-status <name>
+```
+
+### session-grep
+
+```bash
+clawo session-grep <name> <pattern> [-n, --limit <n>]
+```
+
+### session-compact
+
+```bash
+clawo session-compact <name> [--summary <text>]
+```
+
+## Agent Management
+
+```bash
+clawo agents-list [-d, --cwd <dir>]
+clawo agents-create <name> [--description <desc>] [--prompt <prompt>]
+```
+
+## Skills Management
+
+```bash
+clawo skills-list [-d, --cwd <dir>]
+clawo skills-create <name> [--description <desc>] [--prompt <prompt>] [--trigger <t>]
+```
+
+## Rules Management
+
+```bash
+clawo rules-list [-d, --cwd <dir>]
+clawo rules-create <name> [--description <desc>] [--content <text>] [--paths <glob>] [--condition <expr>]
+```
+
+## Agent Teams
+
+```bash
+clawo session-team-list <name>
+clawo session-team-send <name> <teammate> <message>
+```
+
+## SDK-Only Tools (No CLI Wrapper)
+
+The following tools are available through the OpenClaw plugin SDK and TypeScript API but do not have CLI commands. Use the SDK directly or call them via OpenClaw's tool system.
+
+| Tool | Description |
+|------|-------------|
+| `sessions_overview` | Aggregate dashboard of all active sessions |
+| `session_update_tools` | Hot-swap allowed/disallowed tools via `--resume` |
+| `session_switch_model` | Switch model mid-session via `--resume` |
+| `council_start` | Start multi-agent council with worktree isolation |
+| `council_status` | Poll council progress and agent responses |
+| `council_abort` | Abort a running council |
+| `council_inject` | Inject a message into the next council round |
+| `session_send_to` | Cross-session messaging (immediate or queued) |
+| `session_inbox` | Read inbox messages for a session |
+| `session_deliver_inbox` | Deliver queued messages to an idle session |
+| `ultraplan_start` | Start background Opus planning session |
+| `ultraplan_status` | Poll ultraplan progress |
+| `ultrareview_start` | Start fleet of parallel reviewer agents |
+| `ultrareview_status` | Poll ultrareview findings |
+
+See [Tools Reference](./tools.md) for full parameter documentation.

package/skills/references/council.md

@@ -0,0 +1,210 @@
+# Council
+
+The council system orchestrates multiple AI agents working in parallel on the same codebase, using git worktree isolation, round-based execution, and consensus voting.
+
+Ported from [three-minds](https://github.com/Enderfga/three-minds) and adapted to run directly through `SessionManager` + `ISession`.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────┐
+│                  Council                      │
+│                                              │
+│  Round 1 (Planning):                         │
+│    Agent 1 ──┐                               │
+│    Agent 2 ──┼── parallel ── plan.md         │
+│    Agent 3 ──┘                               │
+│                                              │
+│  Round 2+ (Execution):                       │
+│    Agent 1 ──┐                               │
+│    Agent 2 ──┼── parallel ── code + tests    │
+│    Agent 3 ──┘                               │
+│                                              │
+│  Vote: all YES? ─── yes ──→ Review           │
+│         │                    │               │
+│         no ──→ next round    ├─ Accept ──→ Cleanup & Done
+│                              └─ Reject ──→ Rewrite plan.md
+└──────────────────────────────────────────────┘
+```
+
+### Two-Phase Protocol
+
+**Round 1 — Planning**: All agents create `plan.md` in parallel. No business code allowed. Each agent works in its own git worktree, merges plan to `main`.
+
+**Rounds 2+ — Execution**: Agents claim tasks from `plan.md`, write code, run tests, merge to `main`, and review each other's work.
+
+### Git Worktree Isolation
+
+Each agent gets a physically isolated working directory:
+
+```
+project/
+├── .worktrees/
+│   ├── Architect/     ← council/Architect branch
+│   ├── Engineer/      ← council/Engineer branch
+│   └── Reviewer/      ← council/Reviewer branch
+└── (main branch)
+```
+
+Agents cannot interfere with each other's files. All integration happens via `git merge` to `main`.
+
+### Consensus Voting
+
+Every agent must include `[CONSENSUS: YES]` or `[CONSENSUS: NO]` at the end of each round's response. The council continues until:
+- **All agents vote YES** — consensus reached
+- **Max rounds reached** — timeout
+- **Aborted** — user intervention
+
+## Quick Start
+
+### Via Tool
+
+```json
+{
+  "tool": "council_start",
+  "args": {
+    "task": "Build a REST API with authentication and rate limiting",
+    "projectDir": "/tmp/my-api-project",
+    "maxRounds": 10
+  }
+}
+```
+
+This starts a 3-agent council (Planner, Generator, Evaluator) with default settings.
+
+### Via TypeScript
+
+```typescript
+import { SessionManager } from '@enderfga/claw-orchestrator';
+
+const manager = new SessionManager();
+
+const session = manager.councilStart(
+  'Build a REST API with authentication',
+  {
+    agents: [
+      { name: 'Planner', emoji: '🟠', persona: 'Technical planner focused on requirements decomposition and architecture' },
+      { name: 'Generator', emoji: '🟢', persona: 'Implementation engineer focused on shipping correct code per plan' },
+      { name: 'Evaluator', emoji: '🔵', persona: 'Independent quality gate focused on verification and acceptance' },
+    ],
+    maxRounds: 10,
+    projectDir: '/tmp/my-api-project',
+  }
+);
+
+console.log(`Council started: ${session.id}`);
+// Poll for status
+const status = manager.councilStatus(session.id);
+```
+
+### Mixed Engines
+
+Agents can use different engines and models:
+
+```json
+{
+  "agents": [
+    { "name": "Claude", "emoji": "🎭", "engine": "claude", "model": "opus", "persona": "Deep reasoning" },
+    { "name": "Codex", "emoji": "🧠", "engine": "codex", "model": "gpt-5.4", "persona": "Fast implementation" },
+    { "name": "Gemini", "emoji": "💎", "engine": "gemini", "model": "gemini-3.1-pro-preview", "persona": "Creative solutions" }
+  ]
+}
+```
+
+## Council Tools
+
+| Tool | Description |
+|------|-------------|
+| `council_start` | Start a council. Runs in background, returns session ID immediately. |
+| `council_status` | Get current status (running/consensus/max_rounds/error), responses, votes. |
+| `council_abort` | Stop all agent sessions and terminate the council. |
+| `council_inject` | Inject a user message into all agents' prompts in the next round. |
+| `council_review` | Review completed council output: changed files, branches, plan status, agent summaries. |
+| `council_accept` | Accept work and clean up: remove worktrees, branches, plan.md, reviews/. |
+| `council_reject` | Reject work: rewrite plan.md with feedback for the council to retry. |
+
+## Post-Processing Lifecycle
+
+After a council reaches consensus or hits max rounds, use the review/accept/reject tools to finalize the work.
+
+### 1. Review
+
+```json
+{ "tool": "council_review", "args": { "id": "<council-id>" } }
+```
+
+Returns a structured report:
+- **changedFiles**: all files modified by the council with insertion/deletion counts
+- **branches**: remaining `council/*` branches
+- **worktrees**: remaining council worktrees
+- **planContent**: full plan.md text (check for unchecked tasks)
+- **reviews**: review files in `reviews/` directory
+- **agentSummaries**: final-round output preview from each agent
+
+### 2. Accept
+
+```json
+{ "tool": "council_accept", "args": { "id": "<council-id>" } }
+```
+
+Cleans up all council scaffolding:
+- Removes all `council/*` worktrees and `.worktrees/` directory
+- Deletes all `council/*` branches
+- Removes `plan.md` and `reviews/` directory
+- Sets council status to `accepted`
+
+### 3. Reject
+
+```json
+{ "tool": "council_reject", "args": { "id": "<council-id>", "feedback": "..." } }
+```
+
+Rewrites `plan.md` with rejection feedback and commits it. All worktrees and branches are preserved so the council can be restarted to address the feedback.
+
+## Configuration
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `maxRounds` | 15 | Maximum collaboration rounds |
+| `agentTimeoutMs` | 1,800,000 (30 min) | Per-agent timeout per round |
+| `maxTurnsPerAgent` | 30 | Max tool turns per agent per round |
+| `maxBudgetUsd` | — | API spend limit per agent |
+
+### defaultPermissionMode
+
+Optional. Sets the default permission mode for council agents when individual agents don't specify one. Defaults to `bypassPermissions`.
+
+```typescript
+manager.councilStart('task', {
+  agents: [...],
+  maxRounds: 10,
+  projectDir: '/project',
+  defaultPermissionMode: 'acceptEdits', // override the bypassPermissions default
+});
+```
+
+Permission priority: agent-level `permissionMode` > `defaultPermissionMode` > `'bypassPermissions'`
+
+> **Note (Claude CLI 2.1.121+):** When agent personas are persisted as Claude agent files with frontmatter, the `permissionMode`, `tools`, and `disallowedTools` fields are now **enforced** by `--agent` and `--print` modes (previously advisory). If you write agent files with restrictive `tools` lists, expect those agents to refuse calls to other tools at runtime.
+
+## System Prompt
+
+The council system prompt is loaded from `configs/council-system-prompt.md` and supports hot-editing. It includes 9 charter sections tuned through extensive multi-agent collaboration testing:
+
+| Section | Purpose |
+|---------|---------|
+| §0 No Hallucination | Agents must use tools, never fabricate results |
+| §1 Plan First | Two-phase protocol with plan.md |
+| §2 Parallel Coordination | Claim/done protocol for concurrent work |
+| §3 Truth in Git | Git state over conversation memory |
+| §4 Merge to Main | Local only, never push |
+| §5 Cross-Review | Structured APPROVE/REQUEST_CHANGES |
+| §6 Auto-Conflict Resolution | Never stop on merge conflicts |
+| §7 Action Over Words | Never ask permission, just work |
+| §8 Efficient Tool Use | Minimum necessary principle |
+
+Placeholders: `{{emoji}}`, `{{name}}`, `{{persona}}`, `{{workDir}}`, `{{otherBranches}}`
+
+## Transcript Logging
+
+All council sessions save transcripts to `~/.openclaw/council-logs/council-<timestamp>.md`. Completed councils remain queryable via `council_status` for 30 minutes after completion.

package/skills/references/getting-started.md

@@ -0,0 +1,133 @@
+# Getting Started
+
+## Installation
+
+### Standalone CLI
+
+```bash
+npm install -g @enderfga/claw-orchestrator
+
+# Start the embedded server
+clawo serve
+
+# Drive sessions from the command line
+clawo session-start myproject -d ~/project
+clawo session-send myproject "fix the auth bug"
+clawo session-stop myproject
+```
+
+> **Migrating from v2.x?** The legacy binary `claude-code-skill` is still installed alongside `clawo` for the duration of the v3.0.x line; both invoke the same script. Plan to migrate scripts to `clawo` before upgrading to v3.1.
+
+### As OpenClaw Plugin
+
+```bash
+openclaw plugins install @enderfga/claw-orchestrator --dangerously-force-unsafe-install
+openclaw gateway restart
+```
+
+> **Why `--dangerously-force-unsafe-install`?** Claw Orchestrator spawns Claude Code / Codex / Gemini / Cursor Agent CLI subprocesses via `child_process`, which OpenClaw's security scanner flags by design. The flag is required — there is no way to drive coding CLIs without process spawning.
+
+Agents automatically get access to all session, council, and management tools.
+
+### TypeScript Library
+
+```typescript
+import { SessionManager } from '@enderfga/claw-orchestrator';
+
+const manager = new SessionManager({ defaultModel: 'claude-sonnet-4-6' });
+
+const session = await manager.startSession({
+  name: 'backend-fix',
+  cwd: '/path/to/project',
+  permissionMode: 'acceptEdits',
+});
+
+const result = await manager.sendMessage('backend-fix', 'Fix the failing tests');
+console.log(result.output);
+
+await manager.stopSession('backend-fix');
+```
+
+## Requirements
+
+- **Node.js >= 22**
+- **Claude Code CLI >= 2.1** — `npm install -g @anthropic-ai/claude-code`
+- **OpenClaw >= 2026.3.0** — for plugin mode (optional)
+- **OpenAI Codex CLI >= 0.112** — `npm install -g @openai/codex` (optional, for codex engine)
+- **Gemini CLI >= 0.35** — `npm install -g @google/gemini-cli` (optional, for gemini engine)
+
+### Engine Authentication
+
+Each engine requires its own authentication before use:
+
+- **Claude Code** — run `claude /login` or set `ANTHROPIC_API_KEY`
+- **Codex** — run `codex login` or set `OPENAI_API_KEY`
+- **Gemini** — run `gemini login` or set `GEMINI_API_KEY`
+
+The plugin does not manage authentication — it expects each CLI to be ready to run.
+
+### Embedded Server Authentication
+
+The embedded HTTP server (used by CLI and standalone mode) optionally supports bearer token authentication:
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENCLAW_SERVER_TOKEN` | Set to enable bearer token auth. All requests (except `/health`) must include `Authorization: Bearer <token>` |
+
+When set, the token is also written to `~/.openclaw/server-token` for the CLI to read automatically. Default: no auth (localhost binding is the primary security boundary).
+
+### OpenAI-Compatible Endpoint
+
+The server exposes an OpenAI-compatible API at `/v1/chat/completions`. It serves both kinds of clients as first-class citizens:
+
+- **Upstream agents** (OpenClaw main loop, cron, subagents) that maintain their own transcript and only forward the latest user turn — uses default mode.
+- **Webchat / labeling tools** (ChatGPT-Next-Web, Open WebUI, LobeChat) that re-send the full transcript every turn — set `OPENAI_COMPAT_NEW_CONVO_HEURISTIC=1`.
+
+Quick config for any client:
+
+| Setting | Value |
+|---------|-------|
+| API Base URL | `http://127.0.0.1:18796/v1` |
+| API Key | The value of `OPENCLAW_SERVER_TOKEN`, or any string if auth is disabled |
+| Model | `claude-opus-4-6`, `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview`, etc. |
+
+See [openai-compat.md](./openai-compat.md) for the full session-keying rules, `X-Session-Reset` semantics, the legacy-heuristic env var, and the `/v1/sessions` inspection endpoint.
+
+## Configuration
+
+In `~/.openclaw/openclaw.json`:
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "claw-orchestrator": {
+        "enabled": true,
+        "config": {
+          "claudeBin": "claude",
+          "defaultModel": "claude-opus-4-6",
+          "defaultPermissionMode": "acceptEdits",
+          "defaultEffort": "auto",
+          "maxConcurrentSessions": 5,
+          "sessionTtlMinutes": 120,
+          "proxy": {
+            "enabled": false,
+            "bigModel": "gemini-3.1-pro-preview",
+            "smallModel": "gemini-3-flash-preview"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Next Steps
+
+- [Sessions](./sessions.md) — persistent session lifecycle and management
+- [Session Inbox](./inbox.md) — cross-session messaging
+- [Multi-Engine](./multi-engine.md) — using Claude Code and Codex side by side
+- [Council](./council.md) — multi-agent collaboration with consensus voting
+- [Ultraplan & Ultrareview](./ultra.md) — deep planning and fleet code review
+- [Tools Reference](./tools.md) — complete tool API reference (27 tools)
+- [CLI Reference](./cli.md) — command-line interface

package/skills/references/inbox.md

@@ -0,0 +1,81 @@
+# Session Inbox
+
+Cross-session messaging allows different sessions to communicate with each other. Inspired by Claude Code's UDS Inbox feature.
+
+## How It Works
+
+```
+Session A (planner)          SessionManager           Session B (coder)
+     │                            │                        │
+     ├── sendTo(B, "do X") ──────►│                        │
+     │                            ├── B idle? ─── yes ────►│ deliver immediately
+     │                            │         │              │
+     │                            │         no             │
+     │                            │         │              │
+     │                            │    queue in inbox      │
+     │                            │         │              │
+     │                            │    ... B becomes idle  │
+     │                            ├── deliverInbox(B) ────►│ deliver queued msgs
+```
+
+- **Idle sessions** receive messages immediately as a new user turn
+- **Busy sessions** have messages queued in an inbox (max 200 messages)
+- Messages are wrapped in `<cross-session-message>` XML tags
+- Supports broadcast to all sessions via `to: "*"`
+
+## Usage
+
+### Send a Message
+
+```typescript
+// Direct message
+await manager.sessionSendTo('planner', 'coder', 'The auth module needs rate limiting', 'auth rate limit');
+
+// Broadcast to all sessions
+await manager.sessionSendTo('monitor', '*', 'Build failed on main!', 'build failure');
+```
+
+### Read Inbox
+
+```typescript
+// Unread messages only (default)
+const unread = manager.sessionInbox('coder');
+
+// All messages
+const all = manager.sessionInbox('coder', false);
+```
+
+### Deliver Queued Messages
+
+When a session finishes a task and becomes idle, deliver its queued messages:
+
+```typescript
+const count = await manager.sessionDeliverInbox('coder');
+console.log(`Delivered ${count} queued messages`);
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `claude_session_send_to` | Send message between sessions |
+| `claude_session_inbox` | Read inbox messages |
+| `claude_session_deliver_inbox` | Deliver queued messages to idle session |
+
+## Message Format
+
+Messages delivered to sessions are wrapped in XML:
+
+```xml
+<cross-session-message from="planner" summary="auth rate limit">
+The auth module needs rate limiting. Please add a token bucket...
+</cross-session-message>
+```
+
+Attributes are properly escaped to prevent XML injection.
+
+## Inbox Limits
+
+- **Max size**: 200 messages per session
+- **Eviction**: oldest read messages dropped first, then oldest unread
+- **No TTL**: messages persist until read or evicted (in-memory only, not persisted to disk)