ultracode-for-codex 0.2.6 → 0.3.1

package/README.md

@@ -1,11 +1,12 @@
 # Ultracode for Codex
 
-Ultracode for Codex runs local workflows as CLI commands backed by an
-already-authenticated Codex CLI session. Progress streams to stderr as JSONL by
-default, the final result prints to stdout as JSON, and cancellation/retry stay
-inside the same command process.
-The packaged `settings.json` defaults workflow runs to OS background execution
-with result and progress files under `.ultracode-for-codex/background/{jobId}`.
+Ultracode for Codex ships two Codex skill commands plus a local npm CLI runtime.
+`$ultracode-for-codex` is the default high-visibility mode: the Codex main
+context plans adaptive phases, spawns focused parallel subagents, synthesizes
+their results, and reports progress directly in the chat.
+`$ultracode-for-codex-cli` is the explicit runtime path for package validation,
+background jobs, attached CLI runs, release checks, and reproducible local
+workflow artifacts.
 
 ## Quick Start
 
@@ -16,6 +17,16 @@ npm install --save-dev ultracode-for-codex
 npm exec -- ultracode-for-codex --llm-guide
 ```
 
+Install the Codex skill commands from the package:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex-cli \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
 Build and verify a local installable tarball from a source checkout:
 
 ```bash
@@ -26,10 +37,10 @@ npm run pack:ultracode-for-codex
 Install the tarball from a target project:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-0.2.6.tgz
+npm install --save-dev /path/to/ultracode-for-codex-<version>.tgz
 ```
 
-Run a workflow:
+Run through the CLI runtime when that path is explicitly wanted:
 
 ```bash
 npm exec -- ultracode-for-codex run \
@@ -41,6 +52,17 @@ npm exec -- ultracode-for-codex run \
 
 By default this prints a background launch record to stdout. The record contains
 `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`.
+Use the job id to inspect or control the background run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/target-repo --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex jobs --cwd /path/to/target-repo
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/target-repo
+```
 
 Run attached to the current terminal:
 
@@ -64,14 +86,14 @@ npm exec -- ultracode-for-codex run \
   --args '{"prompt":"review correctness risks and propose fixes"}'
 ```
 
-The built-in `task` and `code-review` workflows use an LLM planner first, then
-run work phase by phase. Within each phase, multiple focused Codex subagents run
-in parallel by default, followed by phase and final synthesis. The planner may
-choose a single-agent path only when parallel execution would add risk or waste.
-Planner guidance includes dynamic workflow patterns such as classify-and-act,
-fan-out-and-synthesize, adversarial verification, generate-and-filter,
-tournament, and loop-until-done, so different work types can use different
-phase shapes.
+The CLI built-in `task` and `code-review` workflows use an LLM planner first,
+then run work phase by phase. Within each phase, multiple focused Codex
+subagents run in parallel by default, followed by phase and final synthesis. The
+planner may choose a single-agent path only when parallel execution would add
+risk or waste. Planner guidance includes dynamic workflow patterns such as
+classify-and-act, fan-out-and-synthesize, adversarial verification,
+generate-and-filter, tournament, and loop-until-done, so different work types
+can use different phase shapes.
 
 ## Settings
 
@@ -102,12 +124,21 @@ The package default workflow timeout is `0`, meaning the workflow waits until it
 completes, is cancelled, or the Codex app-server exits. Set `--timeout-ms` to a
 positive value to opt into a deadline for one run.
 Use the default background execution for long Codex-launched work so Codex can
-continue other tasks and inspect `progressPath` or `resultPath` later. Use
+continue other tasks and inspect the job later with `status`, `logs`, or
+`result`. Use
 `--execution attached` only when the caller must block until the final result.
 
 ## CLI Controls
 
 - Use `--version` or `-v` to print the installed package version.
+- Use `status`, `wait`, `logs`, `result`, and `cancel` with a background
+  `jobId` or `metadata.json` path to inspect, wait for, read, or cancel OS
+  background runs.
+- Use `jobs` or `list` to enumerate local background runs.
+- Use `archive` or `export` to write a sensitive local JSON bundle for one run
+  without deleting runtime state.
+- Use `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  for shorter foreground checks.
 - Progress is printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
@@ -120,6 +151,10 @@ continue other tasks and inspect `progressPath` or `resultPath` later. Use
   begins.
 - Each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the active workflow.
 - Use `--retry-limit <n>` to retry failed workflows inside the same process.
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
@@ -131,14 +166,18 @@ continue other tasks and inspect `progressPath` or `resultPath` later. Use
 - Use `--execution background` for OS background runs and `--execution attached`
   only when the caller should stay connected until completion.
 
-## Codex Companion Skill
+## Codex Skill Commands
 
-The npm package is the runtime artifact. The companion Codex skill in
-`skills/ultracode-for-codex` is a lightweight operating guide for agents using
-the package; it contains no runtime code.
+The npm package includes two Codex skill command folders:
 
-Install or copy that folder into `${CODEX_HOME:-$HOME/.codex}/skills` when you
-want Codex to auto-load the package boundaries and verification routine.
+- `skills/ultracode-for-codex`: default Codex-native orchestration. The main
+  context plans adaptive phases, spawns parallel subagents, synthesizes each
+  phase, reports completion progress, and recommends a final critical re-check.
+  Live progress uses test-runner-style visual snapshots; completion reporting
+  uses a diffstat-style impact summary plus a plan-style result summary.
+- `skills/ultracode-for-codex-cli`: explicit CLI runtime operations, including
+  background jobs, attached runs, packaging, release checks, runtime-boundary
+  validation, and installed E2E tests.
 
 ## Runtime Boundaries
 
@@ -147,7 +186,7 @@ want Codex to auto-load the package boundaries and verification routine.
   environment.
 - Codex subagents run against the requested workflow cwd and receive bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `task` and `code-review` inject deterministic workspace context into
+- CLI built-in `task` and `code-review` inject deterministic workspace context into
   planner-selected phase-wise parallel subagents, then synthesize each phase and
   the final result.
 - Workflow execution is local and command-owned; settings default to OS
@@ -196,6 +235,12 @@ For supported CI/CD environments, provenance is available as an explicit opt-in:
 npm run publish:npm:provenance
 ```
 
+Optional live smoke against the local Codex CLI:
+
+```bash
+ULTRACODE_LIVE_SMOKE=1 npm run smoke:live
+```
+
 Useful local run:
 
 ```bash
@@ -205,8 +250,11 @@ node dist/cli.js run --accept-llm-guide=v1 --script-file ./workflow.js
 
 ## Docs
 
-- `skills/ultracode-for-codex/SKILL.md`: Codex companion skill for operating
-  the npm runtime safely.
+- `skills/ultracode-for-codex/SKILL.md`: default Codex-native orchestrator
+  skill command.
+- `skills/ultracode-for-codex/references/progress-visuals.md`: golden visual
+  progress and completion summary examples for native orchestration.
+- `skills/ultracode-for-codex-cli/SKILL.md`: explicit CLI runtime skill command.
 - `ULTRACODE_INSTALL.md`: install and operating guide for LLM agents.
 - `docs/ultracode-p3a-journal-design.md`: journal contract.
 - `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.

package/ULTRACODE_INSTALL.md

@@ -1,18 +1,41 @@
 # Ultracode install and usage guide
 
 This file is for LLM agents installing or operating `ultracode-for-codex`.
-Read it before running workflows or generating integration code.
+Read it before running CLI workflows, installing the Codex skill commands, or
+generating integration code.
 
 ## What This Package Does
 
-`ultracode-for-codex` provides a local command-owned workflow runtime backed by an
-already-authenticated Codex CLI session. The packaged `settings.json` defaults
-workflow runs to OS background execution with result and progress files under
+`ultracode-for-codex` provides two Codex skill command surfaces and a local
+command-owned workflow runtime backed by an already-authenticated Codex CLI
+session.
+
+Skill commands:
+
+- `$ultracode-for-codex`: default Codex-native orchestration. The main Codex
+  context plans phases, spawns focused parallel subagents, synthesizes results,
+  and shows progress directly in the chat with test-runner-style live snapshots
+  and diffstat-plus-plan completion summaries.
+- `$ultracode-for-codex-cli`: explicit CLI runtime operation for background
+  jobs, attached runs, package validation, release checks, and reproducible
+  local runtime artifacts.
+
+The packaged `settings.json` defaults CLI workflow runs to OS background
+execution with result and progress files under
 `.ultracode-for-codex/background/{jobId}`.
 
 Production surface:
 
 - `ultracode-for-codex run`
+- `ultracode-for-codex status`
+- `ultracode-for-codex wait`
+- `ultracode-for-codex logs`
+- `ultracode-for-codex result`
+- `ultracode-for-codex cancel`
+- `ultracode-for-codex jobs`
+- `ultracode-for-codex list`
+- `ultracode-for-codex archive`
+- `ultracode-for-codex export`
 
 Progress, cancellation, permission review, retry, and final result projection
 are handled inside the CLI process. Progress is JSONL on stderr by
@@ -31,21 +54,24 @@ npm exec -- ultracode-for-codex --llm-guide
 For source-checkout validation, install the generated tarball instead:
 
 ```bash
-npm install --save-dev ./ultracode-for-codex-0.2.6.tgz
+npm install --save-dev ./ultracode-for-codex-<version>.tgz
 ```
 
-Optional Codex companion skill:
+Optional Codex skill commands:
 
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
 cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex \
   "${CODEX_HOME:-$HOME/.codex}/skills/"
+cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex-cli \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-The skill is only an operating guide. The npm package remains the runtime
-artifact.
+`$ultracode-for-codex` keeps orchestration in the main Codex context.
+`$ultracode-for-codex-cli` uses the npm CLI runtime. The npm package remains the
+runtime artifact for CLI execution.
 
-## Run
+## Run The CLI Runtime
 
 ```bash
 npm exec -- ultracode-for-codex run \
@@ -57,14 +83,26 @@ npm exec -- ultracode-for-codex run \
 
 The default run prints a background launch record to stdout. Prefer that
 background path for long Codex-launched work so Codex can continue other tasks
-and inspect `progressPath` or `resultPath` later. Use `--execution attached`
-only when the caller must block until completion.
-
-Use built-in `task` for general work and `code-review` for review-specific work.
-Both start with an LLM planner, execute phase by phase, run multiple focused
-Codex subagents in parallel within each phase by default, and synthesize phase
-and final results. The planner chooses a single-agent path only when parallel
-execution would add risk or waste.
+and inspect the job later with `status`, `logs`, or `result`. Use
+`--execution attached` only when the caller must block until completion.
+
+Use the background `jobId` from the launch record to inspect or control the run:
+
+```bash
+npm exec -- ultracode-for-codex status <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex wait <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex logs <jobId> --cwd /path/to/project --tail 40
+npm exec -- ultracode-for-codex result <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex cancel <jobId> --cwd /path/to/project
+npm exec -- ultracode-for-codex jobs --cwd /path/to/project
+npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/project
+```
+
+Use CLI built-in `task` for general work and `code-review` for review-specific
+work. Both start with an LLM planner, execute phase by phase, run multiple
+focused Codex subagents in parallel within each phase by default, and synthesize
+phase and final results. The planner chooses a single-agent path only when
+parallel execution would add risk or waste.
 Planner guidance includes classify-and-act, fan-out-and-synthesize,
 adversarial verification, generate-and-filter, tournament, and loop-until-done
 patterns so different work types can use different phase shapes.
@@ -93,6 +131,13 @@ Settings defaults:
 Useful controls:
 
 - `--version` or `-v` prints the installed package version.
+- `status`, `wait`, `logs`, `result`, and `cancel` accept a background `jobId`
+  or `metadata.json` path.
+- `jobs` and `list` enumerate local background runs.
+- `archive` and `export` write a sensitive local JSON bundle for one run without
+  deleting runtime state.
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain` are
+  available for shorter foreground checks.
 - Progress events are printed to stderr as JSONL by default.
 - The final workflow result is printed as JSON to stdout.
 - The package default workflow timeout is `0`, meaning the workflow waits until
@@ -107,6 +152,10 @@ Useful controls:
   begins.
 - Each `workflow.agent.completed` record includes phase progress, total known
   agent progress, and elapsed time.
+- After a completed run, `workflow.summary.ready` reports each phase with its
+  planned agent count and angle/focus list, then `workflow.review.recommended`
+  asks the current session LLM to critically re-check the final result before
+  acting on it.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
@@ -121,7 +170,7 @@ Useful controls:
 ## Runtime Contract
 
 - Use Codex app-server over stdio as the production backend.
-- Keep workflow execution local and command-owned; settings default to OS
+- Keep CLI workflow execution local and command-owned; settings default to OS
   background execution so long runs can keep waiting while Codex does other
   work.
 - Route progress, cancellation, permission review, retry, and result projection
@@ -160,6 +209,11 @@ workflow.
 ## Documentation Map
 
 - `README.md`: human quickstart and common examples.
+- `skills/ultracode-for-codex/SKILL.md`: default Codex-native orchestrator
+  command.
+- `skills/ultracode-for-codex/references/progress-visuals.md`: golden visual
+  progress and completion summary examples for native orchestration.
+- `skills/ultracode-for-codex-cli/SKILL.md`: explicit CLI runtime command.
 - `docs/ultracode-p3a-journal-design.md`: implemented journal contract.
 - `docs/ultracode-p3b-resume-cache.md`: runtime-internal resume/cache contract.
 - `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.

package/dist/cli.d.ts

@@ -20,5 +20,20 @@ interface ParsedOptions {
     readonly resumeFromRunId?: string;
     readonly permission?: string;
     readonly retryLimit?: string;
+    readonly jobId?: string;
+    readonly metadataPath?: string;
+    readonly resultPath?: string;
+    readonly progressPath?: string;
+    readonly pidPath?: string;
+    readonly intervalMs?: string;
+    readonly tail?: string;
+    readonly signal?: string;
+    readonly plain?: string;
+    readonly format?: string;
+    readonly event?: string;
+    readonly result?: string;
+    readonly wait?: string;
+    readonly outDir?: string;
+    readonly outputPath?: string;
 }
 export declare function parseOptions(args: readonly string[]): ParsedOptions;