@kbediako/codex-orchestrator 0.1.23 → 0.1.24

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,6 +163,11 @@ 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
@@ -173,6 +184,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/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.24",
   "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.