@kbediako/codex-orchestrator 0.1.12 → 0.1.14-alpha.1

package/skills/delegate-early/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: delegate-early
+description: Spawn subagents early and often to conserve context and parallelize research, review, and planning.
+---
+
+# Delegate Early
+
+Use this skill when a task can be split into parallel streams or when the main context risks ballooning. The top-level Codex remains the lead; subagents are assistants.
+
+## Goals
+- Conserve primary context by offloading research/review/planning.
+- Improve throughput with parallel subagent streams.
+- Capture delegation evidence for auditability.
+
+## When to spawn
+- Before deep reading/analysis to avoid bloating context.
+- When new ambiguity appears or scope changes.
+- For independent streams (research, review, planning, edge cases).
+
+## Task slicing heuristic
+- Identify 2–4 independent streams with minimal shared context.
+- Prefer streams like: `research`, `review`, `spec-check`, `edge-cases`.
+
+## Required conventions
+- Use `MCP_RUNNER_TASK_ID=<task-id>-<stream>` for subagents.
+- Record manifest paths and summarize findings in the main run.
+- Run `node scripts/delegation-guard.mjs` before review handoff to verify delegation evidence.
+
+## Minimal delegation workflow
+1) Name streams and write 1–2 sentence goals for each.
+2) Spawn subagents with clear, bounded prompts.
+3) Wait for subagent completion; retrieve manifest evidence and summarize findings into the main plan.
+4) Proceed with implementation.
+
+## Prompt patterns
+- Research: “Find X, cite Y, return 3 bullets + risks.”
+- Review: “Inspect files A/B for regressions; list issues by severity.”
+- Planning: “Draft a 3–5-step plan, call out unknowns.”
+
+## Escalation rules
+- If delegation is impossible, set `DELEGATION_GUARD_OVERRIDE_REASON` and document it in the task checklist.
+
+## Subagent summary format
+- **Findings**: Key results and conclusions from the subagent run
+- **Risks**: Issues, blockers, or concerns
+- **Open questions**: Unresolved items requiring follow-up
+- **Evidence**: Manifest path (e.g., `.runs/<task-id>-<stream>/cli/<timestamp>/manifest.json`)

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -8,6 +8,7 @@ Use this guide for deeper context on delegation behavior, tool surfaces, and tro
 - It does **not** provide general tools itself; it only exposes `delegate.*` + optional `github.*` tools.
 - Child runs get tools based on `delegate.mode` + `delegate.tool_profile` + repo caps.
 - Delegation MCP stays enabled by default (only MCP on by default); disable it only when required by safety constraints.
+- Collab multi-agent mode is separate from delegation; for symbolic RLM subcalls, set `RLM_SYMBOLIC_COLLAB=1` and ensure a collab-capable Codex CLI. Collab tool calls are recorded in `manifest.collab_tool_calls`. If collab tools are unavailable in your CLI build, skip collab steps; delegation still works independently.
 
 ## Background-run pattern (preferred)
 
@@ -105,12 +106,12 @@ If you need delegation to respect a repo’s `.codex/orchestrator.toml` (e.g., s
 
 ## Version guard (JSONL handshake)
 
-Delegation MCP expects JSONL. Use `codex-orchestrator >= 0.1.8`.
+Delegation MCP expects JSONL. Use `codex-orchestrator` 0.1.12 or newer.
 
 - Check: `codex-orchestrator --version`
-- Update global: `npm i -g @kbediako/codex-orchestrator@0.1.8`
-- Or pin via npx: `npx -y @kbediako/codex-orchestrator@0.1.8 delegate-server`
-- If your installed CLI is behind the docs (e.g., 0.1.11 while docs target a newer release), use the pinned `npx` version or upgrade after the release ships.
+- Update global: `npm i -g @kbediako/codex-orchestrator@0.1.12`
+- Or pin via npx: `npx -y @kbediako/codex-orchestrator@0.1.12 delegate-server`
+- If your installed CLI is behind 0.1.12, prefer upgrading or pinning to the docs’ minimum.
 
 ## Common failures
 

package/skills/delegation-usage/SKILL.md

@@ -9,6 +9,8 @@ description: Use when operating the Codex delegation MCP server and tools (deleg
 
 Use this skill to operate delegation MCP tools with delegation enabled by default (the only MCP on by default). Disable it only when required by safety constraints, and keep other MCPs off unless they are relevant to the task.
 
+Collab multi-agent mode is separate from delegation. For symbolic RLM subcalls that use collab tools, set `RLM_SYMBOLIC_COLLAB=1` and ensure a collab-capable Codex CLI; collab tool calls are recorded in `manifest.collab_tool_calls`. If collab tools are unavailable in your CLI build, skip collab steps; delegation still works independently.
+
 ## Quick-start workflow (canned)
 
 Use this when delegation tools are missing in the current run (MCP disabled) and you want a background Codex run to handle delegation:
@@ -62,11 +64,12 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 
 ### 0a) Version guard (JSONL handshake)
 
-- Delegation MCP uses JSONL; ensure the server binary is **0.1.8+**:
-  - `codex-orchestrator --version` should be `>= 0.1.8`
-- If not, update global install: `npm i -g @kbediako/codex-orchestrator@0.1.8`
-- Alternative: pin the MCP server to `npx -y @kbediako/codex-orchestrator@0.1.8` for deterministic behavior.
-- Note: if your installed CLI is older than the docs (e.g., 0.1.11 while docs target a newer release), use the pinned `npx` version or upgrade after the release ships.
+- Delegation MCP uses JSONL; ensure the server binary meets the docs’ minimum version (0.1.12):
+  - `codex-orchestrator --version` should be `>= 0.1.12`.
+- If not, update global install: `npm i -g @kbediako/codex-orchestrator@0.1.12`
+- Alternative: pin the MCP server to `npx -y @kbediako/codex-orchestrator@0.1.12` for deterministic behavior.
+- Note: if your installed CLI is older than 0.1.12, prefer upgrading or pinning to the docs’ minimum.
+- Keep the version pins in this section in sync with the docs’ minimum (currently 0.1.12).
 
 ### 0b) Background terminal bootstrap (required when MCP is disabled)
 
@@ -83,6 +86,7 @@ Guidance for background runs:
 - Use `--json` for JSONL events, or `-o <path>` to write the final message to a file while still printing to stdout.
 - If you need a multi-step run, use `codex exec resume --last "<follow-up>"` to continue the same session.
 - Non-interactive runs can still hit `confirmation_required`; approvals happen via the UI/TUI and the run resumes after approval.
+- Use this only for non-manifest evidence; for manifest-required workflows, use `codex-orchestrator start ...`.
 - `codex exec` does **not** create an orchestrator manifest. If the child must call `delegate.question.*` or `delegate.status/pause/cancel`, pass a real `.runs/<task>/cli/<run>/manifest.json` via `parent_manifest_path`/`manifest_path` (e.g., run `codex-orch start diagnostics --format json --task <task-id>` to get one; or use `export MCP_RUNNER_TASK_ID=<task-id>` if you prefer env vars).
 - Setting `MCP_RUNNER_TASK_ID` does not cause `codex exec` to emit `.runs/**` manifests; use `codex-orchestrator start <pipeline> --task <id>` when manifest evidence is required.
 
@@ -106,6 +110,7 @@ Guidance for background runs:
   - If the repo omits `delegate.allowed_tool_servers`, the cap defaults to `[]` and extra tools are ignored.
   - Names must match `^[A-Za-z0-9_-]+$`; invalid entries (e.g., `;`, `/`, `\n`, `=`) are ignored.
   - `github.*` tools are not gated by `delegate.tool_profile`; they are controlled by repo GitHub allowlists.
+- If the child cannot access expected tools, recheck repo `delegate.allowed_tool_servers` (it may have changed).
 - Keep `delegate.tool_profile` minimal; avoid networked tools unless required.
 - Nested delegation is off by default; only use `full` when `delegate.allow_nested=true` and you intend recursion.
 - **Important:** `delegate.mode` (server tool surface) is different from `delegate_mode` (input to `delegate.spawn` for the *child* run).
@@ -153,6 +158,7 @@ repeat:
 
 - **Long waits:** `wait_ms` never blocks longer than 10s per call; use polling.
 - **Long-running delegate.spawn:** Prefer `start_only=true` (default) to avoid tool-call timeouts. If you must use `start_only=false`, keep runs short or run long jobs outside delegation (no question queue).
+- **Cloud run branch mismatch:** cloud-mode orchestration against a local-only branch can fail with `couldn't find remote ref ...`; set `CODEX_CLOUD_BRANCH` to a pushed branch (typically `main`) before cloud execution.
 - **Tool profile mismatch:** child tool profile must be allowed by repo policy; invalid or unsafe names are ignored.
 - **Confirmation misuse:** never pass `confirm_nonce` from model/tool input; it is runner‑injected only.
 - **Secrets exposure:** never include secrets/tokens/PII in delegate prompts or files.

package/skills/docs-first/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-first
-description: Use when a task requires a spec-driven workflow: draft/refresh PRD + TECH_SPEC + ACTION_PLAN + tasks, link TECH_SPEC in tasks/index.json, and run docs-review before implementation.
+description: "Use when a task requires a spec-driven workflow: draft/refresh PRD + TECH_SPEC + ACTION_PLAN + tasks, link TECH_SPEC in tasks/index.json, and run docs-review before implementation."
 ---
 
 # Docs-First (Spec-Driven)
@@ -25,6 +25,7 @@ Use this skill when a task needs a spec-driven workflow. The objective is to cre
 
 3) Run docs-review before implementation
 - `npx codex-orchestrator start docs-review --format json --no-interactive --task <task-id>`
+- If running in cloud mode, ensure the branch exists on remote. For local-only branches, set `CODEX_CLOUD_BRANCH=main` (or another pushed branch).
 - Link the manifest path in the checklists.
 
 4) Implement and validate

package/templates/README.md

@@ -10,3 +10,7 @@ initializer:
 
 The initializer copies the contents of templates/codex/ into your working
 repository and will not overwrite files unless you pass --force.
+
+Next steps (recommended):
+  codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
+  codex-orchestrator codex setup   # optional: CO-managed Codex CLI for collab JSONL