ultracode-for-codex 0.3.0 → 0.3.2

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,35 @@ npm install --save-dev ultracode-for-codex
 npm exec -- ultracode-for-codex --llm-guide
 ```
 
+Or install the CLI globally:
+
+```bash
+npm install -g ultracode-for-codex
+ultracode-for-codex --version
+ultracode-for-codex --llm-guide
+```
+
+Install the Codex skill commands from a project install:
+
+```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/"
+```
+
+Or install the skill commands from a global npm install:
+
+```bash
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+GLOBAL_NODE_MODULES="$(npm root -g)"
+cp -R "$GLOBAL_NODE_MODULES/ultracode-for-codex/skills/ultracode-for-codex" \
+  "${CODEX_HOME:-$HOME/.codex}/skills/"
+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:
 
 ```bash
@@ -29,7 +59,7 @@ Install the tarball from a target project:
 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 \
@@ -75,14 +105,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
 
@@ -155,14 +185,18 @@ continue other tasks and inspect the job later with `status`, `logs`, or
 - 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
 
@@ -171,7 +205,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
@@ -235,8 +269,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,13 +1,27 @@
 # 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:
@@ -43,18 +57,21 @@ For source-checkout validation, install the generated tarball instead:
 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 \
@@ -81,11 +98,11 @@ npm exec -- ultracode-for-codex jobs --cwd /path/to/project
 npm exec -- ultracode-for-codex archive <jobId> --cwd /path/to/project
 ```
 
-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.
+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.
@@ -153,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
@@ -192,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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.3.0",
-  "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
+  "version": "0.3.2",
+  "description": "Run Codex-native Ultracode orchestration with an optional local CLI runtime.",
   "keywords": [
     "codex",
     "workflow",
@@ -41,6 +41,7 @@
     "dist/codex/",
     "dist/runtime/",
     "skills/ultracode-for-codex/",
+    "skills/ultracode-for-codex-cli/",
     "settings.json",
     "README.md",
     "docs/provenance-audit.md",

package/skills/ultracode-for-codex/SKILL.md

@@ -1,139 +1,117 @@
 ---
 name: ultracode-for-codex
-description: Operate, package, validate, or update the Ultracode for Codex npm runtime. Use when installing or running local workflows, checking runtime boundaries, packaging release tarballs, updating docs, or maintaining the companion Codex skill.
+description: Run Ultracode for Codex in Codex-native mode, with the main Codex context planning phases, spawning parallel subagents, synthesizing results, and showing progress directly in the chat.
 ---
 
 # Ultracode for Codex
 
 ## Core Rule
 
-Treat the npm package as the runtime artifact. This skill is only a companion
-guide for Codex agents. Runtime authority remains in the `ultracode-for-codex`
-binary, tests, package exports, journal layer, and workflow runtime code.
-
-Workflow execution runs through the local CLI command. Progress,
-cancellation, permission review, retry, and result projection stay in that
-command process. `settings.json` defaults runs to OS background execution; use
-that path for long Codex-launched work so Codex can keep doing other tasks and
-inspect the background job later. Attached runs stream stderr JSONL for
-Codex-readable status, while stdout remains the final workflow result JSON.
-
-The default Ultracode work shape is phase-wise parallel execution: built-in
-`task` and `code-review` first call a planner agent, then execute each planned
-phase with parallel focused subagents by default, followed by phase and final
-synthesis. A single-agent path is reserved for cases where the planner judges
-parallel execution risky or wasteful.
-Planner guidance includes classify-and-act, fan-out-and-synthesize,
-adversarial verification, generate-and-filter, tournament, and loop-until-done
-patterns so workflow shape can follow the task instead of a fixed template.
-
-## Install And Run
-
-Use the npm package for consumer installs.
-
-```bash
-npm install --save-dev ultracode-for-codex
-npm exec -- ultracode-for-codex --llm-guide
-npm exec -- ultracode-for-codex run \
-  --accept-llm-guide=v1 \
-  --cwd /path/to/project \
-  --script-file .codex/workflows/review.js \
-  --args '{"prompt":"review the current change"}'
-```
+This skill is the primary Codex-native Ultracode command. Treat the current
+Codex main context as the orchestrator. Plan adaptive phases, spawn focused
+subagents directly from Codex, synthesize phase outputs, and keep the user
+informed in the chat.
 
-For source-checkout validation before publish:
+Use the CLI runtime only when the user explicitly asks for `$ultracode-for-codex-cli`,
+CLI execution, background jobs, packaging, publish preparation, installed
+runtime validation, or reproducible local runtime artifacts.
 
-```bash
-npm run pack:ultracode-for-codex
-npm install --save-dev ./artifacts/ultracode-for-codex-<version>.tgz
-```
+## Required Capability Surface
 
-CLI behavior:
-
-- `--version` or `-v` prints the installed package version;
-- default execution is `background`; stdout contains a launch record with
-  `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`;
-- background jobs can be inspected with `status`, waited with `wait`, read with
-  `logs` and `result`, and cancelled with `cancel`;
-- background jobs can be enumerated with `jobs` or `list`, and exported without
-  deletion with `archive` or `export`;
-- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
-  provide focused foreground checks;
-- attached execution is available with `--execution attached` when the caller
-  should stay connected until completion;
-- attached progress prints to stderr as JSONL by default;
-- attached final workflow result prints as JSON to stdout;
-- JSONL records include `kind`, `version`, `event`, `status`, and `summary`,
-  with agent identity and label fields on agent records;
-- 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 phase-level agent
-  counts and angles, then `workflow.review.recommended` asks the current
-  session LLM to critically re-check the final result before acting on it;
-- `Ctrl-C` cancels the active attached workflow;
-- `--retry-limit <n>` retries 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,
-  and that budget is not divided by the retry budget.
-- `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
-- `--progress plain` switches to human-readable progress lines.
-- background file locations are controlled by `workflow.background` in
-  `settings.json`.
-
-## Runtime Boundaries
-
-- Use Codex app-server over stdio as the production backend.
-- Keep direct provider credentials out of Codex child process environments.
-- Codex subagents run against the requested workflow cwd and have bounded
-  read-only workspace tools for text file reads and directory listings.
-- Built-in `task` and `code-review` inject deterministic workspace context into
-  planner-selected phase-wise parallel subagents.
-- Keep workflow execution local and command-owned; settings default to OS
-  background execution so long runs can keep waiting while Codex does other
-  work.
-- Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
-- Treat `.ultracode-for-codex` workflow state as sensitive local data.
-- Keep `resumeFromRunId` runtime-internal unless cross-process resume
-  gets an explicit durable design.
-- Use `isolation: "worktree"` only inside a git repo with at least one commit;
-  isolated worktrees are intentionally preserved for review, including clean
-  worktrees.
-
-## Packaging And Verification
-
-For source checkout changes, run the narrowest relevant check first, then a
-release-level check before handoff:
-
-```bash
-npm test
-npm run test:e2e:ultracode-for-codex
-npm run test:all
-```
+Use Codex subagent tools for delegated work. If subagent tools are not visible,
+search for the multi-agent tools first. If no subagent surface is available,
+state that native parallel orchestration is unavailable in this session and
+continue with the best single-context workflow.
 
-Build an installable artifact with:
+Do not make the CLI process the default orchestrator for this skill. The npm
+runtime remains available through `$ultracode-for-codex-cli`, but this command's
+value is high-visibility orchestration in the main context.
 
-```bash
-npm run pack:ultracode-for-codex
-```
+## Native Workflow
 
-Check the npm publish payload with:
+1. Identify the user goal, scope, constraints, likely completion condition, and
+   whether the work is review, implementation, planning, verification, or mixed.
+2. Design only the next useful phase when later phases depend on earlier
+   results. A first plan may be partial.
+3. Before each phase starts, show a compact phase plan in the chat:
 
-```bash
-npm run publish:dry-run
+```text
+Phase Inspect - 3 agents
+- Runtime contracts: verify the active execution path and failure semantics.
+- UX/progress: check visibility, summaries, and user-facing wording.
+- Tests/package: check coverage, package contents, and install behavior.
 ```
 
-Publish after npm login with:
-
-```bash
-npm run publish:npm
+4. Spawn independent phase agents in parallel by default. Use a single agent
+   only when parallel work is risky, wasteful, or blocked by a strictly
+   sequential dependency.
+5. Keep subagent prompts concrete and bounded. Give each agent a distinct angle,
+   expected output shape, and file or responsibility boundary when relevant.
+6. While agents run, do non-overlapping main-context work such as deterministic
+   file inspection, test execution, or integration planning.
+7. As agents complete, report progress with a visual snapshot rather than a
+   dense sentence. Use the Default Live Snapshot golden shape from
+   `references/progress-visuals.md` by default. Select task-specific additions
+   from the Situation Choice Matrix in that reference. Within one user
+   request, keep a cumulative ledger: do not remove completed rows from later
+   snapshots; update their status and append newly discovered work below them.
+
+```text
+Phase E2E Validate
+
+  + Native routing review        done      34s
+  + CLI package review           done      48s
+
+  > npm-exec-run-shim            running   1/2 checks
+  > skill-copy-detection         running   3/6 files
+
+Agents 2 completed | 2 running
+Checks 5 passed | 0 failed | 2 running
+Elapsed 1m 12s
 ```
 
-When architecture, runtime boundaries, package exports, or release scope
-changes, update active docs such as `README.md`, `ULTRACODE_INSTALL.md`, and
-`IMPLEMENTATION_MAP.html`.
+8. Synthesize each phase before deciding the next phase. Preserve disagreement,
+   uncertainty, material risks, and exact evidence.
+9. After the final synthesis, include the Completion Impact Summary and
+   Plan-Style Result Summary golden shapes from `references/progress-visuals.md`,
+   followed by a short phase/agent summary.
+10. Recommend that the current session LLM critically re-check the final result
+    before the user relies on it, especially for code, security, release, or
+    architecture decisions.
+
+## Planning Heuristics
+
+Default to phase-wise parallel execution. Useful patterns include:
+
+- classify-and-act: classify request type, risk, or repo area before choosing
+  the phase shape;
+- fan-out-and-synthesize: split independent lenses across parallel agents, then
+  merge evidence;
+- adversarial verification: assign at least one agent to challenge correctness,
+  security, assumptions, or test adequacy;
+- generate-and-filter: create candidate approaches or fixes, then select by
+  evidence and constraints;
+- tournament: compare competing alternatives when the best path is unclear;
+- loop-until-done: iterate repair and verification only when there is a clear
+  stop condition.
+
+For code review, common parallel angles are runtime correctness,
+security/capability boundaries, API/CLI contracts, persistence/retry/cancel
+behavior, user-visible progress, package contents, and test coverage.
+
+For implementation, split by disjoint write ownership where possible. Tell
+subagents they are not alone in the codebase and must not revert unrelated or
+parallel edits.
+
+## Output Contract
+
+Keep progress visible but concise. Prefer stable visual summaries over prose-only
+status sentences. Use `references/progress-visuals.md` for the golden examples.
+The final answer should include:
+
+- the completed result or findings;
+- evidence and verification performed;
+- a phase/agent summary;
+- residual risk or unverified items;
+- a critical re-check recommendation for the current session LLM when the result
+  will drive action.

package/skills/ultracode-for-codex/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Ultracode for Codex"
-  short_description: "Operate the Ultracode for Codex npm runtime safely."
-  default_prompt: "Use the Ultracode for Codex npm package as the runtime and follow its local CLI boundaries."
+  short_description: "Run Codex-native phase-wise parallel orchestration."
+  default_prompt: "Use the Codex main context as the Ultracode orchestrator, plan adaptive phases, spawn focused parallel subagents, synthesize results, and keep progress visible."

package/skills/ultracode-for-codex/references/progress-visuals.md

@@ -0,0 +1,418 @@
+# Progress Visuals
+
+Use these golden examples for Codex-native Ultracode progress updates. The goal
+is fast visual parsing in chat while staying portable across terminals and
+renderers. Prefer ASCII symbols and short labels.
+
+## Research Pattern Map
+
+These patterns are adapted from established CLI/TUI conventions:
+
+- multi-task progress: Rich-style multiple task rows with progress metadata;
+- test progress: pytest-style progress/count/timing summaries;
+- async build logs: Docker BuildKit-style numbered steps and plain progress;
+- folded details: GitHub Actions-style grouped log sections;
+- change plans: Terraform-style add/update/keep/destroy action symbols;
+- rollout watches: Kubernetes rollout-style "N out of M" convergence messages;
+- audit tables: npm audit-style severity/package/path/remediation columns.
+
+Map those patterns to Ultracode situations instead of using one universal
+status format.
+
+## Situation Choice Matrix
+
+Choose one row per task situation. Each row has at most three user-facing
+shapes: primary, support, and finish. Do not present profile names to the user.
+If a task mixes situations, choose the dominant row for live progress and borrow
+at most one support shape from another row.
+
+| Situation | Primary | Support | Finish |
+| --- | --- | --- | --- |
+| Ordinary or mixed work | Default Live Snapshot | Verification Gate Matrix | Plan-Style Result Summary |
+| Design or planning | Decision Tournament | Context Coverage Matrix | User Decision Gate |
+| Implementation | Implementation Work Ledger | Verification Gate Matrix | Completion Impact Summary |
+| Review or audit | Agent Lens Matrix | Context Coverage Matrix | Evidence To Finding Trace |
+| Release or install | Artifact Inventory | Rollout Or Convergence Watch | Risk Or Audit Table |
+| Retry, cancellation, or long-running work | Recovery Ledger | Resource Budget Snapshot | Rollout Or Convergence Watch |
+
+Phase Plan Preview is baseline behavior before a phase starts, not an extra
+choice. Long Async Timeline is only a temporary diagnostic appendix when the
+user explicitly asks to debug detailed event order.
+
+## Cumulative Ledger Rule
+
+Within one user request, progress snapshots are cumulative. Do not let completed
+work scroll out of the next snapshot just because new work starts. Keep completed
+rows, update their status, and append newly discovered work below them. This
+makes the current answer self-contained even if the user only sees the latest
+snapshot.
+
+```text
+Phase Commit Prep
+
+  + README install flow          done      local + global skill install
+  + Registry/install check       done      <version> published and installed
+  + Verification                 done      npm run test:all
+
+  > Commit                       running   staging release changes
+  - Push                         queued    origin/main
+
+Checks 3 passed | 0 failed | 2 running/queued
+Next: commit release changes
+```
+
+Use `+` for completed work, `>` for running work, `-` for queued work, and `!`
+for blocked or failed work. Keep earlier completed rows visible in every later
+snapshot for the same request.
+
+## Default Live Snapshot
+
+Use this for ordinary phase progress. It is inspired by test-runner summaries:
+completed work is listed first, active work is visually distinct, and totals are
+grouped at the bottom.
+
+```text
+Phase E2E Validate
+
+  + Native routing review        done      34s
+  + CLI package review           done      48s
+
+  > npm-exec-run-shim            running   1/2 checks
+  > skill-copy-detection         running   3/6 files
+
+Agents 2 completed | 2 running
+Checks 5 passed | 0 failed | 2 running
+Elapsed 1m 12s
+```
+
+Keep each row to one line when possible.
+
+## Dense Meter Snapshot
+
+Use this when the work is count-heavy and the user needs ratios.
+
+```text
+Progress Snapshot  main c3734d8
+
+Native routing       ####################----  5 / 6 checks
+CLI package E2E      ########################  passed
+Skill install check  ################--------  4 / 6 files
+Docs contract        ############------------  2 / 4 sections
+
+Elapsed 1m 42s   Next: npm exec run shim check
+```
+
+Use fixed-width bars only when the denominator is meaningful. Do not invent a
+percentage for semantic work that cannot be counted.
+
+## Long Async Timeline
+
+Use this for long-running parallel work where event order matters.
+
+```text
+#1 [plan] classify task shape
+#1 DONE 0.8s
+
+#2 [phase:inspect] spawn 2 review agents
+#2 running 2 agents
+
+#3 [agent:native-routing] verify skill split
+#3 DONE 34.1s
+
+#4 [agent:cli-package] verify installed E2E
+#4 DONE 48.7s
+
+#5 [synthesis] merge findings
+#5 running
+```
+
+Use this sparingly in chat. It is best when the user asks for detailed live
+process visibility.
+
+## Completion Impact Summary
+
+Use this in final or phase-completion reporting when files changed.
+
+```text
+Change Impact
+
+  skills/ultracode-for-codex/SKILL.md           | 200 +++++++++++---------
+  skills/ultracode-for-codex-cli/SKILL.md       | 136 +++++++++++++
+  scripts/e2e-installed-ultracode-for-codex.mjs |  78 +++++++-
+  README.md                                     |  62 ++++--
+
+  8 files changed, 295 insertions(+), 201 deletions(-)
+```
+
+Prefer real `git diff --stat` output when available.
+
+## Plan-Style Result Summary
+
+Use this with the impact summary to explain what changed conceptually.
+
+```text
+Execution Result
+
+  + add     ultracode-for-codex-cli skill command
+  ~ update  ultracode-for-codex native orchestration contract
+  ~ update  installed E2E to cover npm exec run
+  = keep    CLI runtime command surface
+
+Result: 1 added, 2 updated, 1 kept
+Risk: Codex skill reload cannot be forced inside the current session
+```
+
+Use `+ add`, `~ update`, `= keep`, and `! risk` consistently.
+
+## Folded Detail Summary
+
+Use this when the top-level result is enough and details should remain compact.
+
+```text
+E2E Validation Summary
+
+[passed] Native skill routing
+[passed] CLI package runtime
+[passed] npm exec run shim
+[passed] CODEX_HOME skill copy
+
+Details
+  native-routing-review     5 findings, 0 failures
+  cli-package-review        7 findings, 0 failures
+  npm test:all              35 tests passed
+```
+
+This is best for final handoff or after multiple agents have returned.
+
+## Building Block Examples
+
+Use these shapes as building blocks selected by the Situation Choice Matrix
+above. Do not present this full list as user-facing choices.
+
+### Phase Plan Preview
+
+Use this immediately before spawning agents for a phase.
+
+```text
+Phase Inspect - planned fan-out
+
+  - Runtime contracts     check execution authority and failure semantics
+  - UX/progress           inspect visible status and completion summaries
+  - Tests/package         verify E2E, tarball, and installed skill contents
+
+Parallelism: 3 agents
+Synthesis: merge material findings and decide next phase
+```
+
+### Agent Lens Matrix
+
+Use this when several agents are reviewing the same artifact from different
+angles.
+
+```text
+Review Lenses
+
+  + Runtime correctness       no material issue       workflow-runtime.ts
+  + Capability boundary       no material issue       subagent-backend.ts
+  ! User visibility           needs fix               progress visuals
+  > Package contract          running                 tarball contents
+
+Findings 1 open | 2 clear | 1 running
+Next: fix user visibility contract
+```
+
+### Implementation Work Ledger
+
+Use this when work is split into edit scopes.
+
+```text
+Implementation Ledger
+
+  + Skill routing docs         updated   skills/ultracode-for-codex
+  + CLI skill command          added     skills/ultracode-for-codex-cli
+  > E2E package checks         editing   scripts/e2e-installed-...
+  - README install flow        queued    local/global install examples
+
+Files touched 6 | Tests queued 2 | Risk low
+```
+
+### Verification Gate Matrix
+
+Use this after tests, package checks, reviews, or publish dry-runs.
+
+```text
+Verification Gates
+
+  + unit/integration           passed    35 tests
+  + installed E2E              passed    fake Codex boundary
+  + package validation         passed    35 files in tarball
+  + publish dry-run            passed    would publish <version>
+
+Gates 4 passed | 0 failed | 0 skipped
+Residual: live Codex smoke remains opt-in
+```
+
+### Decision Tournament
+
+Use this when comparing approaches before implementation.
+
+```text
+Decision Tournament
+
+  A  CLI orchestration         rejected  low visibility
+  B  Native main orchestration selected  highest chat visibility
+  C  Hybrid auto-router        deferred  more moving parts
+
+Winner: B
+Reason: best fit for Codex-native progress and direct subagent control
+```
+
+### Blocked Or Risk Snapshot
+
+Use this when a dependency, permission, failing gate, or missing capability
+blocks progress.
+
+```text
+Blocked Snapshot
+
+  + Package contents           verified
+  ! Native subagent surface    blocked   multi-agent tools unavailable
+  - Parallel review            paused    needs subagent surface
+
+Blocker: native parallel orchestration unavailable in this session
+Fallback: continue single-context review and record residual risk
+```
+
+### Retry Or Recovery Ledger
+
+Use this for transient failures, retry loops, cancellation, or recovery.
+
+```text
+Recovery Ledger
+
+  + attempt 1                  failed    workflow_agent_stalled
+  + retry policy               applied   retry 1 / 2
+  > attempt 2                  running   narrowed review prompt
+  - synthesis                  queued    after terminal result
+
+Retries 1 used | 1 remaining
+Next: wait for attempt 2 terminal state
+```
+
+### Artifact Inventory
+
+Use this when the output is files, package artifacts, generated docs, or local
+state.
+
+```text
+Artifact Inventory
+
+  + npm tarball                artifacts/ultracode-for-codex-<version>.tgz
+  + native skill               skills/ultracode-for-codex/SKILL.md
+  + CLI skill                  skills/ultracode-for-codex-cli/SKILL.md
+  + progress examples          skills/ultracode-for-codex/references/progress-visuals.md
+
+Artifacts 4 ready | Sensitive local state not included
+```
+
+### Rollout Or Convergence Watch
+
+Use this when waiting for a target state: publish propagation, installed package
+availability, test shards, deployment checks, or background jobs.
+
+```text
+Convergence Watch
+
+  + npm registry                visible   <version> latest
+  + global CLI                  updated   /opt/homebrew/bin/ultracode-for-codex
+  > Codex skill reload          pending   next session boundary
+  - downstream smoke            queued    user project install
+
+Converged 2 / 4
+Next: verify downstream smoke after reload
+```
+
+### Risk Or Audit Table
+
+Use this for security, capability boundaries, provenance, dependency audit,
+license review, or data exposure checks.
+
+```text
+Risk Audit
+
+  severity  area                 status    evidence
+  high      provider credentials  clear     env stripping test
+  medium    local state paths     clear     .ultracode-for-codex ignored
+  low       docs ambiguity        open      install wording
+
+Open risk 1 low | Material risk 0
+Next: clarify install wording
+```
+
+### Context Coverage Matrix
+
+Use this when the quality of a result depends on which evidence was actually
+read, searched, tested, or left unverified.
+
+```text
+Context Coverage
+
+  + runtime source              read      src/runtime/workflow-runtime.ts
+  + package scripts             read      scripts/package-...
+  + installed E2E               executed  npm run test:e2e:...
+  ! live Codex smoke            skipped   opt-in local environment
+
+Coverage 3 verified | 1 residual
+Residual: live smoke remains user-triggered
+```
+
+### User Decision Gate
+
+Use this when the next step needs a product or risk choice rather than more
+execution.
+
+```text
+Decision Gate
+
+  A  Publish now                ready     all gates green
+  B  Add live smoke first       safer     needs local Codex run
+  C  Defer release              safest    no user impact yet
+
+Recommended: A
+Why: package and dry-run gates are green; live smoke is optional
+```
+
+### Resource Budget Snapshot
+
+Use this for long work where elapsed time, agent count, retry budget, or token
+budget matters.
+
+```text
+Resource Budget
+
+  agents active                3 / 6
+  retries used                 1 / 2
+  elapsed                      7m 20s
+  timeout                      none
+  token budget                 not capped
+
+Pressure: low
+Next: wait for active agents before synthesis
+```
+
+### Evidence To Finding Trace
+
+Use this when translating many observations into a smaller set of findings or
+fixes.
+
+```text
+Evidence Trace
+
+  evidence                         finding                 action
+  package files include skill refs  packaging contract ok   keep
+  npm exec run path untested        E2E gap                 add test
+  progress rows disappear           visibility gap          add ledger rule
+
+Findings 2 actionable | 1 keep
+Next: implement E2E gap and ledger rule
+```

package/skills/ultracode-for-codex-cli/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ultracode-for-codex-cli
+description: Operate, package, validate, or update the Ultracode for Codex npm CLI runtime, including background jobs, attached runs, runtime boundaries, release tarballs, and Codex skill command files.
+---
+
+# Ultracode for Codex CLI
+
+## Core Rule
+
+Use this skill for the npm package and CLI runtime surface. Runtime authority for
+this path lives in the `ultracode-for-codex` binary, tests, package exports,
+journal layer, and workflow runtime code.
+
+The default `$ultracode-for-codex` skill is Codex-native and keeps orchestration
+in the main context. This `$ultracode-for-codex-cli` skill is for explicit CLI
+runtime work: background execution, attached runs, package validation, release
+preparation, installed E2E checks, runtime-boundary checks, and local workflow
+artifacts.
+
+Workflow execution through this path runs through the local CLI command.
+Progress, cancellation, permission review, retry, and result projection stay in
+that command process. `settings.json` defaults runs to OS background execution;
+use that path for long Codex-launched CLI work so Codex can keep doing other
+tasks and inspect the background job later. Attached runs stream stderr JSONL for
+Codex-readable status, while stdout remains the final workflow result JSON.
+
+## Install And Run
+
+Use the npm package for consumer installs.
+
+```bash
+npm install --save-dev ultracode-for-codex
+npm exec -- ultracode-for-codex --llm-guide
+npm exec -- ultracode-for-codex run \
+  --accept-llm-guide=v1 \
+  --cwd /path/to/project \
+  --script-file .codex/workflows/review.js \
+  --args '{"prompt":"review the current change"}'
+```
+
+For source-checkout validation before publish:
+
+```bash
+npm run pack:ultracode-for-codex
+npm install --save-dev ./artifacts/ultracode-for-codex-<version>.tgz
+```
+
+CLI behavior:
+
+- `--version` or `-v` prints the installed package version;
+- default execution is `background`; stdout contains a launch record with
+  `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`;
+- background jobs can be inspected with `status`, waited with `wait`, read with
+  `logs` and `result`, and cancelled with `cancel`;
+- background jobs can be enumerated with `jobs` or `list`, and exported without
+  deletion with `archive` or `export`;
+- `wait --result`, `cancel --wait`, `logs --event <event>`, and `--plain`
+  provide focused foreground checks;
+- attached execution is available with `--execution attached` when the caller
+  should stay connected until completion;
+- attached progress prints to stderr as JSONL by default;
+- attached final workflow result prints as JSON to stdout;
+- JSONL records include `kind`, `version`, `event`, `status`, and `summary`,
+  with agent identity and label fields on agent records;
+- 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 phase-level agent
+  counts and angles, then `workflow.review.recommended` asks the current
+  session LLM to critically re-check the final result before acting on it;
+- `Ctrl-C` cancels the active attached workflow;
+- `--retry-limit <n>` retries 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,
+  and that budget is not divided by the retry budget.
+- `--permission ask|allow|deny` handles project/user/plugin/scriptPath reviews.
+- `--progress plain` switches to human-readable progress lines.
+- background file locations are controlled by `workflow.background` in
+  `settings.json`.
+
+## Runtime Boundaries
+
+- Use Codex app-server over stdio as the production backend.
+- Keep direct provider credentials out of Codex child process environments.
+- Codex subagents run against the requested workflow cwd and have bounded
+  read-only workspace tools for text file reads and directory listings.
+- Built-in `task` and `code-review` inject deterministic workspace context into
+  planner-selected phase-wise parallel subagents.
+- Keep workflow execution local and command-owned; settings default to OS
+  background execution so long runs can keep waiting while Codex does other
+  work.
+- Keep `journalPath`, `journal.jsonl`, and journal contents out of CLI output.
+- Treat `.ultracode-for-codex` workflow state as sensitive local data.
+- Keep `resumeFromRunId` runtime-internal unless cross-process resume gets an
+  explicit durable design.
+- Use `isolation: "worktree"` only inside a git repo with at least one commit;
+  isolated worktrees are intentionally preserved for review, including clean
+  worktrees.
+
+## Packaging And Verification
+
+For source checkout changes, run the narrowest relevant check first, then a
+release-level check before handoff:
+
+```bash
+npm test
+npm run test:e2e:ultracode-for-codex
+npm run test:all
+```
+
+Build an installable artifact with:
+
+```bash
+npm run pack:ultracode-for-codex
+```
+
+Check the npm publish payload with:
+
+```bash
+npm run publish:dry-run
+```
+
+Publish after npm login with:
+
+```bash
+npm run publish:npm
+```
+
+When architecture, runtime boundaries, package exports, or release scope
+changes, update active docs such as `README.md`, `ULTRACODE_INSTALL.md`, and
+`IMPLEMENTATION_MAP.html`.

package/skills/ultracode-for-codex-cli/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ultracode for Codex CLI"
+  short_description: "Operate the Ultracode for Codex npm CLI runtime."
+  default_prompt: "Use the Ultracode for Codex CLI runtime for explicit package, background job, validation, and release work."