@kbediako/codex-orchestrator 0.1.23 → 0.1.25

package/README.md

@@ -130,6 +130,11 @@ flowchart TB
 
 ## Skills (bundled)
 
+Recommended one-shot bootstrap (skills + delegation + DevTools wiring):
+```bash
+codex-orchestrator setup --yes
+```
+
 The release ships skills under `skills/` for downstream packaging. If you already have global skills installed, treat those as the primary reference and use bundled skills as the shipped fallback. Install bundled skills into `$CODEX_HOME/skills`:
 ```bash
 codex-orchestrator skills install
@@ -142,6 +147,7 @@ Options:
 
 Bundled skills (may vary by release):
 - `collab-subagents-first`
+- `chrome-devtools`
 - `delegation-usage`
 - `standalone-review`
 - `docs-first`
@@ -157,11 +163,24 @@ Check readiness (deps + capability wiring):
 codex-orchestrator doctor --format json
 ```
 
+Auto-fix wiring (delegation + DevTools):
+```bash
+codex-orchestrator doctor --apply --yes
+```
+
 Usage snapshot (scans local `.runs/`):
 ```bash
 codex-orchestrator doctor --usage
 ```
 
+## Downstream usage cheatsheet (agent-first)
+
+- Bootstrap + wire everything: `codex-orchestrator setup --yes`
+- Validate + measure adoption locally: `codex-orchestrator doctor --usage --format json`
+- Delegation: `codex-orchestrator doctor --apply --yes`, then enable for a Codex run with: `codex -c 'mcp_servers.delegation.enabled=true' ...`
+- Collab (symbolic RLM subagents): `codex-orchestrator rlm "<goal>" --collab auto` (requires collab feature enabled in Codex)
+- Cloud: set `CODEX_CLOUD_ENV_ID` (and optional `CODEX_CLOUD_BRANCH`), then run: `codex-orchestrator start <pipeline> --cloud --target <stage-id>`
+
 Print DevTools MCP setup guidance:
 ```bash
 codex-orchestrator devtools setup
@@ -173,6 +192,7 @@ codex-orchestrator devtools setup
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
 - `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`) into a repo.
+- `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring.
 - `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time).
 - `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
 - `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (optional managed/pinned path; use `--download-url` + `--download-sha256` for prebuilts).

package/dist/bin/codex-orchestrator.js

@@ -18,7 +18,7 @@ import { formatDoctorUsageSummary, runDoctorUsage } from '../orchestrator/src/cl
 import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
 import { formatCodexCliSetupSummary, runCodexCliSetup } from '../orchestrator/src/cli/codexCliSetup.js';
 import { formatDelegationSetupSummary, runDelegationSetup } from '../orchestrator/src/cli/delegationSetup.js';
-import { formatSkillsInstallSummary, installSkills } from '../orchestrator/src/cli/skills.js';
+import { formatSkillsInstallSummary, installSkills, listBundledSkills } from '../orchestrator/src/cli/skills.js';
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
 import { serveMcp } from '../orchestrator/src/cli/mcp.js';
@@ -65,6 +65,9 @@ async function main() {
             case 'init':
                 await handleInit(args);
                 break;
+            case 'setup':
+                await handleSetup(args);
+                break;
             case 'doctor':
                 await handleDoctor(args);
                 break;
@@ -556,10 +559,106 @@ async function handleInit(rawArgs) {
         }
     }
 }
+async function handleSetup(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        console.log(`Usage: codex-orchestrator setup [--yes] [--format json]
+
+One-shot bootstrap for downstream users. Installs bundled skills and configures
+delegation + DevTools MCP wiring.
+
+Options:
+  --yes                 Apply setup (otherwise plan only).
+  --repo <path>         Repo root for delegation wiring (default cwd).
+  --format json         Emit machine-readable output (dry-run only).
+`);
+        return;
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    if (format === 'json' && apply) {
+        throw new Error('setup does not support --format json with --yes.');
+    }
+    const repoFlag = readStringFlag(flags, 'repo');
+    const repoRoot = repoFlag ?? process.cwd();
+    const repoFlagValue = repoFlag ? (/\s/u.test(repoFlag) ? JSON.stringify(repoFlag) : repoFlag) : null;
+    const delegationRepoArg = repoFlagValue ? ` --repo ${repoFlagValue}` : '';
+    const bundledSkills = await listBundledSkills();
+    if (bundledSkills.length === 0) {
+        throw new Error('No bundled skills detected; cannot run setup.');
+    }
+    const forceSkills = bundledSkills.filter((skill) => skill !== 'chrome-devtools');
+    if (!apply) {
+        const forceOnly = forceSkills.join(',');
+        const forceCommand = forceOnly ? `codex-orchestrator skills install --force --only ${forceOnly}` : null;
+        const devtoolsCommand = bundledSkills.includes('chrome-devtools')
+            ? 'codex-orchestrator skills install --only chrome-devtools'
+            : null;
+        const delegation = await runDelegationSetup({ repoRoot });
+        const devtools = await runDevtoolsSetup();
+        const payload = {
+            status: 'planned',
+            steps: {
+                skills: {
+                    commandLines: [forceCommand, devtoolsCommand].filter((entry) => Boolean(entry)),
+                    note: 'Installs bundled skills into $CODEX_HOME/skills (setup avoids overwriting chrome-devtools when already present).'
+                },
+                delegation,
+                devtools
+            }
+        };
+        if (format === 'json') {
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        console.log('Setup plan:');
+        console.log('- Skills:');
+        for (const commandLine of payload.steps.skills.commandLines) {
+            console.log(`  - ${commandLine}`);
+        }
+        console.log(`- Delegation: codex-orchestrator delegation setup --yes${delegationRepoArg}`);
+        console.log('- DevTools: codex-orchestrator devtools setup --yes');
+        console.log('Run with --yes to apply this setup.');
+        return;
+    }
+    const primarySkills = forceSkills.length > 0 ? await installSkills({ force: true, only: forceSkills }) : null;
+    const devtoolsSkill = bundledSkills.includes('chrome-devtools')
+        ? await installSkills({ force: false, only: ['chrome-devtools'] })
+        : null;
+    const skills = primarySkills && devtoolsSkill
+        ? {
+            sourceRoot: primarySkills.sourceRoot,
+            targetRoot: primarySkills.targetRoot,
+            skills: [...new Set([...primarySkills.skills, ...devtoolsSkill.skills])],
+            written: [...primarySkills.written, ...devtoolsSkill.written],
+            skipped: [...primarySkills.skipped, ...devtoolsSkill.skipped]
+        }
+        : devtoolsSkill ?? primarySkills;
+    if (!skills) {
+        throw new Error('No bundled skills detected; cannot run setup.');
+    }
+    const delegation = await runDelegationSetup({ apply: true, repoRoot });
+    const devtools = await runDevtoolsSetup({ apply: true });
+    for (const line of formatSkillsInstallSummary(skills)) {
+        console.log(line);
+    }
+    for (const line of formatDelegationSetupSummary(delegation)) {
+        console.log(line);
+    }
+    for (const line of formatDevtoolsSetupSummary(devtools)) {
+        console.log(line);
+    }
+    console.log('Next: codex-orchestrator doctor --usage');
+}
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
     const includeUsage = Boolean(flags['usage']);
+    const wantsApply = Boolean(flags['apply']);
+    const apply = Boolean(flags['yes']);
+    if (wantsApply && format === 'json') {
+        throw new Error('doctor --apply does not support --format json.');
+    }
     const windowDaysRaw = readStringFlag(flags, 'window-days');
     let windowDays = undefined;
     if (windowDaysRaw) {
@@ -591,6 +690,63 @@ async function handleDoctor(rawArgs) {
             console.log(line);
         }
     }
+    if (!wantsApply) {
+        return;
+    }
+    const repoRoot = process.cwd();
+    const delegationPlan = await runDelegationSetup({ repoRoot });
+    const devtoolsPlan = await runDevtoolsSetup();
+    const needsDelegation = !delegationPlan.readiness.configured;
+    const needsDevtoolsSkill = devtoolsPlan.readiness.skill.status !== 'ok';
+    const devtoolsConfigStatus = devtoolsPlan.readiness.config.status;
+    const needsDevtoolsConfig = devtoolsConfigStatus === 'missing';
+    const hasInvalidDevtoolsConfig = devtoolsConfigStatus === 'invalid';
+    if (!needsDelegation && !needsDevtoolsSkill && !needsDevtoolsConfig && !hasInvalidDevtoolsConfig) {
+        console.log('Doctor apply: nothing to do.');
+        return;
+    }
+    console.log('Doctor apply plan:');
+    if (needsDevtoolsSkill) {
+        console.log('- Install skill: chrome-devtools (codex-orchestrator skills install --only chrome-devtools)');
+    }
+    if (hasInvalidDevtoolsConfig) {
+        console.log(`- DevTools MCP config is invalid: ${devtoolsPlan.readiness.config.path} (fix config.toml then rerun doctor --apply)`);
+    }
+    if (needsDevtoolsConfig) {
+        console.log('- Configure DevTools MCP: codex-orchestrator devtools setup --yes');
+    }
+    if (needsDelegation) {
+        console.log('- Configure delegation MCP: codex-orchestrator delegation setup --yes');
+    }
+    if (!apply) {
+        console.log('Run with --apply --yes to apply these fixes.');
+        return;
+    }
+    if (needsDevtoolsSkill) {
+        const skills = await installSkills({ only: ['chrome-devtools'] });
+        for (const line of formatSkillsInstallSummary(skills)) {
+            console.log(line);
+        }
+    }
+    if (needsDelegation) {
+        const delegation = await runDelegationSetup({ apply: true, repoRoot });
+        for (const line of formatDelegationSetupSummary(delegation)) {
+            console.log(line);
+        }
+    }
+    if (hasInvalidDevtoolsConfig) {
+        console.log(`DevTools setup: skipped (config.toml is invalid: ${devtoolsPlan.readiness.config.path}). Fix it and rerun doctor --apply --yes.`);
+    }
+    else if (needsDevtoolsConfig) {
+        const devtools = await runDevtoolsSetup({ apply: true });
+        for (const line of formatDevtoolsSetupSummary(devtools)) {
+            console.log(line);
+        }
+    }
+    const doctorAfter = runDoctor();
+    for (const line of formatDoctorSummary(doctorAfter)) {
+        console.log(line);
+    }
 }
 async function handleDevtools(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
@@ -1023,11 +1179,17 @@ Commands:
     --codex-download-sha256 <sha>  Expected SHA256 for the prebuilt download.
     --codex-force          Overwrite existing CO-managed codex binary.
     --yes                  Apply codex CLI setup (otherwise plan only).
-  doctor [--format json] [--usage] [--window-days <n>] [--task <id>]
+  setup [--yes] [--format json]
+    --yes                 Apply setup (otherwise plan only).
+    --repo <path>         Repo root for delegation wiring (default cwd).
+    --format json         Emit machine-readable output (dry-run only).
+  doctor [--format json] [--usage] [--window-days <n>] [--task <id>] [--apply]
     --usage               Include a local usage snapshot (scans .runs/).
     --window-days <n>     Window for --usage (default 30).
     --task <id>           Limit --usage scan to a specific task directory.
-    --format json         Emit machine-readable output.
+    --apply               Plan/apply quick fixes for DevTools + delegation wiring (use with --yes).
+    --yes                 Apply fixes when --apply is set.
+    --format json         Emit machine-readable output (not supported with --apply).
   codex setup
     --source <path>        Build from local Codex repo (or git URL).
     --ref <ref>            Git ref (branch/tag/sha) when building from repo.

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

@@ -20,7 +20,8 @@ export async function runDevtoolsSetup(options = {}) {
         throw new Error(`Cannot apply DevTools setup because config.toml is invalid: ${readiness.config.path}`);
     }
     await applyDevtoolsSetup(plan, env);
-    return { status: 'applied', plan, readiness };
+    const readinessAfter = resolveDevtoolsReadiness(env);
+    return { status: 'applied', plan, readiness: readinessAfter };
 }
 export function formatDevtoolsSetupSummary(result) {
     const lines = [];

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

@@ -51,6 +51,7 @@ export function runDoctor(cwd = process.cwd()) {
             install: readiness.config.status === 'ok'
                 ? undefined
                 : [
+                    'Quick fix: codex-orchestrator doctor --apply --yes',
                     'Run: codex-orchestrator devtools setup',
                     `Run: ${setupPlan.commandLine}`,
                     `Config path: ${setupPlan.configPath}`,
@@ -115,6 +116,7 @@ export function runDoctor(cwd = process.cwd()) {
             status: delegationStatus,
             config: delegationConfig,
             enablement: [
+                'Quick fix: codex-orchestrator doctor --apply --yes',
                 'Run: codex-orchestrator delegation setup --yes',
                 'Or manually: codex mcp add delegation -- codex-orchestrator delegate-server',
                 "Enable for a run with: codex -c 'mcp_servers.delegation.enabled=true' ...",

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

@@ -14,14 +14,25 @@ export async function runDoctorUsage(options = {}) {
     const seenRunIds = new Set();
     const pipelines = new Map();
     const cloudByStatus = {};
+    const cloudByDiffStatus = {};
+    const cloudByApplyStatus = {};
+    const cloudEnvIds = new Map();
+    const cloudTasks = new Set();
     const statusCounts = { total: 0, succeeded: 0, failed: 0, cancelled: 0, other: 0 };
     let cloudRuns = 0;
     let rlmRuns = 0;
+    const rlmTasks = new Set();
     let collabRunsWithToolCalls = 0;
     let collabTotalToolCalls = 0;
+    const collabTasks = new Set();
+    const collabByStatus = {};
+    const collabByEventType = {};
+    const collabTools = new Map();
     const collabCaptureDisabled = String(process.env.CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS ?? '').trim() === '0';
     const activeIndexTasks = new Set();
     const taskKeys = readTaskIndexKeys(env.repoRoot);
+    const tasksWithChildRuns = new Set();
+    let totalChildRuns = 0;
     for (const manifestPath of manifestPaths) {
         const runIdFromPath = extractRunIdFromManifestPath(manifestPath);
         if (!runIdFromPath) {
@@ -68,19 +79,54 @@ export async function runDoctorUsage(options = {}) {
         pipelines.set(pipelineId, (pipelines.get(pipelineId) ?? 0) + 1);
         if (pipelineId === 'rlm') {
             rlmRuns += 1;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                rlmTasks.add(manifest.task_id);
+            }
         }
         if (manifest.cloud_execution) {
             cloudRuns += 1;
-            const status = (manifest.cloud_execution.status ?? 'unknown').trim() || 'unknown';
+            const cloudStatusRaw = manifest.cloud_execution.status;
+            const status = typeof cloudStatusRaw === 'string' ? cloudStatusRaw.trim() || 'unknown' : 'unknown';
             cloudByStatus[status] = (cloudByStatus[status] ?? 0) + 1;
+            const cloudDiffRaw = manifest.cloud_execution.diff_status;
+            const diffStatus = typeof cloudDiffRaw === 'string' ? cloudDiffRaw.trim() || 'unknown' : 'unknown';
+            cloudByDiffStatus[diffStatus] = (cloudByDiffStatus[diffStatus] ?? 0) + 1;
+            const cloudApplyRaw = manifest.cloud_execution.apply_status;
+            const applyStatus = typeof cloudApplyRaw === 'string' ? cloudApplyRaw.trim() || 'unknown' : 'unknown';
+            cloudByApplyStatus[applyStatus] = (cloudByApplyStatus[applyStatus] ?? 0) + 1;
+            const cloudEnvIdRaw = manifest.cloud_execution.environment_id;
+            const envId = typeof cloudEnvIdRaw === 'string' ? cloudEnvIdRaw.trim() : '';
+            if (envId) {
+                cloudEnvIds.set(envId, (cloudEnvIds.get(envId) ?? 0) + 1);
+            }
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                cloudTasks.add(manifest.task_id);
+            }
         }
         if (Array.isArray(manifest.collab_tool_calls) && manifest.collab_tool_calls.length > 0) {
             collabRunsWithToolCalls += 1;
             collabTotalToolCalls += manifest.collab_tool_calls.length;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                collabTasks.add(manifest.task_id);
+            }
+            for (const entry of manifest.collab_tool_calls) {
+                const tool = typeof entry?.tool === 'string' && entry.tool ? entry.tool : 'unknown';
+                const status = typeof entry?.status === 'string' && entry.status ? entry.status : 'unknown';
+                const eventType = typeof entry?.event_type === 'string' && entry.event_type ? entry.event_type : 'unknown';
+                collabByStatus[status] = (collabByStatus[status] ?? 0) + 1;
+                collabByEventType[eventType] = (collabByEventType[eventType] ?? 0) + 1;
+                collabTools.set(tool, (collabTools.get(tool) ?? 0) + 1);
+            }
         }
-        if (taskKeys.has(manifest.task_id)) {
+        if (typeof manifest.task_id === 'string' && manifest.task_id && taskKeys.has(manifest.task_id)) {
             activeIndexTasks.add(manifest.task_id);
         }
+        if (Array.isArray(manifest.child_runs) && manifest.child_runs.length > 0) {
+            totalChildRuns += manifest.child_runs.length;
+            if (typeof manifest.task_id === 'string' && manifest.task_id) {
+                tasksWithChildRuns.add(manifest.task_id);
+            }
+        }
     }
     const pipelineTop = [...pipelines.entries()]
         .sort((a, b) => b[1] - a[1])
@@ -103,26 +149,45 @@ export async function runDoctorUsage(options = {}) {
             activeWithSubagents += 1;
         }
     }
+    const cloudTopEnvIds = [...cloudEnvIds.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([id, runs]) => ({ id, runs }));
+    const collabTopTools = [...collabTools.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([tool, calls]) => ({ tool, calls }));
     return {
         window_days: windowDays,
         cutoff_iso: cutoffIso,
         runs: statusCounts,
         cloud: {
             runs: cloudRuns,
-            by_status: cloudByStatus
+            unique_tasks: cloudTasks.size,
+            by_status: cloudByStatus,
+            by_diff_status: cloudByDiffStatus,
+            by_apply_status: cloudByApplyStatus,
+            top_environment_ids: cloudTopEnvIds
         },
         rlm: {
-            runs: rlmRuns
+            runs: rlmRuns,
+            unique_tasks: rlmTasks.size
         },
         collab: {
             runs_with_tool_calls: collabRunsWithToolCalls,
             total_tool_calls: collabTotalToolCalls,
+            unique_tasks: collabTasks.size,
+            by_status: collabByStatus,
+            by_event_type: collabByEventType,
+            top_tools: collabTopTools,
             capture_disabled: collabCaptureDisabled
         },
         delegation: {
             active_top_level_tasks: activeTasks.length,
             active_with_subagents: activeWithSubagents,
             total_subagent_manifests: totalSubagentManifests,
+            tasks_with_child_runs: tasksWithChildRuns.size,
+            total_child_runs: totalChildRuns,
             errors: delegationErrors
         },
         pipelines: {
@@ -135,12 +200,31 @@ export function formatDoctorUsageSummary(result) {
     const lines = [];
     lines.push(`Usage (last ${result.window_days}d, cutoff ${result.cutoff_iso})`);
     lines.push(`  - runs: ${result.runs.total} (ok=${result.runs.succeeded}, failed=${result.runs.failed}, cancelled=${result.runs.cancelled}, other=${result.runs.other})`);
-    lines.push(`  - cloud: ${result.cloud.runs} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}`);
-    lines.push(`  - rlm: ${result.rlm.runs} (${formatPercent(result.rlm.runs, result.runs.total)})`);
+    const cloudSuffix = result.cloud.unique_tasks > 0
+        ? ` over ${result.cloud.unique_tasks} task${result.cloud.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    const cloudDiff = formatTopCounts(result.cloud.by_diff_status, 2, 'diff');
+    const cloudApply = formatTopCounts(result.cloud.by_apply_status, 2, 'apply');
+    const cloudEnv = formatTopList(result.cloud.top_environment_ids.map((entry) => ({ key: entry.id, value: entry.runs })), 2, 'env');
+    lines.push(`  - cloud: ${result.cloud.runs}${cloudSuffix} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}${cloudDiff}${cloudApply}${cloudEnv}`);
+    const rlmSuffix = result.rlm.unique_tasks > 0
+        ? ` over ${result.rlm.unique_tasks} task${result.rlm.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    lines.push(`  - rlm: ${result.rlm.runs}${rlmSuffix} (${formatPercent(result.rlm.runs, result.runs.total)})`);
     const collabSuffix = result.collab.capture_disabled ? ' (capture disabled)' : '';
-    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`);
+    const collabTaskSuffix = result.collab.unique_tasks > 0
+        ? ` over ${result.collab.unique_tasks} task${result.collab.unique_tasks === 1 ? '' : 's'}`
+        : '';
+    const collabAvg = result.collab.runs_with_tool_calls > 0
+        ? ` (avg ${Math.round((result.collab.total_tool_calls / result.collab.runs_with_tool_calls) * 10) / 10}/run)`
+        : '';
+    const collabOk = result.collab.by_status.completed ?? 0;
+    const collabFailed = result.collab.by_status.failed ?? 0;
+    const collabToolList = formatTopList(result.collab.top_tools.map((entry) => ({ key: entry.tool, value: entry.calls })), 3, 'tools');
+    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`
+        + `${collabTaskSuffix}, events=${result.collab.total_tool_calls}${collabAvg} (ok=${collabOk}, failed=${collabFailed})${collabToolList}`);
     if (result.delegation.active_top_level_tasks > 0) {
-        lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests`);
+        lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests (${result.delegation.total_subagent_manifests} total); child_runs=${result.delegation.total_child_runs} over ${result.delegation.tasks_with_child_runs} tasks`);
     }
     else {
         lines.push('  - delegation: no top-level tasks detected in tasks/index.json for this window');
@@ -193,6 +277,30 @@ function formatCloudStatuses(byStatus) {
         .join(', ');
     return ` [${top}]`;
 }
+function formatTopCounts(byKey, limit, label) {
+    const entries = Object.entries(byKey);
+    if (entries.length === 0) {
+        return '';
+    }
+    entries.sort((a, b) => b[1] - a[1]);
+    const top = entries
+        .slice(0, limit)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(', ');
+    return ` ${label}[${top}]`;
+}
+function formatTopList(entries, limit, label) {
+    const filtered = entries.filter((entry) => entry.key && Number.isFinite(entry.value) && entry.value > 0);
+    if (filtered.length === 0) {
+        return '';
+    }
+    const top = filtered
+        .sort((a, b) => b.value - a.value || a.key.localeCompare(b.key))
+        .slice(0, limit)
+        .map((entry) => `${entry.key}=${entry.value}`)
+        .join(', ');
+    return ` ${label}[${top}]`;
+}
 function readTaskIndexKeys(repoRoot) {
     const indexPath = join(repoRoot, 'tasks', 'index.json');
     try {

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

@@ -61,7 +61,7 @@ export function formatInitSummary(result, cwd) {
         lines.push('No files written.');
     }
     lines.push('Next steps (recommended):');
-    lines.push('  - codex-orchestrator delegation setup --yes');
+    lines.push('  - codex-orchestrator setup --yes  # installs bundled skills + configures delegation/devtools wiring');
     lines.push('  - codex-orchestrator codex setup  # optional: managed/pinned Codex CLI (stock CLI works by default)');
     return lines;
 }

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

@@ -36,6 +36,12 @@ export async function installSkills(options = {}) {
         skills: selectedSkills
     };
 }
+export async function listBundledSkills() {
+    const pkgRoot = findPackageRoot();
+    const sourceRoot = join(pkgRoot, 'skills');
+    await assertDirectory(sourceRoot);
+    return await listSkillNames(sourceRoot);
+}
 export function formatSkillsInstallSummary(result, cwd = process.cwd()) {
     const lines = [];
     lines.push(`Skills source: ${result.sourceRoot}`);

package/docs/README.md

@@ -101,7 +101,8 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Companion Package Commands
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `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] [--usage]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`).
+- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills and configures delegation + DevTools wiring).
+- `codex-orchestrator doctor [--format json] [--usage] [--apply]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`). `--apply` plans/applies quick fixes (use with `--yes`).
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
 - `codex-orchestrator delegation setup [--yes]`: configure delegation MCP wiring (`--yes` applies `codex mcp add ...`).
 - `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).

package/package.json

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

package/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: chrome-devtools
+description: Control and inspect Chrome via the Chrome DevTools MCP server (navigate, interact, screenshots, console, network, perf).
+allowed-tools: mcp__chrome-devtools__*
+---
+
+# Chrome DevTools (MCP)
+
+Use this skill when you need browser-grounded evidence (UI screenshots, console errors, network failures, perf traces) or when a task requires real page interaction.
+
+## Preflight
+
+- Ensure the MCP server is configured: `codex-orchestrator devtools setup --yes`.
+- If tools are missing in the current run, enable the server and restart the run:
+  - `codex -c 'mcp_servers.chrome-devtools.enabled=true' ...`
+
+## Default Workflow
+
+1. Open a new page and navigate to the target URL.
+2. Wait for the page to be stable (avoid racing async renders).
+3. Interact with the UI (click/fill/press) to reproduce the behavior.
+4. Collect evidence:
+   - Screenshot(s) for visual state
+   - Console messages for runtime errors
+   - Network requests for failed/slow calls
+5. Close pages when finished.
+
+## Evidence Discipline
+
+- Always capture at least one screenshot when validating UI behavior.
+- When debugging, always include:
+  - `list_console_messages`
+  - `list_network_requests` (and fetch details for failures)
+

package/skills/delegation-usage/SKILL.md

@@ -64,8 +64,10 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 ### 0) One-time setup (register the MCP server)
 
 - Register the delegation server once:
-  - Preferred: `codex-orchestrator delegation setup --yes`
-    - This wraps `codex mcp add delegation ...` and keeps wiring discoverable via `codex-orchestrator doctor`.
+  - Preferred: `codex-orchestrator setup --yes`
+    - One-shot bootstrap (installs bundled skills + configures delegation/DevTools wiring).
+  - `codex-orchestrator delegation setup --yes`
+    - Delegation-only setup (wraps `codex mcp add delegation ...` and keeps wiring discoverable via `codex-orchestrator doctor`).
   - `codex mcp add delegation -- codex-orchestrator delegate-server`
   - Optional: append `--repo /path/to/repo` to pin the server to one repo (not recommended if you work across repos).
   - `delegate-server` is the canonical name; `delegation-server` is supported as an alias.