ultracode-for-codex 0.2.6 → 0.3.1

package/docs/provenance-audit.md

@@ -7,7 +7,7 @@ Date: 2026-06-22
 This audit checked:
 
 - tracked repository files;
-- generated npm package contents for `ultracode-for-codex@0.2.6`;
+- generated npm package contents for `ultracode-for-codex@0.3.0`;
 - the locally installed companion Codex skill.
 
 Generated build output and package tarballs were checked as projections of the
@@ -23,7 +23,8 @@ License transition completed:
 
 - Apache-2.0 `LICENSE` file is present;
 - `package.json` and `package-lock.json` declare `Apache-2.0`;
-- package version is prepared as `0.2.6`.
+- release-candidate package version is `0.3.0`;
+- npm latest before this release remains `0.2.6`.
 
 ## Evidence
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultracode-for-codex",
-  "version": "0.2.6",
-  "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
+  "version": "0.3.1",
+  "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",
@@ -58,6 +59,7 @@
     "publish:dry-run": "npm publish --dry-run --access public",
     "publish:npm": "npm publish --access public",
     "publish:npm:provenance": "npm publish --access public --provenance",
+    "smoke:live": "node scripts/live-smoke-ultracode-for-codex.mjs",
     "test:e2e:ultracode-for-codex": "node scripts/e2e-installed-ultracode-for-codex.mjs",
     "test:all": "npm test && npm run test:e2e:ultracode-for-codex",
     "test": "npm run build && npm run verify:runtime-boundary && node --test --test-concurrency=2 test/*.test.mjs",

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

@@ -1,130 +1,114 @@
 ---
 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 `progressPath` or `resultPath` 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-0.2.6.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`;
-- 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;
-- `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.
+
+```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,125 @@
+# 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.
+
+## 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
+```
+
+Use `+` for completed items, `>` for running items, `!` for blocked or failed
+items, and `-` for queued items. 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.

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."