A

Provider, Codex, and CLI Bootstrap Refactor Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Reduce one-off provider install logic, split the overgrown Codex harness adapter, and replace ad hoc SQLite-free CLI parsing with a clearer dispatch layer without changing external behavior.

Architecture: Introduce shared provider install-target helpers used by setup, uninstall, and doctor. Move SQLite-free command dispatch into a dedicated CLI module with small command descriptors. Split Codex provider code into focused modules while preserving the existing public imports used by tests.

Tech Stack: TypeScript ESM, Commander, Vitest, Node fs/process APIs.

Task 1: Provider Instruction Targets#

Files:

  • Create: src/agent/install-targets.ts
  • Modify: src/commands/setup.ts
  • Modify: src/commands/uninstall.ts
  • Modify: src/commands/doctor-checks/install.ts
  • Test: test/setup.test.ts, test/uninstall.test.ts, test/doctor.test.ts

Steps:

  1. Extract Claude import-file and Codex inline-block behavior behind provider instruction target helpers.
  2. Keep setup and uninstall output compatible with existing tests.
  3. Add doctor checks for Codex instructions while preserving existing stable install keys.
  4. Run targeted setup/uninstall/doctor tests.

Task 2: SQLite-Free CLI Bootstrap#

Files:

  • Create: src/cli/sqlite-free.ts
  • Modify: src/cli.ts
  • Test: test/cli.test.ts

Steps:

  1. Move SQLite-free dispatch and flag parsers into a focused module.
  2. Use a small descriptor table for recovery-safe command dispatch.
  3. Preserve setup shortcut behavior and worker/update fast paths.
  4. Run CLI tests.

Task 3: Codex Harness Adapter Split#

Files:

  • Create: src/harness/providers/codex/request.ts
  • Create: src/harness/providers/codex/app-server.ts
  • Create: src/harness/providers/codex/events.ts
  • Modify: src/harness/providers/codex.ts
  • Test: test/codex-harness-provider.test.ts

Steps:

  1. Move request construction and unsupported-field validation into request.ts.
  2. Move app-server process/JSON-RPC runner into app-server.ts.
  3. Move notification/event/usage mapping into events.ts.
  4. Re-export existing public test imports from codex.ts.
  5. Replace hard-coded app-server client version with package version lookup.
  6. Run Codex harness tests.

Task 4: Full Verification#

Steps:

  1. Run npm run lint.
  2. Run npm test.
  3. Run almanac health and note remaining wiki-only dead refs if unchanged.

Implementation Log#

  • 2026-05-13: Initial plan created after reading provider-install-layer, harness-providers, sqlite-free-cli-bootstrap, and lifecycle-cli.
  • 2026-05-13: Began Task 1 by creating src/agent/install-targets.ts to centralize Claude import-file and Codex inline-instruction behavior.
  • 2026-05-13: Updated src/commands/setup.ts and src/commands/uninstall.ts to call the shared instruction helpers while preserving legacy exports used by tests.
  • 2026-05-13: Updated doctor install checks so install.import validates both Claude import and Codex managed instructions while keeping the existing stable key list.
  • 2026-05-13: Verified Task 1 with npm test -- test/setup.test.ts test/uninstall.test.ts test/doctor.test.ts and npm run lint.
  • 2026-05-13: Completed Task 2 by moving recovery-safe command routing and setup shortcut parsing into src/cli/sqlite-free.ts.
  • 2026-05-13: Verified Task 2 with npm test -- test/cli.test.ts and npm run lint.
  • 2026-05-13: Began Task 3 by extracting Codex request construction to src/harness/providers/codex/request.ts and Codex readiness probes to src/harness/providers/codex/status.ts.
  • 2026-05-13: Replaced the hard-coded Codex app-server client version with package-version lookup from the request module.
  • 2026-05-13: Verified the Codex extraction with npm test -- test/codex-harness-provider.test.ts and npm run lint.
  • 2026-05-13: Follow-up Codex cleanup split src/harness/providers/codex.ts into a 106-line facade plus codex/exec.ts, codex/app-server.ts, and codex/events.ts.
  • 2026-05-13: Verified the Codex event/protocol split with npm run lint and npm test -- test/codex-harness-provider.test.ts.

Decision Log#

  • Keep this as a refactor, not a feature expansion: no new public commands and no behavior change unless required to remove a smell safely.
  • Preserve existing exported compatibility functions from setup.ts and uninstall.ts so current tests and external callers do not need a coordinated migration.
  • Do not implement Cursor install behavior in this pass. Cursor remains gated/placeholder; the target abstraction should make it easier later without pretending support exists now.
  • Keep install.import as the stable doctor key rather than adding a new Codex-specific install key. The message now describes "Agent instruction entries" so JSON consumers do not see a breaking key list.
  • Keep tryParseSetupShortcut re-exported from src/cli.ts even though its implementation moved, because tests and external code may already import it from the process entrypoint.
  • Keep src/harness/providers/codex.ts as the compatibility facade. Tests and downstream imports continue using the old module path while the implementation lives in smaller files.
  • Split Codex by responsibility rather than protocol names alone: exec.ts owns the legacy codex exec --json path, app-server.ts owns JSON-RPC process handling, and events.ts owns normalized harness-event mapping plus failure/usage parsing.