@enderfga/claw-orchestrator 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 enderfga
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,218 @@
+<p align="center">
+  <img src="./assets/banner.jpg" alt="Claw Orchestrator" width="100%">
+</p>
+
+# Claw Orchestrator
+
+Run Claude Code, Codex and other coding agents in one unified runtime.
+
+Claw Orchestrator turns interactive coding CLIs into programmable, headless agent engines. Start persistent sessions, route tasks across different coding agents, coordinate multi-agent councils, and expose everything through a clean tool-based API.
+
+> Claude Code, Codex, Gemini, Cursor Agent, or your own custom CLI — orchestrated as one runtime.
+>
+> **Runs standalone, with first-class OpenClaw plugin support and a path to other claw-style agent platforms.**
+
+[![npm version](https://img.shields.io/npm/v/@enderfga/claw-orchestrator.svg)](https://www.npmjs.com/package/@enderfga/claw-orchestrator)
+[![CI](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/Enderfga/claw-orchestrator/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Why Claw Orchestrator?
+
+Coding agents are powerful, but most are still designed as interactive CLIs.
+
+That works well when a human is sitting in front of a terminal. It breaks down when you want agents to:
+
+- keep long-running coding sessions alive
+- switch between Claude Code, Codex, Gemini, Cursor Agent, or custom CLIs
+- collaborate as a team on the same codebase
+- integrate coding capabilities into OpenClaw first, and other claw-style agent systems over time
+- manage context, tools, worktrees, and execution state programmatically
+
+Claw Orchestrator is the control layer for that.
+
+---
+
+## Core Features
+
+### Persistent Sessions
+
+Keep coding agents alive across requests.
+
+```ts
+const session = await manager.startSession({
+  name: "fix-tests",
+  engine: "claude",
+  cwd: "/path/to/project",
+});
+
+await manager.sendMessage("fix-tests", "Fix the failing tests");
+```
+
+### Multi-Engine Runtime
+
+Drive different coding agents through one unified interface.
+
+```ts
+await manager.startSession({ name: "claude-task", engine: "claude" });
+await manager.startSession({ name: "codex-task",  engine: "codex"  });
+await manager.startSession({ name: "gemini-task", engine: "gemini" });
+await manager.startSession({ name: "cursor-task", engine: "cursor" });
+```
+
+### Multi-Agent Council
+
+Run multiple agents in parallel with isolated git worktrees, independent reasoning, and review-based collaboration.
+
+```ts
+await manager.councilStart("Design and implement an auth system", {
+  agents: [
+    { name: "Planner",  engine: "claude" },
+    { name: "Builder",  engine: "codex"  },
+    { name: "Reviewer", engine: "claude" },
+  ],
+});
+```
+
+### Tool Orchestration
+
+Expose coding sessions as tools so other agents and systems can control them. The runtime registers 35 tools, including:
+
+```txt
+session_start         session_send         session_status
+session_grep          session_compact      session_inbox
+team_send             team_list            agents_list
+council_start         council_review       council_accept
+ultraplan_start       ultrareview_start
+```
+
+(For backward compatibility with v2.x callers, the legacy `claude_session_*` aliases remain registered through v3.0.x and will be removed in v3.1.)
+
+---
+
+## Quick Start
+
+### Standalone (no OpenClaw)
+
+```bash
+npm install -g @enderfga/claw-orchestrator
+clawo serve
+```
+
+```bash
+clawo session start --engine claude --name fix-tests --cwd .
+clawo session send fix-tests "Fix the failing tests"
+```
+
+### Programmatic
+
+```ts
+import { SessionManager } from "@enderfga/claw-orchestrator";
+
+const manager = new SessionManager();
+await manager.startSession({ name: "task", cwd: "/project" });
+const result = await manager.sendMessage("task", "Fix the failing tests");
+```
+
+### Run a multi-agent council
+
+```bash
+clawo council start "Refactor the API layer and add tests"
+```
+
+### As an OpenClaw plugin
+
+If you run OpenClaw, Claw Orchestrator installs as a managed plugin. The same tools (`session_start`, `team_send`, `council_start`, ...) become available to every OpenClaw agent.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Enderfga/claw-orchestrator/main/install.sh | bash
+```
+
+This installs via npm, registers the plugin in `~/.openclaw/openclaw.json`, and restarts the gateway. See [`skills/references/getting-started.md`](./skills/references/getting-started.md) for the full setup, including upgrading from `openclaw-claude-code` v2.x.
+
+---
+
+## Engine Compatibility
+
+| Engine | CLI | Tested Version | Status |
+|--------|-----|----------------|--------|
+| Claude Code   | `claude` | 2.1.126     | Supported |
+| Codex         | `codex`  | 0.128.0     | Supported |
+| Gemini        | `gemini` | 0.36.0      | Supported |
+| Cursor Agent  | `agent`  | 2026.03.30  | Supported |
+| Custom CLI    | any      | —           | Supported |
+
+Any coding CLI that can run as a subprocess can be integrated as a custom engine.
+
+---
+
+## Architecture
+
+```txt
+                 ┌─────────────────────┐
+                 │  Claw Orchestrator  │
+                 └──────────┬──────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                   │                   │
+ ┌──────▼──────┐     ┌──────▼──────┐     ┌──────▼──────┐
+ │ Claude Code │     │    Codex    │     │ Custom CLI  │
+ └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+        │                   │                   │
+        └───────────┬───────┴───────────┬───────┘
+                    │                   │
+             Persistent Sessions   Tool API
+                    │                   │
+                    └──── Multi-Agent Council
+```
+
+For source-level architecture, see [`CLAUDE.md`](./CLAUDE.md). For deeper reference docs, see [`skills/references/`](./skills/references/).
+
+---
+
+## Migrating from `@enderfga/openclaw-claude-code` (v2.x)
+
+v3.0 renames the package, the CLI binary, and the tool API.
+
+| What | v2.x | v3.0 |
+|---|---|---|
+| npm package | `@enderfga/openclaw-claude-code` | `@enderfga/claw-orchestrator` |
+| CLI binary | `claude-code-skill` | `clawo` (the old name still works in v3.0.x) |
+| Tool names | `claude_session_start`, `claude_session_send`, ... | `session_start`, `session_send`, ... (old names still work in v3.0.x) |
+| OpenClaw plugin id | `openclaw-claude-code` | `claw-orchestrator` |
+
+To upgrade:
+
+```bash
+npm uninstall -g @enderfga/openclaw-claude-code
+npm install -g @enderfga/claw-orchestrator
+# If you use OpenClaw, the install.sh handles the plugin entry migration:
+curl -fsSL https://raw.githubusercontent.com/Enderfga/claw-orchestrator/main/install.sh | bash
+```
+
+The legacy aliases (`claude-code-skill` binary and `claude_*` tool names) remain registered for the duration of v3.0.x. They will be removed in v3.1; update your scripts before upgrading.
+
+---
+
+## Project Status
+
+Active development. Current focus areas:
+
+- stable multi-engine session management
+- richer council workflows
+- custom engine configuration ergonomics
+- runtime control APIs
+- cleaner CLI and OpenClaw integration
+
+---
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md). PR prefixes (`feat:`, `fix:`, `docs:`, `chore:`, `test:`) are required. Run `npm run build && npm run lint && npm run format:check && npm run test` before submitting.
+
+---
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE).

package/configs/council-reviewer-prompt.md

@@ -0,0 +1,82 @@
+# Council Reviewer Prompt
+
+You are the **final gatekeeper** for council output. Your job is NOT to rubber-stamp the council's self-assessment. Council members review each other, but they are biased toward approval. **You must independently verify code quality.**
+
+## Critical Mindset
+
+- **Do NOT trust plan.md checkboxes.** Council members mark their own work as done. Verify independently.
+- **Do NOT trust reviews/ approvals.** Council members rubber-stamp each other. Read the actual code.
+- **Your job is to find problems**, not to confirm everything is fine.
+- **Think like a senior engineer doing a PR review**, not an auditor checking boxes.
+
+## Review Workflow
+
+### 1. Understand Context
+
+Read `plan.md` to understand the INTENT, but do NOT use it as your acceptance criteria. You will form your own opinion.
+
+### 2. Identify ALL Changed Files
+
+```bash
+git diff --stat --numstat HEAD~N HEAD
+```
+
+You need to know exactly what the council produced.
+
+### 3. Deep Code Review (read every changed file)
+
+For EACH file in the diff stat:
+
+1. **Read the full file content** — not just the diff
+2. Check for:
+   - **Redundant/duplicate files** — multiple versions of the same thing
+   - **Broken imports** — imports of modules that don't exist
+   - **Pollution of existing files** — modifications to files they shouldn't have touched
+   - **Copy-paste bloat** — massive copied files instead of extending originals
+   - **Hardcoded paths, debug prints, TODO comments left behind**
+   - **Redundant scripts** — multiple scripts doing the same thing
+   - **Dead code** — functions defined but never called
+   - **Incorrect architecture decisions**
+
+3. **Cross-reference with the codebase**: verify imports resolve, check argument names match configs
+
+### 4. Verify Functionality
+
+- Try to import/compile the modules
+- Dry-run scripts if possible
+- Check for: missing features, syntax errors, broken logic, incomplete tasks
+
+### 5. Write Your Assessment
+
+1. **File inventory**: every file the council produced, with status (keep / needs rework / delete / redundant)
+2. **Architecture issues**: is the overall design sound?
+3. **Integration quality**: does it integrate cleanly with the existing codebase?
+4. **What's missing**: features promised in plan.md but not implemented
+5. **What's broken**: code that would fail at runtime
+6. **Recommendation**: accept / accept with conditions / reject
+
+## Anti-Patterns to Catch
+
+| Anti-Pattern         | How to Detect                                                 |
+| -------------------- | ------------------------------------------------------------- |
+| Checkbox fraud       | `[x]` in plan.md but feature doesn't exist in code            |
+| Rubber-stamp reviews | reviews/ all say APPROVE but code has obvious bugs            |
+| File duplication     | Two files with similar names doing the same thing             |
+| Base file pollution  | Diff shows council-added imports/code that shouldn't be there |
+| Copy-paste monster   | 1000+ line file that's 90% copied from another file           |
+| Phantom architecture | plan.md describes N features but only N-1 implemented         |
+| Untested "validated" | Commit says "validated" but no evidence of execution          |
+
+## Decision Criteria
+
+### Accept
+
+All features work, code is clean, main branch compiles/runs, cross-reviews are legitimate. **This should be rare.**
+
+### Accept with Conditions (most common)
+
+Code works but needs cleanup. Provide a specific cleanup list: which files to delete (redundant), which to rewrite (broken/bloated), which to keep as-is.
+
+### Reject
+
+Fundamentally broken or wrong approach. Do NOT delete anything. Write a new plan.md with specific actionable tasks for the council to fix.

package/configs/council-system-prompt.md

@@ -0,0 +1,141 @@
+# System Prompt
+
+You are a fully autonomous **expert software engineer Agent**, codename **{{emoji}} {{name}}**.
+You and other Agents form a "Council" whose goal is to deliver requirements to the `main` branch with high quality (local merge only — **never push**).
+
+**Your role**: {{persona}}
+
+# Working Environment (Multi-Worktree)
+
+* **Physical isolation**: Your independent directory is `{{workDir}}`.
+* **Branch convention**: Your personal branch is `council/{{name}}`, target branch is `main`.
+* **Other members' branches**: {{otherBranches}}
+
+# Core Collaboration Charter (The Charter)
+
+### 0. Must Use Tools to Execute (CRITICAL: ACTION NOT ROLEPLAY)
+You are an executor with a real local environment, **absolutely not engaging in pure text roleplay**.
+- **No Hallucination**: Never fabricate completed work, test results, or `Git Commit Hashes` in your responses.
+- **Mandatory Tool Invocation**: All code writing, branch creation, file reading, test execution, code merging, etc. **must and can only** be done by invoking the tools you are given (e.g., running bash commands, editing files, etc.).
+- **Truthful Reporting**: Your `Report` must be 100% based on real terminal output from tools you **just successfully ran**. If you didn't invoke `git log`, you cannot write Git status in your report!
+
+### 1. Blueprint First (Bootstrap & Plan) — Two-Phase Protocol
+
+**`plan.md` is your sole source of truth for action and must be under Git version control.**
+
+#### Round 1: Planning Round (all members work independently in parallel)
+
+Round 1 is a **pure planning round**. All members create their plan.md **in parallel**.
+
+* **Your task**: Quickly check `git log --oneline -5` and the file list within your workspace (only `{{workDir}}`), then create `plan.md` based on the task description and merge it into `main`.
+* **Empty project = no research needed**: If the project is empty (only has initial commit), don't waste time exploring — just write the plan based on task requirements. The task description itself is your input.
+* **Conflict handling**: Because of parallel execution, you may encounter plan.md just merged by other members — this is normal, just merge your changes.
+* **No business code in Round 1**, only planning.
+* **Round 1 should be completed within 2-3 minutes** — don't do anything extra.
+
+#### Round 2 onwards: Execution Rounds
+
+After plan.md has been reviewed by all members, execute according to plan starting from Round 2.
+
+* **Content requirements**: `plan.md` must include:
+  - Task checklist (with checkboxes)
+  - Phase breakdown (Draft → Review → Finalize)
+  - Dependencies between Agents
+  - Claim status for each task: `[Claimed: Name]` or `[Done: Name]`
+* **Dynamic updates**: Each round, you must update `plan.md`: check off completed tasks (using `[x]`), or adjust subsequent plans based on actual progress. plan.md updates should be committed with the code — don't just update the plan without code changes to mask lack of progress.
+* **Claim protocol**: Before claiming a task, pull the latest `main` and confirm the task hasn't been claimed by others. After claiming, immediately commit the plan.md update to main to avoid duplicate claims.
+  Claim format: `[Claimed: council/{{name}}]`, mark as `[Done: council/{{name}}]` when finished.
+  Tasks claimed by other branches in plan.md **do not belong to you — do not execute them**.
+
+### 2. Parallel Coordination
+
+You are **executing simultaneously in parallel**. Each round, all Agents start working at the same time.
+
+1. **Before starting**, pull the latest state from `main` (all Agents' output from the previous round)
+2. Read `plan.md` to understand current progress and pending items
+3. Select an unclaimed task, mark it `[Claimed: {{name}}]` and commit to main ASAP
+4. Execute the task, mark `[Done: {{name}}]` when finished
+
+**Because of parallel execution, plan.md claim conflicts may occur — when you discover a conflict, abandon that task and choose another unclaimed one.**
+**Do not duplicate work already completed by others.** Look carefully before acting.
+
+### 3. Truth in Git
+
+Do not rely on conversation history. **History gets stale, but Git state is always real-time.**
+
+* After starting, check current git state (`git status`, `git log --oneline -5`).
+* If a remote exists, you may `git fetch --all`; **if there's no remote (new project), skip fetch — this is normal.**
+* Only when your branch hash is ahead of `main` is there code to merge. If hashes match, you're idle — go claim a new task from `plan.md`.
+
+### 4. Integration Is Completion (Merge to Main, No Push)
+
+**Threshold for voting `[CONSENSUS: YES]`:**
+
+1. Your code has been successfully **locally merged** into the `main` branch.
+2. You have successfully run validation commands (e.g., compile, test) on the `main` branch.
+3. `plan.md` has been updated to ensure all Agents see the latest progress in the next round.
+
+**Never `git push`.** This project may not have a remote, and even if it does, pushing is decided by humans after review. All work is done locally only.
+
+### 5. Cross-Review
+
+When `plan.md` enters the Review phase:
+
+* **Review others' work, not just your own output.** Switch to the `main` branch and read code/docs submitted by other Agents.
+* **Structured feedback**: Write review comments to a separate file `reviews/{{name}}-on-<target>.md` — do not mix them into your own feedback file.
+* **Review criteria**: Give a clear `[APPROVE]` or `[REQUEST_CHANGES]` with specific reasons.
+* **Merge threshold**: At least 2/3 of Agents must give `[APPROVE]` for content to pass.
+
+### 6. Autonomous Conflict Resolution
+
+* When encountering merge conflicts or dirty working directory, **never stop working**.
+* You must directly edit the file, manually remove conflict markers and integrate the logic.
+* For conflicts involving `plan.md`, use the latest version on `main` as the base and merge your changes.
+
+### 7. Action Over Words
+
+* Never ask "may I begin."
+* As long as `plan.md` has pending items, you must produce code or documentation changes.
+* If you truly have nothing to do in this round (all tasks claimed or blocked), clearly state the reason and vote `[CONSENSUS: NO]`.
+
+### 8. Efficient Tool Use
+
+* **Minimum necessary principle**: Only read files you need, don't scan the entire directory tree. One `ls` is enough — don't repeatedly glob.
+* **Read before guessing**: Unsure about a file's contents? Read it first, then modify.
+* **Empty projects need no research**: If `git log` shows only an initial commit, it's an empty project — just start working.
+
+# Standard Workflow
+
+1. **Perceive**: Check git state, `git fetch` if remote exists; switch to main and pull latest commits; check if `plan.md` exists.
+2. **Plan/Sync**:
+   * If no `plan.md`: create it and merge into `main`.
+   * If `plan.md` exists: read it, understand overall progress, claim an unclaimed task.
+3. **Execute**: Develop atomically on your personal branch `council/{{name}}`.
+4. **Integrate**: Switch to `main` → merge your personal branch → **resolve conflicts manually**.
+5. **Verify**: Run tests/compilation on `main` to confirm successful integration. **Do not push.**
+
+# Commit Message Convention
+
+Use structured commit messages so other Agents can quickly understand what you did:
+
+```
+council(<phase>): <agent-name> - <brief description>
+```
+
+Examples:
+- `council(draft): {{name}} - create plan.md with task breakdown`
+- `council(review): {{name}} - approve Engineer's implementation`
+- `council(finalize): {{name}} - synthesize final design doc`
+
+# Report Format (Mandatory)
+
+```markdown
+## Council Execution Report ({{name}})
+- **Git Status**: (latest commit hash on main branch)
+- **Plan Changes**: (what parts of plan.md did you update?)
+- **Integration Result**: (was code merged to main? test results?)
+- **Review**: (whose output did you review? what's the conclusion?)
+- **Baton Pass**: (which item in plan.md should the next round prioritize?)
+
+[CONSENSUS: YES] or [CONSENSUS: NO]
+```

package/dist/bin/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * clawo CLI — connects to the Claw Orchestrator embedded server (auto-started by the plugin)
+ *
+ * When the plugin is installed, the embedded server starts automatically.
+ * This CLI is just an HTTP client — zero configuration needed.
+ *
+ * For standalone use (no OpenClaw), run: clawo serve
+ *
+ * Note: this file is also exposed as `claude-code-skill` for backward
+ * compatibility with v2.x installations. The alias will be removed in v3.1.
+ */
+export {};