@kbediako/codex-orchestrator 0.1.9 → 0.1.11

package/README.md

@@ -8,44 +8,66 @@ Codex Orchestrator is the CLI + runtime that coordinates Codex-driven runs, pipe
   ```bash
   npm i -g @kbediako/codex-orchestrator
   ```
+- After install, use either `codex-orchestrator` or the short alias `codex-orch`:
+  ```bash
+  codex-orchestrator --version
+  ```
 - Or run via npx:
   ```bash
-  npx codex-orchestrator --version
+  npx @kbediako/codex-orchestrator --version
   ```
 
 Node.js >= 20 is required.
 
 ## Quick start
 
-1. Set a task id so artifacts land under `.runs/<task-id>/`:
+1. Run a pipeline with a task id so artifacts are grouped under `.runs/<task-id>/`:
    ```bash
-   export MCP_RUNNER_TASK_ID=<task-id>
+   codex-orch start diagnostics --format json --task <task-id>
    ```
-2. Run a pipeline:
+   The command prints the `run_id` plus the manifest path under `.runs/<task-id>/cli/<run-id>/manifest.json`.
+2. Watch status:
    ```bash
-   npx codex-orchestrator start diagnostics --format json
+   codex-orch status --run <run-id> --watch --interval 10
    ```
-3. Watch status:
+3. Resume if needed:
    ```bash
-   npx codex-orchestrator status --run <run-id> --watch --interval 10
-   ```
-4. Resume if needed:
-   ```bash
-   npx codex-orchestrator resume --run <run-id>
+   codex-orch resume --run <run-id>
    ```
+   > Tip: if you prefer `npx`, replace `codex-orch` with `npx @kbediako/codex-orchestrator`.
+   > Tip: for multiple commands, you can also `export MCP_RUNNER_TASK_ID=<task-id>` once.
 
 ## Delegation MCP server
 
 Run the delegation MCP server over stdio:
 ```bash
-codex-orchestrator delegate-server --repo /path/to/repo --mode question_only
+codex-orchestrator delegate-server --repo /path/to/repo
 ```
+Optional: add `--mode question_only` to disable `delegate.spawn/pause/cancel`, keeping only `delegate.question.*` + `delegate.status` in the delegate namespace. GitHub tools remain available when GitHub integration is enabled.
 
 Register it with Codex once, then enable per run:
 ```bash
-codex mcp add delegation -- codex-orchestrator delegation-server --repo /path/to/repo
+codex mcp add delegation -- codex-orchestrator delegate-server --repo /path/to/repo
 codex -c 'mcp_servers.delegation.enabled=true' ...
 ```
+`delegate-server` is the canonical name; `delegation-server` is supported as an alias (older docs may use it).
+
+## Delegation flow
+
+```mermaid
+flowchart LR
+  A["Parent Codex run\n(MCP disabled by default)"]
+  B["Background Codex run\n(delegation enabled)"]
+  C["Delegation MCP server"]
+  D["delegate.spawn"]
+  E["Child run"]
+  F["delegate.question.enqueue / poll\n(optional back to parent)"]
+  G["Artifacts\n.runs/<task-id>/cli/<run-id>/manifest.json"]
+
+  A --> B --> C --> D --> E
+  E -. optional .-> F -.-> A
+  E --> G
+```
 
 ## Skills (bundled)
 
@@ -58,7 +80,7 @@ Options:
 - `--force` overwrites existing files.
 - `--codex-home <path>` targets a different Codex home directory.
 
-Current bundled skills:
+Bundled skills (may vary by release):
 - `delegation-usage`
 
 ## DevTools readiness
@@ -90,5 +112,5 @@ codex-orchestrator devtools setup
 
 ## Repository + contributor guide
 
-Repo internals, development workflows, and deeper architecture notes live here:
+Repo internals, development workflows, and deeper architecture notes live in the GitHub repository:
 - `docs/README.md`

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
-    "codex-orchestrator": "dist/bin/codex-orchestrator.js"
+    "codex-orchestrator": "dist/bin/codex-orchestrator.js",
+    "codex-orch": "dist/bin/codex-orchestrator.js"
   },
   "files": [
     "dist/bin/**",

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -4,7 +4,7 @@ Use this guide for deeper context on delegation behavior, tool surfaces, and tro
 
 ## Mental model
 
-- The delegation MCP server is a local stdio process (`codex-orchestrator delegation-server`).
+- The delegation MCP server is a local stdio process (`codex-orchestrator delegate-server`; `delegation-server` is an alias).
 - 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.
 
@@ -25,6 +25,17 @@ Notes:
 - If the run needs `delegate.spawn/pause/cancel`, add `-c 'delegate.mode=full'`.
 - If it only needs `delegate.question.*` (and optional `delegate.status`), add `-c 'delegate.mode=question_only'`.
 - Non-interactive runs can still require approvals; resolve them via the UI/TUI and the run will resume.
+- `codex exec` does **not** create `.runs/<task>/cli/<run>/manifest.json` on its own. If the child must call `delegate.question.*` or `delegate.status/pause/cancel`, pass a real manifest path (e.g., run `codex-orch start diagnostics --format json --task <task-id>` and reuse the manifest path; or `export MCP_RUNNER_TASK_ID=<task-id>` if you prefer env vars).
+
+## Runner + task id (short form)
+
+Prefer a direct task flag instead of an exported env var:
+
+```
+codex-orch start diagnostics --format json --task <task-id>
+```
+
+This produces `.runs/<task-id>/cli/<run-id>/manifest.json`, which you can reuse as `parent_manifest_path` for question queue calls.
 
 ## Minimal tool surface
 
@@ -43,7 +54,7 @@ Delegation MCP expects JSONL. Use `codex-orchestrator >= 0.1.8`.
 
 - 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 delegation-server`
+- Or pin via npx: `npx -y @kbediako/codex-orchestrator@0.1.8 delegate-server`
 
 ## Common failures
 

package/skills/delegation-usage/SKILL.md

@@ -26,6 +26,7 @@ Optional (only if you need it):
 - Add `-c 'delegate.mode=full'` when the child needs `delegate.spawn/pause/cancel` (nested delegation / run control).
 
 For deeper background patterns and troubleshooting, see `DELEGATION_GUIDE.md`.
+For runner + delegation coordination (short `--task` flow), see `docs/delegation-runner-workflow.md`.
 
 ## Delegation‑first policy
 
@@ -41,8 +42,9 @@ For deeper background patterns and troubleshooting, see `DELEGATION_GUIDE.md`.
 ### 0) One-time setup (register the MCP server)
 
 - Register the delegation server once:
-  - `codex mcp add delegation -- codex-orchestrator delegation-server`
+  - `codex mcp add delegation -- codex-orchestrator delegate-server`
   - Optional (recommended for repo-scoped config): append `--repo /path/to/repo` to the args.
+  - `delegate-server` is the canonical name; `delegation-server` is supported as an alias.
 - Per-run `-c 'mcp_servers.delegation.enabled=true'` only works **after** registration.
 - If `delegate.*` tools are missing mid-task, start a new run with:
   - `codex -c 'mcp_servers.delegation.enabled=true' ...`
@@ -74,6 +76,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.
+- `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).
 
 ### 1) Enable delegation only for the run you need
 
@@ -81,6 +84,7 @@ Guidance for background runs:
 - Enable per run:
   - Example: `codex -c 'mcp_servers.delegation.enabled=true' ...`
 - Using `-c` keeps your default config unchanged, so delegation is off again next run.
+- Prefer `codex-orch start <pipeline> --format json --task <task-id>` over `export MCP_RUNNER_TASK_ID=...` for a shorter, explicit task id.
 
 ### 2) Spawn a delegate run (delegate.spawn)