Agent Orchestrator

Project Overview

This repository publishes @ralphkrauss/agent-orchestrator, a standalone MCP server for coordinating local Codex and Claude worker CLI runs through a persistent daemon. The 0.3.0 release (issue #63) adds the orchestration_run engine — a daemon-managed state machine that drives short-lived orchestrator / reviewer / compactor turns through a typed action protocol, with persistent state, lifecycle pub/sub, and MCP / IPC / CLI / opt-in HTTP+SSE transports. The supervisor surfaces (agent-orchestrator claude / opencode / supervisor, the supervisor hooks.json, the orchestrators snapshot block, and the register_supervisor IPC family) were removed in this release; see CHANGELOG.md 0.3.0 entry for the migration pointers.

For the orchestration engine: see docs/orchestration.md, docs/workflows.md, docs/orchestration-http-transport.md, and docs/development/orchestration-internals.md.

Build And Test

Use the repository scripts:

pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm verify

pnpm verify is the release-quality check. It builds, runs tests, checks publish readiness, audits production dependencies, resolves the npm dist-tag, and runs an npm pack dry run.

Agents may run pnpm install --frozen-lockfile when dependencies are missing and verification requires them, because the frozen lockfile prevents dependency resolution changes. Do not run other install commands or change dependency ranges unless explicitly asked.

Development Rules

• Read the existing TypeScript, tests, and docs before introducing new patterns.
• Prefer the repository's existing plain TypeScript style and Node built-ins.
• Keep public package behavior stable unless the task is explicitly about an API or contract change.
• Add or update focused tests for daemon lifecycle, run-store persistence, backend invocation, MCP contracts, and release behavior when those areas change.
• Do not commit, push, publish, deprecate npm versions, activate hooks, install packages, change secrets, or write to external services unless explicitly asked.
• Treat uncommitted changes as user-owned unless you made them during the current task.
• Record concrete evidence when claiming that builds, tests, audits, or publish checks passed.

Release Notes

Release process documentation lives in PUBLISHING.md.

• Prereleases publish to the npm next dist-tag.
• Stable releases publish to the npm latest dist-tag.
• GitHub Actions publishes from matching v*.*.* tags.

MCP Tooling

Repository MCP setup is documented in docs/development/mcp-tooling.md.

• GitHub API access is configured through the github MCP server.
• GitHub CLI access is configured through the repo-local gh MCP wrapper.
• Secret-bearing MCP launches go through scripts/mcp-secret-bridge.mjs.
• The bridge resolves GITHUB_TOKEN from a user-level secrets file, process environment, or the local gh auth token result.

Never place real tokens in repo files, MCP config, docs, examples, or command arguments.

AI Workspace

• Shared skills live in .agents/skills/.
• Cross-cutting rules live in .agents/rules/.
• Reusable agent definitions live in .agents/agents/.
• Generated Claude and Cursor projections are produced by scripts/sync-ai-workspace.mjs; edit .agents/ instead.
• Longer workspace documentation lives in docs/ai-workspace.md.

Local Orchestration-Run Debugging

When the user explicitly asks to inspect a local test orchestration_run, read from the daemon's stores rather than guessing from memory.

• Resolve the local test home with node scripts/local-orchestrator-home.mjs or just local-home.
• Orchestration run records live under <local-home>/orchestration_runs/<orchestration_run_id>/ — meta.json, actions.jsonl, handoff.json, pending_inputs.jsonl, children.json, workers.json, groups.json, compactions.jsonl, workflow.json. Prefer daemon MCP tools (get_orchestration_run, list_orchestration_runs, subscribe_orchestration_events) when the daemon is reachable.
• Worker run records live under <local-home>/runs/<run_id>/; prefer daemon MCP tools such as get_run_progress, get_run_events, and get_run_result.
• Keep excerpts minimal. Summarize relevant actions, reviewer verdicts, and worker outcomes; never paste secrets or credentials.

Before Implementing

1. Inspect the affected source, tests, and docs.
2. Identify the narrowest relevant verification command.
3. Load relevant rules from .agents/rules/.
4. Ask before changing release, secret, hook, or external-service behavior.