ultracode-for-codex 0.3.2 → 0.3.4

package/README.md

@@ -1,31 +1,58 @@
 # Ultracode for Codex
 
-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.
+Dynamic workflows redesigned for Codex, with parallel subagents, visible
+progress, and an optional local CLI runtime.
 
-## Quick Start
+The default experience is Codex-native: you ask for `$ultracode-for-codex`, and
+the main Codex chat becomes the orchestrator. It plans the next useful phase,
+runs independent subagents in parallel when that helps, summarizes their
+findings, and shows compact progress snapshots directly in the conversation.
 
-Install from npm:
+A local CLI runtime is included for users who want background jobs, reproducible
+workflow runs, package checks, or attached terminal execution.
+
+## Why Use It
+
+- Get multi-angle reviews instead of a single linear pass.
+- Run implementation and verification work phase by phase.
+- See what agents are doing, what finished, and what still needs attention.
+- Keep long CLI workflows running in the OS background when desired.
+- Package the same workflow behavior for repeatable local use.
+
+## Install
+
+For one project:
 
 ```bash
 npm install --save-dev ultracode-for-codex
-npm exec -- ultracode-for-codex --llm-guide
 ```
 
-Or install the CLI globally:
+For global use:
 
 ```bash
 npm install -g ultracode-for-codex
+```
+
+If you installed it globally, check the CLI directly:
+
+```bash
 ultracode-for-codex --version
 ultracode-for-codex --llm-guide
 ```
 
-Install the Codex skill commands from a project install:
+If you installed it as a project dependency, check it with `npm exec --`:
+
+```bash
+npm exec -- ultracode-for-codex --version
+npm exec -- ultracode-for-codex --llm-guide
+```
+
+## Install The Codex Skills
+
+After installing the npm package, copy the included skill commands into your
+Codex skills folder.
+
+From a project install:
 
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
@@ -35,7 +62,7 @@ cp -R ./node_modules/ultracode-for-codex/skills/ultracode-for-codex-cli \
   "${CODEX_HOME:-$HOME/.codex}/skills/"
 ```
 
-Or install the skill commands from a global npm install:
+From a global install:
 
 ```bash
 mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
@@ -46,235 +73,173 @@ cp -R "$GLOBAL_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:
+Restart Codex or start a new Codex session if the skills do not appear
+immediately.
 
-```bash
-npm install
-npm run pack:ultracode-for-codex
+## Use In Codex
+
+Use the default skill for normal work:
+
+```text
+$ultracode-for-codex Review this change for correctness and security risks.
 ```
 
-Install the tarball from a target project:
+Good tasks for the default skill:
+
+- code review;
+- implementation planning;
+- multi-step verification;
+- architecture or design critique;
+- release readiness checks;
+- work that benefits from parallel perspectives.
+
+The default skill shows a phase plan before work starts and keeps a cumulative
+progress snapshot as agents finish.
+
+Example:
+
+```text
+Phase Review
+
+  + Runtime correctness       done      no material issue
+  > Security boundary         running   checking local state handling
+  - Package contract          queued    verify installed files
+
+Agents 1 completed | 1 running | 1 queued
+Next: synthesize material findings
+```
+
+## Use The CLI Runtime
+
+Use `$ultracode-for-codex-cli` or the `ultracode-for-codex` binary when you
+explicitly want a local command-owned workflow run.
+
+Run a built-in task workflow:
 
 ```bash
-npm install --save-dev /path/to/ultracode-for-codex-<version>.tgz
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/project \
+  --name task \
+  --args '{"prompt":"review correctness risks and propose fixes"}'
 ```
 
-Run through the CLI runtime when that path is explicitly wanted:
+Run a code review:
 
 ```bash
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
-  --cwd /path/to/target-repo \
-  --script-file .codex/workflows/review.js \
+  --cwd /path/to/project \
+  --name code-review \
   --args '{"prompt":"review the current change"}'
 ```
 
-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:
+The built-in `code-review` workflow collects bounded repository evidence,
+chooses review lenses, runs finder agents in parallel, verifies each candidate,
+and returns JSON with `findings`, `provenance`, `synthesis`, and `stats`.
+Use `{"level":"high"}` to skip the final sweep, or omit it for the default
+`xhigh` review.
+
+CLI runs use OS background execution by default. The command prints a launch
+record with a `jobId`, then you can inspect or control the job:
 
 ```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
+npm exec -- ultracode-for-codex status <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
 ```
 
-Run attached to the current terminal:
+Use attached execution only when the terminal should stay connected until the
+workflow finishes:
 
 ```bash
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
   --execution attached \
-  --cwd /path/to/target-repo \
-  --script-file .codex/workflows/review.js \
-  --args '{"prompt":"review the current change"}'
+  --cwd /path/to/project \
+  --name task \
+  --args '{"prompt":"check the release plan"}'
 ```
 
-Named workflows are resolved from `.codex/workflows`, user workflow folders,
-plugin workflow folders, and built-ins:
+Resume a completed local workflow from preserved runtime state:
 
 ```bash
 npm exec -- ultracode-for-codex run \
   --accept-llm-guide=v1 \
-  --cwd /path/to/target-repo \
-  --name task \
-  --args '{"prompt":"review correctness risks and propose fixes"}'
+  --execution attached \
+  --cwd /path/to/project \
+  --resume-from-run-id run_...
 ```
 
-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
-
-Package defaults live in `settings.json`:
-
-```json
-{
-  "workflow": {
-    "executionMode": "background",
-    "progress": "jsonl",
-    "permission": "ask",
-    "retryLimit": 0,
-    "timeoutMs": 0,
-    "background": {
-      "runDir": ".ultracode-for-codex/background/{jobId}",
-      "resultFile": "result.json",
-      "progressFile": "progress.jsonl",
-      "metadataFile": "metadata.json",
-      "pidFile": "pid"
-    }
-  }
-}
-```
+## What Gets Installed
 
-Use `--execution attached`, `--progress`, `--permission`, `--retry-limit`, and
-`--timeout-ms` to override settings for one run.
-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 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`;
-  agent records also include stable agent identity and label fields.
-- Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
-  snapshot, not a promise that every later phase is already known.
-- `workflow.phase.planned` is emitted immediately before each phase starts and
-  carries that phase's current planned agent role labels. Each
-  `workflow.phase.started` record repeats the same role labels when the phase
-  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.
-  Positive values opt into a workflow deadline and per-agent silence budget;
-  that budget is not divided by the retry budget.
-- Use `--permission ask|allow|deny` for project/user/plugin/scriptPath workflow
-  permission reviews.
-- Use `--progress plain` for human-readable log lines.
-- Use `--execution background` for OS background runs and `--execution attached`
-  only when the caller should stay connected until completion.
-
-## Codex Skill Commands
-
-The npm package includes two Codex skill command folders:
-
-- `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
-
-- The only production backend is Codex app-server over stdio.
-- Direct provider credentials are stripped from the Codex child process
-  environment.
-- Codex subagents run against the requested workflow cwd and receive bounded
-  read-only workspace tools for text file reads and directory listings.
-- 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
-  background execution so long runs can keep waiting while Codex does other
-  work.
-- `.ultracode-for-codex` workflow state is sensitive local data.
-- `journalPath`, `journal.jsonl`, and journal contents stay out of CLI output.
-  Local runtime state may still contain runtime-owned
-  `transcriptDir`, `scriptPath`, and result files.
-- `resumeFromRunId` remains runtime-internal and same-session; users retry the
-  active run or rerun the workflow command.
-- `agent(..., { isolation: "worktree" })` runs the agent in a detached git
-  worktree and preserves the worktree for review, including clean worktrees.
-
-## Development
+The package includes:
 
-```bash
-npm install
-npm test
-npm run pack:ultracode-for-codex
-npm run test:e2e:ultracode-for-codex
-npm run test:all
-```
+- `ultracode-for-codex`: the local CLI binary;
+- `skills/ultracode-for-codex`: the recommended Codex-native skill;
+- `skills/ultracode-for-codex-cli`: the explicit CLI/runtime skill;
+- `settings.json`: default CLI runtime settings;
+- `ULTRACODE_INSTALL.md`: detailed install and operating guide for agents.
+
+## Local State
+
+CLI runs write workflow state under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`.
+The runtime keeps background metadata, journals, transcripts, generated scripts,
+and results outside the target project so review evidence stays focused on the
+workspace itself.
 
-## Publishing
+Project workflow sources may still live in `.codex/workflows/`. If an older
+workspace already has `.ultracode-for-codex/`, keep it ignored and treat it as
+legacy sensitive local data:
 
-The npm package name is `ultracode-for-codex`. Public publish metadata lives in
-`package.json`, and `prepublishOnly` runs the full verification suite before
-`npm publish`.
+```gitignore
+.ultracode-for-codex/
+```
+
+## Troubleshooting
 
-Check the package before publishing:
+If Codex does not recognize `$ultracode-for-codex`, confirm that the skill
+folder exists:
 
 ```bash
-npm run publish:dry-run
+ls "${CODEX_HOME:-$HOME/.codex}/skills/ultracode-for-codex"
 ```
 
-Publish after `npm login`:
+If `npm exec -- ultracode-for-codex` fails, confirm the package is installed:
 
 ```bash
-npm run publish:npm
+npm ls ultracode-for-codex
 ```
 
-For supported CI/CD environments, provenance is available as an explicit opt-in:
+If a CLI workflow is still running, list local jobs:
 
 ```bash
-npm run publish:npm:provenance
+npm exec -- ultracode-for-codex jobs --cwd /path/to/project
 ```
 
-Optional live smoke against the local Codex CLI:
+## For Maintainers
+
+Common source checkout commands:
 
 ```bash
-ULTRACODE_LIVE_SMOKE=1 npm run smoke:live
+npm install
+npm test
+npm run test:e2e:ultracode-for-codex
+npm run test:all
+npm run pack:ultracode-for-codex
 ```
 
-Useful local run:
+Check the publish payload:
 
 ```bash
-npm run build
-node dist/cli.js run --accept-llm-guide=v1 --script-file ./workflow.js
+npm run publish:dry-run
 ```
 
-## Docs
-
-- `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.
-- `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.
+## More Documentation
+
+- `ULTRACODE_INSTALL.md`: detailed install and operating guide.
+- `skills/ultracode-for-codex/SKILL.md`: Codex-native orchestration behavior.
+- `skills/ultracode-for-codex/references/progress-visuals.md`: progress display
+  examples.
+- `skills/ultracode-for-codex-cli/SKILL.md`: CLI runtime behavior.

package/ULTRACODE_INSTALL.md

@@ -22,7 +22,7 @@ Skill commands:
 
 The packaged `settings.json` defaults CLI workflow runs to OS background
 execution with result and progress files under
-`.ultracode-for-codex/background/{jobId}`.
+`${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}/background/{jobId}`.
 
 Production surface:
 
@@ -99,13 +99,19 @@ 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.
+work. `task` starts with an LLM planner, executes phase by phase, runs multiple
+focused Codex subagents in parallel within each phase by default, and 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.
+
+`code-review` uses a specialized review harness. It collects bounded repository
+evidence, selects active review lenses, runs one finder per lens in parallel,
+verifies every emitted candidate with a candidate-scoped subagent, optionally
+runs an `xhigh` sweep, then synthesizes final findings by verified candidate
+index. The final JSON includes `findings`, `provenance`, `synthesis`, and
+`stats`.
 
 Settings defaults:
 
@@ -118,7 +124,7 @@ Settings defaults:
     "retryLimit": 0,
     "timeoutMs": 0,
     "background": {
-      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "runDir": "{stateRoot}/background/{jobId}",
       "resultFile": "result.json",
       "progressFile": "progress.jsonl",
       "metadataFile": "metadata.json",
@@ -145,7 +151,9 @@ Useful controls:
 - JSONL records include `kind`, `version`, `event`, `status`, and `summary`;
   agent records also include stable agent identity and label fields.
 - Built-in `task` and `code-review` emit `workflow.plan.ready` as a planning
-  snapshot, not a promise that every later phase is already known.
+  snapshot, not a promise that every later phase is already known. In
+  `code-review`, later verifier agents are discovered after finder agents emit
+  candidates.
 - `workflow.phase.planned` is emitted immediately before each phase starts and
   carries that phase's current planned agent role labels. Each
   `workflow.phase.started` record repeats the same role labels when the phase
@@ -158,6 +166,9 @@ Useful controls:
   acting on it.
 - Press `Ctrl-C` once to cancel the running workflow.
 - Use `--retry-limit <n>` to retry failed runs in the same process.
+- Use `--resume-from-run-id <runId>` to resume a completed local workflow from
+  preserved runtime state. Resume always uses the original persisted workflow
+  source; without `--args`, it also reuses the original args.
 - `--timeout-ms 0` waits for completion, cancellation, or app-server exit.
   Positive values opt into a workflow deadline and per-agent silence budget;
   that budget is not divided by the retry budget.
@@ -180,19 +191,26 @@ Useful controls:
 - Strip direct provider credentials from child CLI environments.
 - Run Codex subagents against the requested workflow cwd and provide bounded
   read-only workspace tools for text file reads and directory listings.
-- Built-in `task` and `code-review` add deterministic workspace context to
-  planner-selected phase-wise parallel subagents, then synthesize each phase and
-  the final result.
+- Built-in `task` adds deterministic workspace context to planner-selected
+  phase-wise parallel subagents. Built-in `code-review` uses deterministic
+  review evidence, allowed evidence refs, dynamic lenses, candidate verification,
+  and bounded final synthesis.
 - Install consumers from a packaged artifact.
 - Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
   Local runtime state may still contain runtime-owned
   `transcriptDir`, `scriptPath`, and result files.
-- `resumeFromRunId` remains a runtime-internal same-session capability; the
-  CLI uses retry or explicit reruns for user-facing recovery.
+- `--resume-from-run-id` reads the preserved runtime script, result record, and
+  completed journal from the workflow state directory under
+  `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`; completed agent
+  results are reused only when their runtime-owned call keys still match. The
+  script path, script source identity, and inherited args must match the
+  completed journal.
 - Use `isolation: "worktree"` only in git repositories with at least one commit.
   Isolated worktrees are intentionally preserved for review, including clean
   worktrees.
-- Treat `.ultracode-for-codex` workflow state as sensitive local data.
+- Treat workflow state under `${ULTRACODE_FOR_CODEX_HOME:-~/.ultracode-for-codex}`
+  as sensitive local data. Project-local `.ultracode-for-codex/` directories are
+  legacy state and should stay ignored.
 
 ## First Checks After Install
 
@@ -215,5 +233,5 @@ workflow.
   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-p3b-resume-cache.md`: local resume/cache contract.
 - `docs/ultracode-p3c-worktree-isolation.md`: worktree isolation contract.