@kbediako/codex-orchestrator 0.1.19 → 0.1.21

package/README.md

@@ -137,14 +137,17 @@ codex-orchestrator skills install
 
 Options:
 - `--force` overwrites existing files.
+- `--only <skills>` installs only selected skills (comma-separated). Combine with `--force` to overwrite only those.
 - `--codex-home <path>` targets a different Codex home directory.
 
 Bundled skills (may vary by release):
+- `collab-subagents-first`
 - `delegation-usage`
 - `standalone-review`
 - `docs-first`
 - `collab-evals`
 - `collab-deliberation`
+- `release`
 - `delegate-early` (compatibility alias; use `delegation-usage`)
 
 ## DevTools readiness

package/dist/bin/codex-orchestrator.js

@@ -605,7 +605,15 @@ async function handleSkills(rawArgs) {
             const format = flags['format'] === 'json' ? 'json' : 'text';
             const force = flags['force'] === true;
             const codexHome = readStringFlag(flags, 'codex-home');
-            const result = await installSkills({ force, codexHome });
+            const onlyRaw = flags['only'];
+            let only;
+            if (onlyRaw !== undefined) {
+                if (typeof onlyRaw !== 'string') {
+                    throw new Error('--only requires a comma-separated list of skill names.');
+                }
+                only = onlyRaw.split(',').map((entry) => entry.trim()).filter(Boolean);
+            }
+            const result = await installSkills({ force, codexHome, only });
             if (format === 'json') {
                 console.log(JSON.stringify(result, null, 2));
             }
@@ -946,6 +954,7 @@ Commands:
     --format json         Emit machine-readable output (dry-run only).
   skills install          Install bundled skills into $CODEX_HOME/skills.
     --force               Overwrite existing skill files.
+    --only <skills>       Install only selected skills (comma-separated).
     --codex-home <path>   Override the target Codex home directory.
     --format json         Emit machine-readable output.
   mcp serve [--repo <path>] [--dry-run] [-- <extra args>]
@@ -972,6 +981,7 @@ function printSkillsHelp() {
 Commands:
   install                   Install bundled skills into $CODEX_HOME/skills.
     --force                 Overwrite existing skill files.
+    --only <skills>         Install only selected skills (comma-separated).
     --codex-home <path>     Override the target Codex home directory.
     --format json           Emit machine-readable output.
 `);

package/dist/orchestrator/src/cli/skills.js

@@ -12,18 +12,28 @@ export async function installSkills(options = {}) {
     const targetRoot = join(codexHome, 'skills');
     const written = [];
     const skipped = [];
-    const skillNames = await listSkillNames(sourceRoot);
-    await copyDir(sourceRoot, targetRoot, {
+    const availableSkills = await listSkillNames(sourceRoot);
+    const selectedSkills = resolveSelectedSkills(availableSkills, options.only);
+    const copyOptions = {
         force: options.force ?? false,
         written,
         skipped
-    });
+    };
+    if (selectedSkills.length === availableSkills.length) {
+        await copyDir(sourceRoot, targetRoot, copyOptions);
+    }
+    else {
+        await mkdir(targetRoot, { recursive: true });
+        for (const skill of selectedSkills) {
+            await copyDir(join(sourceRoot, skill), join(targetRoot, skill), copyOptions);
+        }
+    }
     return {
         written,
         skipped,
         sourceRoot,
         targetRoot,
-        skills: skillNames
+        skills: selectedSkills
     };
 }
 export function formatSkillsInstallSummary(result, cwd = process.cwd()) {
@@ -61,6 +71,22 @@ async function listSkillNames(sourceRoot) {
     const entries = await readdir(sourceRoot, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
+function resolveSelectedSkills(availableSkills, only) {
+    if (!only) {
+        return availableSkills;
+    }
+    const trimmed = only.map((entry) => entry.trim()).filter(Boolean);
+    if (trimmed.length === 0) {
+        throw new Error('No skills specified for --only.');
+    }
+    const requested = Array.from(new Set(trimmed));
+    const available = new Set(availableSkills);
+    const unknown = requested.filter((skill) => !available.has(skill));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown skill(s): ${unknown.join(', ')}. Available skills: ${availableSkills.join(', ')}`);
+    }
+    return requested;
+}
 async function assertDirectory(path) {
     const info = await stat(path).catch(() => null);
     if (!info || !info.isDirectory()) {

package/docs/README.md

@@ -103,7 +103,7 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json` and `AGENTS.md`; no overwrite unless `--force`).
 - `codex-orchestrator doctor [--format json]`: check optional tooling dependencies and print install commands.
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
-- `codex-orchestrator skills install [--force] [--codex-home <path>]`: install bundled skills into `$CODEX_HOME/skills` (global skills remain the primary reference when installed).
+- `codex-orchestrator skills install [--force] [--only <skills>] [--codex-home <path>]`: install bundled skills into `$CODEX_HOME/skills` (global skills remain the primary reference when installed).
 - `codex-orchestrator self-check --format json`: emit a safe JSON health payload for smoke tests.
 - `codex-orchestrator --version`: print the package version.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/collab-subagents-first/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: collab-subagents-first
+description: Manage non-trivial tasks via focused collab subagents to save context and improve throughput. Use when work spans multiple files/components, can be split into independent streams, needs separate validation/review, or risks context bloat. Favor direct execution for trivial one-shot tasks.
+---
+
+# Collab Subagents First
+
+## Overview
+
+Delegate as a manager, not as a pass-through. Split work into narrow streams, give each subagent a rich brief, and keep parent context lean by collecting short structured summaries plus evidence paths.
+
+Note: If a global `collab-subagents-first` skill is installed, prefer that and fall back to this bundled skill.
+
+## Delegation gate
+
+Use subagents when any condition is true:
+- Task spans more than one subsystem or more than one file.
+- Work naturally splits into independent streams (for example research + implementation + verification).
+- Work likely exceeds about 5-10 minutes.
+- Separate review/verification is required before handoff.
+- Parent context is growing and summary compression is needed.
+- You are unsure whether the task should be delegated.
+
+Default rule:
+- For any non-trivial task, spawn at least one subagent early (even if work is mostly single-stream) to offload execution and preserve parent context.
+
+Skip subagents when all conditions are true:
+- Single-file or tightly scoped change.
+- No parallelizable stream exists.
+- Execution and verification are straightforward in one pass.
+- Expected duration is under about 5 minutes.
+
+## Workflow
+
+1) Define parent success criteria
+- Write 3-6 acceptance bullets before spawning.
+- Define "done" and required validation upfront.
+
+2) Choose delegation shape
+- Minimum for non-trivial work: 1 subagent (`implement` or `research`).
+- Standard: 2 subagents (`implement` + `review/verify`).
+- Complex/high-risk: 3-4 subagents (`research`, `implement`, `tests`, `review`).
+- If uncertain, spawn a short-lived `scout` subagent first to propose decomposition and risks.
+
+3) Split into narrow streams
+- Prefer 1-4 streams based on the chosen shape.
+- Assign one owner per stream and avoid overlapping file ownership.
+- Good stream labels: `research`, `implement`, `tests`, `review`.
+
+4) Send a rich brief to each subagent
+- Use the required brief template from `references/subagent-brief-template.md`.
+- Include objective, scope, constraints, acceptance criteria, and expected output format.
+- Require concise summaries and evidence paths; avoid long logs in chat.
+
+5) Run streams in parallel when independent
+- Spawn multiple subagents for independent streams.
+- Wait for all subagents to finish before final synthesis.
+
+6) Synthesize with context compression
+- Merge only decisions, findings, and evidence links into parent context.
+- Keep full details in artifacts/files instead of long conversation dumps.
+- Force summary discipline: keep each subagent synthesis to a short block with outcome, files, validation, findings, and open questions only.
+
+7) Verify before handoff
+- Run parent-level validation/tests.
+- Run standalone review on merged changes (see review loop below).
+
+8) Re-check delegation need at checkpoints
+- Re-evaluate delegation after major context growth (for example every 6-8 parent messages, or after crossing about 8 touched files, or when the plan changes materially).
+- If parent context starts bloating, spawn/redirect subagents instead of continuing in parent.
+- Keep the delegation tree shallow. Prefer parent fan-out over subagent-of-subagent chains.
+
+## Spawn payload + labels (current behavior)
+
+- `spawn_agent` accepts exactly one input style:
+  - `message` (plain text), or
+  - `items` (structured input).
+- Do not send both `message` and `items` in one spawn call.
+- Use `items` when you need explicit structured context (for example `mention` paths like `app://...` or selected `skill` entries) instead of flattening everything into one long string.
+- Spawn returns an `agent_id` (thread id). Collab event rendering/picker labels are id-based today; do not depend on custom visible agent names.
+- To keep operator readability high despite id labels, encode the role clearly in your stream labels and first-line task brief (for example `review`, `tests`, `research`).
+
+## Collab lifecycle hygiene (required)
+
+When you use collab tools (`spawn_agent` / `wait` / `close_agent`):
+- Keep a local list of every returned `agent_id`.
+- For every successful `spawn_agent`, run `wait` and then `close_agent` for that same id.
+- Always close agents on error/timeout paths; do a final cleanup pass before finishing so no id is left unclosed.
+- If spawn fails with `agent thread limit reached`, stop spawning immediately, close any known ids, then retry once. If you still cannot spawn, proceed without collab (solo or via delegation) and explicitly note the degraded mode.
+
+## Required subagent contract
+
+Require each subagent response to include:
+- `Outcome`: done / blocked / partial.
+- `Changes`: files touched or "none".
+- `Validation`: commands run and pass/fail results.
+- `Findings`: prioritized defects/risks (or "none found").
+- `Evidence`: artifact paths, manifests, or command outputs summary.
+- `Open questions`: only unresolved items that block correctness.
+
+Reject and rerun when responses are:
+- Missing validation evidence for code changes.
+- Missing ownership/scope boundaries.
+- Excessively verbose with no actionable summary.
+
+## Execution constraints for subagents
+
+- Subagents are spawned with approval policy effectively set to `never`.
+- Design subagent tasks so they can complete without approval/escalation prompts.
+- Keep privileged/high-risk operations in the parent thread when interactive approval is required.
+- Subagents inherit core execution context (for example cwd/sandbox constraints), so include environment assumptions explicitly in each brief.
+
+## Review loop (standalone-review pairing)
+
+Use a two-layer review loop:
+
+1) Subagent self-review (when possible)
+- If `codex review` is available in the working repo, have the subagent run the repo's standalone-review flow (including hardened fallback rules) for:
+  - `--uncommitted`, or
+  - `--base <branch>` when branch comparison is clearer.
+- Capture top findings and fixes in the subagent summary.
+- If self-review cannot run (tool/policy/trust constraints), require a manual checklist summary: correctness, regressions, missing tests.
+
+2) Parent independent review (required)
+- After integrating subagent work, run a standalone review from the parent.
+- Prefer the global `standalone-review` skill workflow for consistent checks.
+
+Do not treat wrapper handoff-only output as a completed review.
+
+## Orchestrator + RLM path (optional, recommended for deep loops)
+
+- Prefer orchestrator RLM/delegation loops for long-horizon, recursive, or high-risk tasks when available.
+- Keep this additive: still perform final parent synthesis and standalone review.
+- If orchestrator is unavailable, continue with local subagent orchestration and standalone review.
+
+## Compatibility guardrail (JSONL/collab drift)
+
+- Symptoms: missing collab/delegate tool-call evidence, framing/parsing errors, or unstable collab behavior after CLI upgrades.
+- Check versions first: `codex --version` and `codex-orchestrator --version`.
+- CO repo refresh path (safe default): `scripts/codex-cli-refresh.sh --repo <codex-repo> --no-push`.
+- Rebuild managed CLI only: `codex-orchestrator codex setup --source <codex-repo> --yes --force`.
+- If local codex is materially behind upstream, sync before diagnosing collab behavior differences.
+- If compatibility remains unstable, continue with non-collab execution path and document the degraded mode.
+
+## Depth-limit guardrail
+
+- Collab spawn depth is bounded. At max depth, `spawn_agent` will fail and the branch must execute directly.
+- Near max depth, collab may be disabled for newly spawned children; plan for leaf execution.
+- When depth errors appear, stop recursive delegation and switch to parent-driven execution.
+
+## Anti-patterns
+
+- Do not delegate one giant stream with vague ownership.
+- Do not spawn subagents before acceptance criteria are defined.
+- Do not merge subagent output without independent validation.
+- Do not copy raw multi-hundred-line logs into parent context.
+- Do not keep long single-agent execution in parent when a focused subagent can own it.
+- Do not skip delegation solely because there is only one implementation stream; single-stream delegation is valid for context offload.
+- Do not rely on human-readable agent names in TUI labels for control flow; use stream ownership and evidence paths as source of truth.
+- Do not end the parent work with unclosed collab agent ids.
+
+## Completion checklist
+
+- At least one subagent was used for non-trivial work (or explicit reason documented for skipping).
+- Streams defined with clear ownership and acceptance criteria.
+- Subagent briefs include complete context and constraints.
+- All subagents completed or explicitly closed as blocked.
+- Parent synthesis includes concise decisions and evidence paths.
+- Parent-level review completed (standalone review or equivalent).
+- Collab lifecycle closed (`spawn_agent` -> `wait` -> `close_agent` per id) or degraded mode explicitly recorded.

package/skills/collab-subagents-first/references/subagent-brief-template.md

@@ -0,0 +1,90 @@
+# Subagent Brief Template
+
+Use this template when spawning or re-scoping a subagent. Fill every field.
+
+## Template
+
+```text
+You are assigned a focused subtask. You are not alone in the codebase; other agents may edit unrelated files. Ignore unrelated edits and do not revert work you do not own.
+
+Task label:
+Objective:
+Timebox:
+Working repo/path:
+Base branch / comparison scope:
+
+Why this matters:
+- <1-3 bullets of product/technical context>
+
+Known context digest:
+- <current branch / relevant files / recent decisions>
+- <known runtime/tooling quirks in this repo>
+- <links/paths to specs, tasks, notes, or manifests>
+
+In scope:
+- <exact responsibilities>
+
+Out of scope:
+- <explicit exclusions>
+
+Ownership:
+- Files/paths you may edit: <paths>
+- Files/paths you must not edit: <paths>
+
+Acceptance criteria:
+- <bullet 1>
+- <bullet 2>
+- <bullet 3>
+
+Validation required:
+- Commands to run: <commands>
+- Minimum checks: <tests/lint/build/review expectations>
+
+Review:
+- If available, run the repo's standalone-review flow on your changes before final response (`--uncommitted` or `--base <branch>` as appropriate).
+- If review cannot run, provide a manual self-review for correctness, regressions, and missing tests.
+
+Output format (required):
+1. Outcome: done | partial | blocked
+2. Changes: <file list + short summary>
+3. Validation: <command> -> <pass/fail>
+4. Findings: <prioritized issues/risks, or "none found">
+5. Evidence: <paths/log references>
+6. Open questions: <only blockers>
+
+Keep the response concise. Put detailed notes in a file and return the path.
+```
+
+## Brief quality bar (required)
+
+- Include enough context so the subagent can act without back-and-forth.
+- Include explicit file ownership boundaries.
+- Include a concrete output format and validation expectations.
+- Include at least one "do not do" constraint to prevent drift.
+- If task is review-only, explicitly prohibit implementation edits.
+
+## Fast variants
+
+### Research stream
+
+```text
+Objective: answer <question> with evidence.
+Deliverable: 3-7 bullets + key risks + recommendation.
+No code edits unless explicitly requested.
+```
+
+### Implementation stream
+
+```text
+Objective: implement <specific change>.
+Deliverable: patch + validation output + self-review notes.
+```
+
+### Verification stream
+
+```text
+Objective: validate <existing change>.
+Deliverable: failing/passing checks, defect list by severity, and minimal fix suggestions.
+No broad refactors.
+```
+

package/skills/release/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: release
+description: Ship a signed tag + GitHub Release + npm publish for @kbediako/codex-orchestrator with low-friction, agent-first steps (PR -> watch-merge -> tag -> watch publish -> downstream smoke).
+---
+
+# Release (CO Maintainer)
+
+Use this skill when the user asks to ship a new CO version to npm/downstream users.
+If a global `release` skill is installed, prefer that and fall back to this bundled skill.
+
+## Guardrails (required)
+
+- Never publish from an unmerged branch: release tags must point at `main`.
+- Release tags must be **signed annotated tags** (`git tag -s vX.Y.Z -m "vX.Y.Z"`).
+- Confirm `gh auth status` is OK before any PR/release steps.
+- Prefer non-interactive commands; avoid anything that can hang on prompts.
+- If any check fails (Core Lane, Cloud Canary, CodeRabbit, release workflow), stop and fix before proceeding.
+
+## Workflow
+
+### 1) Preflight
+
+```bash
+gh auth status -h github.com
+git status -sb
+git checkout main
+git pull --ff-only
+```
+
+### 2) Version bump PR
+
+Pick a version (usually patch): `0.1.N+1`.
+
+```bash
+VERSION="0.1.20"
+BRANCH="task/release-${VERSION}"
+
+git checkout -b "$BRANCH"
+npm version "$VERSION" --no-git-tag-version
+git add package.json package-lock.json
+git commit -m "chore(release): bump version to ${VERSION}"
+git push -u origin "$BRANCH"
+```
+
+Open PR (use `--body-file` to avoid literal `\\n` rendering):
+
+```bash
+cat <<EOF > /tmp/pr-body.md
+## What
+- Bump version to ${VERSION}.
+
+## Why
+- Ship latest main to npm/downstream users.
+
+## How Tested
+- CI on this PR (Core Lane / Cloud Canary / CodeRabbit).
+EOF
+
+gh pr create --title "chore(release): bump version to ${VERSION}" --body-file /tmp/pr-body.md
+```
+
+Monitor + auto-merge once green:
+
+```bash
+PR_NUMBER="$(gh pr view --json number --jq .number)"
+codex-orchestrator pr watch-merge --pr "$PR_NUMBER" --auto-merge --delete-branch --quiet-minutes 1 --interval-seconds 20
+```
+
+### 3) Create signed tag + push
+
+```bash
+git checkout main
+git pull --ff-only
+
+TAG="v${VERSION}"
+git tag -s "$TAG" -m "$TAG"
+git tag -v "$TAG"
+git push origin "$TAG"
+```
+
+### 4) Watch the release workflow + confirm npm publish
+
+```bash
+TAG_SHA="$(git rev-list -n 1 "$TAG")"
+RUN_ID=""
+for i in {1..30}; do
+  RUN_ID="$(
+    gh run list \
+      --workflow release.yml \
+      --limit 20 \
+      --json databaseId,headBranch,headSha \
+      --jq ".[] | select((.headBranch==\"${TAG}\") or (.headSha==\"${TAG_SHA}\")) | .databaseId" \
+      | head -n 1 \
+      || true
+  )"
+  if [[ -n "$RUN_ID" && "$RUN_ID" != "null" ]]; then
+    break
+  fi
+  sleep 2
+done
+if [[ -z "$RUN_ID" || "$RUN_ID" == "null" ]]; then
+  echo "::error::No release workflow run found for ${TAG}."
+  exit 1
+fi
+gh run watch "$RUN_ID" --exit-status
+
+npm view @kbediako/codex-orchestrator version
+gh release view "v${VERSION}" --json url,assets --jq '{url: .url, assets: (.assets|map(.name))}'
+```
+
+### 5) Update global + downstream smoke
+
+```bash
+npm i -g @kbediako/codex-orchestrator@"${VERSION}"
+codex-orchestrator --version
+
+TMPDIR="$(mktemp -d)"
+cd "$TMPDIR"
+npx -y @kbediako/codex-orchestrator@"${VERSION}" --version
+npx -y @kbediako/codex-orchestrator@"${VERSION}" pr watch-merge --help | head -n 10
+```
+
+If the release included bundled skill changes, refresh local skills:
+
+```bash
+codex-orchestrator skills install --force
+```