ultracode-for-codex 0.2.0

package/dist/settings.d.ts

@@ -0,0 +1,38 @@
+import type { ReasoningEffort, Verbosity } from './runtime/types.js';
+export type WorkflowExecutionMode = 'background' | 'attached';
+export type WorkflowProgressMode = 'jsonl' | 'plain';
+export type WorkflowPermissionPolicy = 'ask' | 'allow' | 'deny';
+export interface UltracodeSettings {
+    readonly workflow: {
+        readonly executionMode: WorkflowExecutionMode;
+        readonly progress: WorkflowProgressMode;
+        readonly permission: WorkflowPermissionPolicy;
+        readonly retryLimit: number;
+        readonly timeoutMs: number;
+        readonly background: {
+            readonly runDir: string;
+            readonly resultFile: string;
+            readonly progressFile: string;
+            readonly metadataFile: string;
+            readonly pidFile: string;
+        };
+    };
+    readonly codex: {
+        readonly reasoningEffort: ReasoningEffort;
+        readonly verbosity: Verbosity;
+    };
+}
+export declare function loadSettings(): UltracodeSettings;
+export declare function workflowDefaultExecutionMode(): WorkflowExecutionMode;
+export declare function workflowDefaultProgressMode(): WorkflowProgressMode;
+export declare function workflowDefaultPermissionPolicy(): WorkflowPermissionPolicy;
+export declare function workflowDefaultRetryLimit(): number;
+export declare function workflowDefaultTimeoutMs(): number;
+export declare function workflowBackgroundDefaults(): UltracodeSettings['workflow']['background'];
+export declare function codexDefaultReasoningEffort(): ReasoningEffort;
+export declare function codexDefaultVerbosity(): Verbosity;
+export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
+export declare function isVerbosity(value: unknown): value is Verbosity;
+export declare function isWorkflowExecutionMode(value: unknown): value is WorkflowExecutionMode;
+export declare function isWorkflowProgressMode(value: unknown): value is WorkflowProgressMode;
+export declare function isWorkflowPermissionPolicy(value: unknown): value is WorkflowPermissionPolicy;

package/dist/settings.js

@@ -0,0 +1,153 @@
+import { readFileSync } from 'node:fs';
+const SETTINGS_URL = new URL('../settings.json', import.meta.url);
+const WORKFLOW_EXECUTION_MODES = ['background', 'attached'];
+const WORKFLOW_PROGRESS_MODES = ['jsonl', 'plain'];
+const WORKFLOW_PERMISSION_POLICIES = ['ask', 'allow', 'deny'];
+const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'];
+const VERBOSITIES = ['low', 'medium', 'high'];
+let cachedSettings = null;
+export function loadSettings() {
+    if (cachedSettings)
+        return cachedSettings;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(SETTINGS_URL, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Unable to read settings.json: ${errorMessage(err)}`);
+    }
+    const root = asRecord(parsed);
+    if (!root)
+        throw new Error('settings.json must contain a JSON object.');
+    const workflow = asRecord(root?.workflow);
+    if (!workflow)
+        throw new Error('settings.json must define workflow.');
+    const background = asRecord(workflow?.background);
+    if (!background)
+        throw new Error('settings.json must define workflow.background.');
+    const codex = asRecord(root?.codex);
+    if (!codex)
+        throw new Error('settings.json must define codex.');
+    cachedSettings = {
+        workflow: {
+            executionMode: readWorkflowExecutionModeSetting(workflow?.executionMode, 'workflow.executionMode'),
+            progress: readWorkflowProgressModeSetting(workflow?.progress, 'workflow.progress'),
+            permission: readWorkflowPermissionPolicySetting(workflow?.permission, 'workflow.permission'),
+            retryLimit: readNonNegativeIntegerSetting(workflow?.retryLimit, 'workflow.retryLimit'),
+            timeoutMs: readPositiveIntegerSetting(workflow?.timeoutMs, 'workflow.timeoutMs'),
+            background: {
+                runDir: readTemplateSetting(background?.runDir, 'workflow.background.runDir', true),
+                resultFile: readRelativePathSetting(background?.resultFile, 'workflow.background.resultFile'),
+                progressFile: readRelativePathSetting(background?.progressFile, 'workflow.background.progressFile'),
+                metadataFile: readRelativePathSetting(background?.metadataFile, 'workflow.background.metadataFile'),
+                pidFile: readRelativePathSetting(background?.pidFile, 'workflow.background.pidFile'),
+            },
+        },
+        codex: {
+            reasoningEffort: readReasoningEffortSetting(codex?.reasoningEffort, 'codex.reasoningEffort'),
+            verbosity: readVerbositySetting(codex?.verbosity, 'codex.verbosity'),
+        },
+    };
+    return cachedSettings;
+}
+export function workflowDefaultExecutionMode() {
+    return loadSettings().workflow.executionMode;
+}
+export function workflowDefaultProgressMode() {
+    return loadSettings().workflow.progress;
+}
+export function workflowDefaultPermissionPolicy() {
+    return loadSettings().workflow.permission;
+}
+export function workflowDefaultRetryLimit() {
+    return loadSettings().workflow.retryLimit;
+}
+export function workflowDefaultTimeoutMs() {
+    return loadSettings().workflow.timeoutMs;
+}
+export function workflowBackgroundDefaults() {
+    return loadSettings().workflow.background;
+}
+export function codexDefaultReasoningEffort() {
+    return loadSettings().codex.reasoningEffort;
+}
+export function codexDefaultVerbosity() {
+    return loadSettings().codex.verbosity;
+}
+export function isReasoningEffort(value) {
+    return typeof value === 'string' && REASONING_EFFORTS.includes(value);
+}
+export function isVerbosity(value) {
+    return typeof value === 'string' && VERBOSITIES.includes(value);
+}
+export function isWorkflowExecutionMode(value) {
+    return typeof value === 'string' && WORKFLOW_EXECUTION_MODES.includes(value);
+}
+export function isWorkflowProgressMode(value) {
+    return typeof value === 'string' && WORKFLOW_PROGRESS_MODES.includes(value);
+}
+export function isWorkflowPermissionPolicy(value) {
+    return typeof value === 'string' && WORKFLOW_PERMISSION_POLICIES.includes(value);
+}
+function readWorkflowExecutionModeSetting(value, key) {
+    if (isWorkflowExecutionMode(value))
+        return value;
+    throw new Error(`${key} must be one of ${WORKFLOW_EXECUTION_MODES.join(', ')}.`);
+}
+function readWorkflowProgressModeSetting(value, key) {
+    if (isWorkflowProgressMode(value))
+        return value;
+    throw new Error(`${key} must be one of ${WORKFLOW_PROGRESS_MODES.join(', ')}.`);
+}
+function readWorkflowPermissionPolicySetting(value, key) {
+    if (isWorkflowPermissionPolicy(value))
+        return value;
+    throw new Error(`${key} must be one of ${WORKFLOW_PERMISSION_POLICIES.join(', ')}.`);
+}
+function readReasoningEffortSetting(value, key) {
+    if (isReasoningEffort(value))
+        return value;
+    throw new Error(`${key} must be one of ${REASONING_EFFORTS.join(', ')}.`);
+}
+function readVerbositySetting(value, key) {
+    if (isVerbosity(value))
+        return value;
+    throw new Error(`${key} must be one of ${VERBOSITIES.join(', ')}.`);
+}
+function readNonNegativeIntegerSetting(value, key) {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0)
+        return value;
+    throw new Error(`${key} must be a non-negative integer.`);
+}
+function readPositiveIntegerSetting(value, key) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0)
+        return value;
+    throw new Error(`${key} must be a positive integer.`);
+}
+function readTemplateSetting(value, key, requireJobId) {
+    const text = readNonEmptyStringSetting(value, key);
+    if (requireJobId && !text.includes('{jobId}')) {
+        throw new Error(`${key} must include {jobId}.`);
+    }
+    return text;
+}
+function readRelativePathSetting(value, key) {
+    const text = readNonEmptyStringSetting(value, key);
+    if (text.startsWith('/') || /^[A-Za-z]:[\\/]/.test(text) || text.split(/[\\/]+/).includes('..')) {
+        throw new Error(`${key} must be a relative path without parent traversal.`);
+    }
+    return text;
+}
+function readNonEmptyStringSetting(value, key) {
+    if (typeof value === 'string' && value.trim())
+        return value;
+    throw new Error(`${key} must be a non-empty string.`);
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/ultracode-install-guide.d.ts

@@ -0,0 +1,4 @@
+export declare const ULTRACODE_INSTALL_GUIDE_FILENAME = "ULTRACODE_INSTALL.md";
+export declare function readUltracodeInstallGuide(): string;
+export declare function ultracodeInstallGuidePath(): string;
+export declare function renderUltracodeInstallGuideNotice(guide?: string): string;

package/dist/ultracode-install-guide.js

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const ULTRACODE_INSTALL_GUIDE_FILENAME = 'ULTRACODE_INSTALL.md';
+export function readUltracodeInstallGuide() {
+    return readFileSync(ultracodeInstallGuidePath(), 'utf8');
+}
+export function ultracodeInstallGuidePath() {
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    return join(distDir, '..', ULTRACODE_INSTALL_GUIDE_FILENAME);
+}
+export function renderUltracodeInstallGuideNotice(guide = readUltracodeInstallGuide()) {
+    return [
+        '',
+        '=== ultracode-for-codex ULTRACODE INSTALL GUIDE START ===',
+        guide.trimEnd(),
+        '=== ultracode-for-codex ULTRACODE INSTALL GUIDE END ===',
+        '',
+        `Re-read later with: ultracode-for-codex --llm-guide`,
+        '',
+    ].join('\n');
+}

package/docs/ultracode-p3a-journal-design.md

@@ -0,0 +1,78 @@
+# Ultracode Journal Contract
+
+This is the current journal contract for the local command-owned workflow runtime.
+It is implemented in `src/runtime/workflow-journal.ts` and
+`src/runtime/workflow-runtime.ts`.
+
+## Goal
+
+Every launched workflow writes a durable
+`<transcriptDir>/journal.jsonl` ledger. The journal is the canonical runtime
+artifact for future replay/cache behavior; CLI progress is only a
+projection.
+
+P3-A is done when:
+
+- `workflow.run.started` is durably written before `taskId` and `runId` are
+  acknowledged to the caller;
+- agent started/completed/failed entries use deterministic start-order call
+  keys;
+- exactly one terminal run entry is durable before terminal workflow events and
+  result projection;
+- journal write failures fail closed with `workflow_journal_write_failed`;
+- journal readers validate schema, ordering, sequence, hash chain, task/run
+  identity, agent pairing, terminal uniqueness, and trailing partial-line
+  recovery.
+
+## Authority Model
+
+| Concept | Authority | Rule |
+| --- | --- | --- |
+| `journal.jsonl` | runtime canonical artifact | Future replay/cache reads this ledger. |
+| `WorkflowEvent` | runtime projection | CLI progress consumes this stream. |
+| `taskId`, `runId`, `seq`, `recordedAt` | runtime | Never accepted from workflow script or model output. |
+| `journalPath` | runtime internal state | Never printed in CLI output. |
+| `scriptPath`, `workflowSource`, `scriptHash` | runtime resolver | Captured in `workflow.run.started`. |
+| agent return value | runtime executor | Raw text or validated structured output. |
+
+The CLI defaults to OS background execution from `settings.json`, writing result
+and progress files under the configured background run directory. Attached
+execution prints progress to stderr as JSONL and final result JSON to stdout.
+Journal contents and `journalPath` remain internal runtime state.
+
+## Ordering
+
+Launch ordering:
+
+1. Normalize and validate workflow input.
+2. Resolve source, permission, script hash, and transcript directory.
+3. Create the transcript directory.
+4. Append and durably flush `workflow.run.started`.
+5. Register the task, emit `workflow.started`, and start execution.
+
+Agent ordering:
+
+1. Reserve `agentIndex`, `agentId`, `previousAgentCallKey`, and `agentCallKey`
+   before the first await.
+2. Append and flush `workflow.agent.started`.
+3. Emit `workflow.agent.started`.
+4. Execute Codex subagent with stall retry and structured-output validation.
+5. Append and flush exactly one agent final entry.
+6. Emit the matching final event.
+
+Terminal ordering:
+
+1. Create or reuse one terminal finalizer.
+2. Normalize result or failure payload.
+3. Append and flush terminal run entry.
+4. Emit `workflow.completed` or `workflow.failed`.
+5. Write/project the terminal result when successful.
+
+## Verification
+
+- `test/workflow-journal.test.mjs` verifies stable JSON, writer durability, and
+  reader validation.
+- `test/workflow-runtime.test.mjs` verifies direct runtime launch, failure,
+  retry, cancel, resume/cache, and worktree paths.
+- `scripts/e2e-installed-ultracode-for-codex.mjs` verifies the packaged CLI
+  against a fake Codex app-server boundary.

package/docs/ultracode-p3b-resume-cache.md

@@ -0,0 +1,43 @@
+# Ultracode Resume Cache Contract
+
+This is the current same-session resume/cache contract. It builds on
+`docs/ultracode-p3a-journal-design.md`.
+
+## Scope
+
+Resume/cache is runtime-internal and same-session. User-facing recovery uses
+same-run retry or explicit CLI reruns.
+
+## Rules
+
+- `resumeFromRunId` accepts only workflow `runId` values already known by the
+  current `WorkflowTaskRegistry`.
+- Running source runs fail with `workflow_resume_running`.
+- Completed agent prefixes are reused only when the current `agentCallKey`
+  matches the source journal prefix.
+- The first changed or new agent call and every suffix call reruns.
+- Cache hits emit `workflow.agent.completed` with `cached: true` and zero usage
+  for the current run.
+- Resumed runs write their own journal entries.
+
+`agentCallKey` is derived from previous key, prompt, and stable semantic opts:
+
+```text
+sha256(previousAgentCallKey + "\0" + prompt + "\0" + stableJson(opts))
+```
+
+Semantic opts include schema, model, effort, isolation, and agent type. Display
+values such as label and phase stay outside the cache identity.
+
+## Verification
+
+- `test/workflow-runtime.test.mjs` covers exact cache hits and retry/cancel
+  interactions.
+- `test/workflow-journal.test.mjs` validates the journal reader used to derive
+  cache entries.
+
+Realization:
+
+- `mock`: direct runtime tests use a fake subagent backend.
+- `boundary_stub`: packaged CLI E2E uses a fake Codex app-server for CLI
+  execution paths.

package/docs/ultracode-p3c-worktree-isolation.md

@@ -0,0 +1,60 @@
+# Ultracode Worktree Isolation Contract
+
+This is the current contract for `agent(..., { isolation: "worktree" })`.
+
+## Goal
+
+Worktree isolation is an opt-in local isolation mode for subagents that need
+workspace writes while keeping the source checkout reviewable.
+
+P3-C is done when:
+
+- the runtime creates a detached git worktree before the backend call;
+- the backend turn runs with that worktree as its workspace;
+- unchanged isolated worktrees are removed after the agent finishes;
+- changed or unsafe-to-clean worktrees are preserved for review;
+- `semanticOpts.isolation` participates in the agent cache key.
+
+## Authority Model
+
+| Concept | Authority | Rule |
+| --- | --- | --- |
+| isolation request | workflow script | Only `isolation: "worktree"` is accepted. |
+| worktree path | runtime | Runtime creates paths outside the source repo working tree. |
+| backend cwd | runtime request packet | Subagent backend executes the turn in `worktreePath`. |
+| changed/unchanged decision | runtime git status | `git status --porcelain --untracked-files=all --ignored=matching` decides preserve vs cleanup. |
+| preserved path projection | runtime event | Changed or unsafe-to-clean worktrees are surfaced on agent final events. |
+
+The accepted isolation values are `"none"` and `"worktree"`; any other value
+fails as invalid workflow input.
+
+## Worktree Location
+
+Worktrees are created as siblings of the git root:
+
+```text
+<parent-of-git-root>/.ultracode-for-codex-worktrees/<repo-slug>-<repo-hash>/<runId>/<agentId>
+```
+
+The worktree is detached at `HEAD`; uncommitted source repo changes are not
+copied into the isolated worktree.
+
+## Lifecycle
+
+1. Validate `agent()` options and include `isolation: "worktree"` in
+   `semanticOpts`.
+2. Append `workflow.agent.started`.
+3. Create a detached git worktree for the agent.
+4. Pass `worktreePath` to the subagent backend and append path-free worktree
+   context to the backend prompt.
+5. Inspect worktree status after the attempt settles.
+6. Remove clean worktrees.
+7. Preserve changed, stalled, aborted, status-unavailable, or cleanup-failed
+   worktrees and surface them on the agent final event.
+
+## Verification
+
+- `test/codex-isolation.test.mjs` verifies Codex backend request projection.
+- `test/workflow-runtime.test.mjs` verifies changed worktree preservation.
+- `scripts/e2e-installed-ultracode-for-codex.mjs` verifies packaged CLI workflow
+  execution through the fake Codex app-server boundary.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "ultracode-for-codex",
+  "version": "0.2.0",
+  "description": "Run local Codex-backed workflows from a command-owned CLI runtime.",
+  "keywords": [
+    "codex",
+    "workflow",
+    "cli",
+    "automation",
+    "subagents"
+  ],
+  "homepage": "https://github.com/kangminlee-maker/ultracode-for-codex#readme",
+  "bugs": {
+    "url": "https://github.com/kangminlee-maker/ultracode-for-codex/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kangminlee-maker/ultracode-for-codex.git"
+  },
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "ultracode-for-codex": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/cli.js",
+    "./ultracode-install-guide": "./dist/ultracode-install-guide.js",
+    "./settings": "./dist/settings.js"
+  },
+  "files": [
+    "ULTRACODE_INSTALL.md",
+    "postinstall.mjs",
+    "dist/cli.js",
+    "dist/cli.d.ts",
+    "dist/ultracode-install-guide.js",
+    "dist/ultracode-install-guide.d.ts",
+    "dist/settings.js",
+    "dist/settings.d.ts",
+    "dist/codex/",
+    "dist/runtime/",
+    "skills/ultracode-for-codex/",
+    "settings.json",
+    "README.md",
+    "docs/ultracode-p3a-journal-design.md",
+    "docs/ultracode-p3b-resume-cache.md",
+    "docs/ultracode-p3c-worktree-isolation.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && chmod 755 dist/cli.js",
+    "verify:runtime-boundary": "node scripts/verify-runtime-boundary.mjs",
+    "prepack": "npm run build && npm run verify:runtime-boundary",
+    "postinstall": "node postinstall.mjs",
+    "prepublishOnly": "npm run test:all",
+    "pack:ultracode-for-codex": "node scripts/package-ultracode-for-codex.mjs",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "publish:npm": "npm publish --access public",
+    "publish:npm:provenance": "npm publish --access public --provenance",
+    "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",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "run": "npm run build && node dist/cli.js run --accept-llm-guide=v1"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "npm@11.12.1"
+}

package/postinstall.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+try {
+  const packageRoot = dirname(fileURLToPath(import.meta.url));
+  const guide = readFileSync(join(packageRoot, 'ULTRACODE_INSTALL.md'), 'utf8');
+  process.stdout.write([
+    '',
+    '=== ultracode-for-codex ULTRACODE INSTALL GUIDE START ===',
+    guide.trimEnd(),
+    '=== ultracode-for-codex ULTRACODE INSTALL GUIDE END ===',
+    '',
+    'Re-read later with: ultracode-for-codex --llm-guide',
+    '',
+  ].join('\n'));
+} catch (err) {
+  process.stderr.write(
+    `ultracode-for-codex postinstall failed to read ULTRACODE_INSTALL.md: ${err instanceof Error ? err.message : String(err)}\n`,
+  );
+  process.exitCode = 1;
+}

package/settings.json

@@ -0,0 +1,20 @@
+{
+  "workflow": {
+    "executionMode": "background",
+    "progress": "jsonl",
+    "permission": "ask",
+    "retryLimit": 0,
+    "timeoutMs": 180000,
+    "background": {
+      "runDir": ".ultracode-for-codex/background/{jobId}",
+      "resultFile": "result.json",
+      "progressFile": "progress.jsonl",
+      "metadataFile": "metadata.json",
+      "pidFile": "pid"
+    }
+  },
+  "codex": {
+    "reasoningEffort": "xhigh",
+    "verbosity": "medium"
+  }
+}

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

@@ -0,0 +1,102 @@
+---
+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.
+---
+
+# 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.
+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-0.2.0.tgz
+```
+
+CLI behavior:
+
+- default execution is `background`; stdout contains a launch record with
+  `jobId`, `pid`, `resultPath`, `progressPath`, `metadataPath`, and `pidPath`;
+- attached execution is available with `--execution attached`;
+- 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;
+- `Ctrl-C` cancels the active attached workflow;
+- `--retry-limit <n>` retries failed workflows inside the same process;
+- `--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.
+- Keep workflow execution local and command-owned; settings default to OS
+  background execution and `--execution attached` keeps the process connected
+  until completion.
+- 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;
+  changed or unsafe worktrees are intentionally preserved for review.
+
+## 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/agents/openai.yaml

@@ -0,0 +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."