---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-oracle-packx-runbook"
title: "Oracle and PackX execution runbook"
---

# Oracle and PackX execution runbook

You are a PIPELINE EXECUTOR. Your job is: packx bundle -> `mcp__oracle__consult` -> read output.log -> summarize Oracle's answer -> optionally commit Oracle-driven implementation changes when the user explicitly asks.

Do not answer the user's question from your own code research. Use local inspection only to build an excellent bundle and prompt. The point of this skill is to spend Oracle's expensive intelligence on high-leverage design, implementation, and review output.

## Non-Negotiable Runtime Mode

Oracle MUST always run through the browser engine using the remote browser configuration in `~/.oracle/config.json`. Treat this as a hard stop before every consult call, including follow-up calls.

- Every `mcp__oracle__consult` call MUST set `engine: "browser"`.
- Never use `engine: "api"` and never omit `engine`; the API engine's `OPENAI_API_KEY` failure is a caller bug, not a credential blocker.
- Never switch to API mode because it seems faster, because browser mode timed out, because a smaller/follow-up prompt is being sent, or because a specific model label looks API-only.
- If a planned Oracle call object contains `engine: "api"` or lacks `engine: "browser"`, discard that call object before invoking the tool and rebuild it in browser mode.
- Model choice must be expressed through browser-compatible fields such as `browserModelLabel` and `browserThinkingTime`; do not use API credentials, API model IDs, or API-engine shortcuts.
- Do not pass ad hoc remote host, token, profile, or browser-routing overrides. Let Oracle read `~/.oracle/config.json`, which owns the remote browser endpoint.
- If the MCP surface is unavailable, the CLI Oracle recovery path MUST use `oracle --engine browser ...` and the same `~/.oracle` config. Do not add API flags or environment-key workarounds.
- If any Oracle attempt reports `Missing OPENAI_API_KEY`, immediately retry in browser mode using the `~/.oracle` config instead of asking the user for a key.

## ChatGPT Intelligence Setting

oracle-packx is a text/code reasoning workflow, not image generation. Use
ChatGPT **Pro Extended** for every `oracle-packx` consult.

Critical rules:

- Every `mcp__oracle__consult` call in this skill must include
  `browserThinkingTime: "extended"`.
- Keep `browserModelLabel: "Latest"` and `model: "gpt-5.5-pro"` unless the user
  explicitly asks for a different browser model.
- Never use `browserThinkingTime: "instant"` for packx, planning, review,
  architecture, debugging, or code-analysis consults.
- Instant is reserved for ChatGPT **Create image** / `imagine` runs only.
- If the visible ChatGPT Intelligence pill says `Instant` before a packx run,
  change it back through Oracle by sending `browserThinkingTime: "extended"`;
  do not rely on the current UI state.

Good call shape:

```text
mcp__oracle__consult({
  prompt: "[{slug}]\n\n{question}",
  files: ["~/.oracle/bundles/{slug}.txt"],
  engine: "browser",
  model: "gpt-5.5-pro",
  browserModelLabel: "Latest",
  browserThinkingTime: "extended",
  slug: "{slug}"
})
```

Bad call shape:

```text
browserThinkingTime: "instant"  # image generation only; wrong for oracle-packx
```

## Operating Principle

Oracle is expensive and powerful. Push it for maximum useful output.

- Current validated browser-mode bundle target: up to ~900k tokens. The old ~49k guidance is obsolete.
- Large bundles may exceed 1 MB on disk; rely on `~/.oracle/config.json` `maxFileSizeBytes` (10 MiB or higher) instead of splitting solely because of the old guard.
- Ask for comprehensive solutions, not cautious fragments.
- Ask Oracle to identify the highest-leverage work, sequencing, risks, invariants, tests, logs, and verification receipts.
- Ask for critical code snippets, exact file/function targets, and implementation notes local agents can execute.
- Ask Oracle to separate "must implement now" from "later polish", while still pushing for a meaningful implementation wave.
- Expect local verification with `$agentic-testing`, logs, targeted tests, and `lat check` to teach us more after Oracle gives the plan.

## Output Artifact Boundary

For planning, review, debugging, goal-writing, or implementation guidance, Oracle must return text in the chat/session response only. Do not ask Oracle to create, attach, export, or offer a downloadable file as the deliverable.

The local agent owns every local artifact:

- `~/.oracle/bundles/{slug}.txt` is created locally by `packx`.
- `~/.oracle/sessions/{slug}/output.log` is Oracle session output captured locally.
- Repo files, `.goals/*.md`, `.loop/oracle-loop/**`, prompts, plans, review notes, commits, and verification logs are written locally by the agent with local file-editing or shell tools.

If Oracle creates a downloadable file anyway, do not treat the download as the artifact. Read the response content and write the local artifact yourself. If the only useful content exists inside an unreadable download, rerun Oracle with the no-download constraint emphasized.

## Forward Progress Contract

Oracle is not a substitute for doing the work. Before any second or later Oracle call on the same topic, the local agent MUST build a Prior-State Ledger and pass the Forward Progress Gate.

For a first Oracle call on a new topic, write `prior_oracle_session: none` and continue. For every follow-up Oracle call on the same topic, include this ledger in the Oracle prompt:

```text
Prior-State Ledger:
- prior_oracle_session: <slug/path, or none for first call>
- last_oracle_recommendation: <one-paragraph summary>
- implemented_since_prior_oracle: <files/functions/tests/receipts changed, or none>
- verified_since_prior_oracle: <exact command/receipt/result, or none>
- failed_proof_or_blocker: <exact failed command/output/log/screenshot path, or none>
- narrowing_decision: <what scope was removed and what one slice remains>
- files_functions_now_in_scope: <exact paths#symbols>
- files_functions_out_of_scope: <explicit exclusions>
- next_falsifiable_verification: <command, receipt, screenshot, or runtime proof>
- forward_progress_index: <score and arithmetic>
```

Forward Progress Gate: before another Oracle call on the same topic, at least one of these MUST be true:

- `implemented`: files, tests, goal artifacts, or receipts changed since the prior Oracle session.
- `verified`: a new proof result exists, even if it is red.
- `blocked`: an exact failed command/output/log/screenshot path exists.
- `narrowed`: the new prompt removes scope and targets exactly one next shippable slice.

If none are true, do not call Oracle again. Implement the previous recommendation, run proof, capture a blocker, or narrow the prompt first.

Forward Progress Index:

- +3 consumed a prior receipt, failed proof, or blocker
- +3 selected exactly one new next slice
- +2 named exact files/functions/tests/commands
- +2 added falsifiable verification
- +2 resulted in a checked-in or written goal/test/receipt afterward
- -3 repeats the same topic without new evidence
- -4 produces a broad roadmap instead of the next action

Target score before a follow-up Oracle call: `>= 7`. A score below 7 is allowed only when `blocked` is true and the prompt includes the exact blocker receipt. Record the score in the local goal, loop state, or final summary.

## Long-Running Expectations

Oracle browser runs are blocking research sessions. After Codex starts an Oracle call, all local planning, implementation, verification, and independent problem solving MUST pause until Oracle has fully completed and the local Oracle response has been read. There are no elapsed-time exceptions.

- Never assume Oracle timed out or failed based on elapsed time alone.
- Never proceed independently while Oracle is still processing, even if a wrapper returns after 120s or any other local wait limit.
- Treat Oracle's response as the required next input. No fallback, workaround, self-directed implementation, or "I'll continue while it runs" path is allowed.
- Reattach with `mcp__oracle__sessions({ id: "{slug}", detail: true })` or read `~/.oracle/sessions/{slug}/output.log` when it lands.
- Health checks are allowed only to reattach, inspect session state, or confirm whether Oracle has produced the final local response. They are not permission to start work.
- Keep waiting as long as Oracle requires while the session is still processing. There is no Codex-side timeout threshold that permits independent action.
- Only treat the run as failed when Oracle reports an explicit error, the session exits non-zero, browser automation is blocked, or logs show a terminal failure.

For packx flags and filter details, see [references/packx-quick-reference.md](/topics/codex-packx-command-reference/).

## Pipeline

### Step 1: Choose a slug

Slug must be 3-5 words separated by hyphens. Oracle rejects slugs outside this range.

```bash
mkdir -p ~/.oracle/bundles
```

### Step 2: Preview with packx

Run a dry-run to check file count and estimated size.

```bash
packx --preview [your-filters] -x "**/CLAUDE.md"
```

Stop if 0 files match. Fix filters and preview again. If the target directory is not your cwd, wrap in a subshell: `(cd /path/to/project && packx ...)`.

Never include `CLAUDE.md` in an Oracle PackX bundle. Always exclude it explicitly with `-x "**/CLAUDE.md"` and prefer `AGENTS.md` for repository guidance when both files exist.

### Step 3: Build the bundle

Target a rich bundle close to 900k. If the bundle is under 250k for a broad planning/review task, attempt another pass with more relevant context, process docs, `lat.md` pages, tests, logs, or adjacent owners before consulting Oracle. Smaller focused bundles are still fine for narrow questions.

```bash
packx --limit 900k [filters] -x "**/CLAUDE.md" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt
```

Required flags: `--limit 900k`, `-x "**/CLAUDE.md"`, `-f markdown`, `--no-interactive`, `--stdout`.

If preview showed more than 200 files, add `--strip-comments --minify` so the final bundle still carries broad context.

### Step 4: Validate the bundle

```bash
test -s ~/.oracle/bundles/{slug}.txt && echo "OK" || echo "EMPTY"
```

Stop if empty. Go back to Step 2.

### Step 4.5: Add compact evidence when raw context is too large or unsafe

`packx` remains the primary bundle. Do not skip the bundle. However, if raw session logs, hidden-path scans, screenshots, traces, or generated receipts are too large, unsafe, unavailable, or filtered out, add compact evidence.

Write `~/.oracle/bundles/{slug}-evidence.md` when useful:

```markdown
# Compact Evidence Supplement

## Prior-State Ledger
<ledger, or prior_oracle: none>

## Receipts and failures
- <exact command / receipt / failure summary>
- <paths to screenshots, logs, traces, or receipts not included in packx>

## Raw context intentionally omitted
- <large log/session path> -- omitted because <too large / hidden path / unsafe / unavailable>
- <summary of the relevant lines or facts>

## Current narrowing
- one_next_slice: <exact next slice>
- out_of_scope: <what is intentionally excluded>
- verification: <falsifiable proof>
```

Pass the supplement as an extra file when it is small and safe. If the supplement itself would be too large, include the compact evidence directly in the prompt. This is allowed only as evidence compaction, not as a replacement for the primary packx bundle.

### Step 5: Add screenshots or artifacts

If the user provided image, PDF, log, trace, or screenshot paths, verify they exist and pass them in `files` with the bundle. Use `browserAttachments: "always"` for visual files.

### Step 6: Call Oracle

You must execute this MCP tool call.

```
mcp__oracle__consult({
  prompt: "[{slug}]\n\n{your detailed question here}",
  files: ["~/.oracle/bundles/{slug}.txt"],
  engine: "browser",
  model: "gpt-5.5-pro",
  browserModelLabel: "Latest",
  browserThinkingTime: "extended",
  slug: "{slug}"
})
```

Forbidden call shapes:

```text
engine: "api"              # never valid for oracle-packx
model: "<api-model-id>"    # never use this as a reason to switch engines
engine omitted             # never rely on Oracle defaults
```

If you notice one of these shapes in a drafted call, stop before tool invocation and rewrite the call with `engine: "browser"` plus browser fields. Do not try it once "to see if it works."

With screenshots or PDFs:

```
mcp__oracle__consult({
  prompt: "[{slug}]\n\n{your detailed question here}",
  files: ["~/.oracle/bundles/{slug}.txt", "/path/to/screenshot.png"],
  engine: "browser",
  model: "gpt-5.5-pro",
  browserModelLabel: "Latest",
  browserThinkingTime: "extended",
  browserAttachments: "always",
  slug: "{slug}"
})
```

### Step 7: Read the full response

The MCP return can be truncated. Read the authoritative answer from:

```text
~/.oracle/sessions/{slug}/output.log
```

If the file does not exist yet, check session status and keep waiting unless there is a real terminal failure. A long browser run is expected; keep waiting while the session is still alive and logs show no terminal failure.
Do not summarize, plan, edit, verify, or answer from your own analysis until this full Oracle output is available and read.

### Step 8: Summarize for execution

Lead with Oracle's highest-leverage recommendations, then convert the answer into implementation-ready work packages. Preserve Oracle's reasoning, file targets, critical snippets, logging asks, verification plan, and unresolved risks.

If follow-up code changes are likely, mention the optional commit path: after implementation, the user can say `commit` and you should inspect the diff, map actual changes back to Oracle's advice, and create a traceable commit tied to `{slug}`.

### Step 9: Commit phase, only when requested

Only run this step if the user explicitly asks after implementation.

```bash
git diff --staged
git diff
```

Prefer `git diff --staged` as the commit boundary. Stage only relevant Oracle-driven changes. Do not sweep unrelated edits into the commit.

Commit message format:

```text
<imperative subject line, <=72 chars>

- <what changed> because Oracle recommended <fix/improvement>
- <what changed> to address Oracle's finding about <risk/problem>

Oracle-Session: {slug}
```

## Prompt Contract

Every Oracle prompt must be self-contained, ambitious, and progress-gated.

Include:

1. Slug header: `[{slug}]`.
2. Project briefing: stack, framework, runtime, and repo rules.
3. Goal: the broad outcome the user wants, plus the first shippable slice when the goal is broad.
4. Prior-State Ledger: use `prior_oracle_session: none` for the first consult; for follow-ups include the last Oracle recommendation, what was implemented, verification result, failed proof or blocker, and what is being narrowed now.
5. Forward Progress Gate result: `implemented`, `verified`, `blocked`, or `narrowed`, including Forward Progress Index arithmetic.
6. Current evidence: attempts, logs, screenshots, failing receipts, blocker outputs, or known constraints.
7. Bundle map: why these files were included, what may be missing, and what compact evidence was summarized because raw logs/hidden paths were too large or unavailable.
8. Deliverable: ask for architecture, implementation plan, critical code snippets, file/function targets, tests, logs, verification strategy, and task breakdown for local agents.
9. Next action shape: Oracle must identify the one highest-leverage next shippable slice, separate immediate implementation from later roadmap, and name exact files/functions/tests when possible.
10. Repo-specific rules: for Script Kit GPUI, include `AGENTS.md`, owning skills, relevant `lat.md` pages, and `lat.md/verification.md` when implementation or review checks are part of the question. Never include `CLAUDE.md`; prefer `AGENTS.md` for repo instructions.
11. Output boundary: ask Oracle to return text in the response only, with no downloadable files, attachments, exports, or generated local artifacts.

Include this constraint verbatim or equivalently in every planning/review prompt:

```text
Return your answer as text in this response only. Do not create, attach, export,
or offer any downloadable file. Do not create local project artifacts yourself.
The local agent will write any needed files, plans, notes, goals, commits, or
verification logs using local tools.
```

Avoid prompts that ask only "what is the next change?" Also avoid repeated broad replanning. A follow-up prompt on the same topic must either consume new evidence or deliberately narrow to one next slice.

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Empty bundle | Check `--preview`; ensure `-i` uses `**/` prefix; expand relevant filters |
| `-i "*.ts"` matches nothing | Use `-i "**/*.ts"` |
| `-i` + external path = 0 files | Wrap in `(cd TARGET && packx ...)` |
| Token budget exceeded | Use `--strip-comments --minify`, then sharpen filters around owners, tests, docs, and logs |
| `mcp__oracle__consult` unavailable | Use the CLI Oracle recovery path: `oracle --engine browser --model gpt-5.5-pro --browser-thinking-time extended -p "..." --file ~/.oracle/bundles/{slug}.txt --slug "{slug}"` |
| `Missing OPENAI_API_KEY` | The call accidentally used API mode or defaulted incorrectly. Retry with `engine: "browser"` and let Oracle read `~/.oracle/config.json`. |
| 120s timeout / no final answer yet | Reattach/check `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle completes or reports a terminal failure |
| Truncated response | Read `~/.oracle/sessions/{slug}/output.log` |
| Oracle created a downloadable file | Do not use it as the artifact; write the needed local file yourself from response text, or rerun with the no-download constraint emphasized |
| Thinking time error | Use `browserThinkingTime: "extended"` |

## Completion Checklist

- [ ] `packx` preview ran and produced matching files.
- [ ] `~/.oracle/bundles/{slug}.txt` exists and is non-empty.
- [ ] If under 250k for broad planning/review, you attempted to add useful context before consulting Oracle.
- [ ] You called `mcp__oracle__consult` with `engine: "browser"` so Oracle uses `~/.oracle/config.json`.
- [ ] You read `~/.oracle/sessions/{slug}/output.log`.
- [ ] Your summary is based on Oracle's answer, not your own analysis.
- [ ] No planning, implementation, verification, or final answer happened while Oracle was still processing.
- [ ] Oracle was asked to return text only and not create downloadable files or project artifacts.
- [ ] For follow-up Oracle calls, the prompt included a Prior-State Ledger.
- [ ] For follow-up Oracle calls, the Forward Progress Gate passed as `implemented`, `verified`, `blocked`, or `narrowed`.
- [ ] The Forward Progress Index arithmetic was recorded.
- [ ] If raw logs/session output/hidden paths were too large or unavailable, compact evidence was summarized in the prompt or a `~/.oracle/bundles/{slug}-evidence.md` supplement.
- [ ] Oracle was asked for one next shippable slice, not only a broad roadmap.
- [ ] If committing, you inspected staged and unstaged diffs and mapped the commit to Oracle's recommendations.

## References

- [Packx quick reference](/topics/codex-packx-command-reference/) - flags, filters, workflows, size management
- [Packx deep technical reference](/topics/codex-packx-technical-reference/) - internals, caching, AST details

## Operational boundaries

- The browser-only mode, extended-thinking setting, exclusion policy, and progress score are this runbook’s operating choices. They are not universal tool limitations.
- Numeric token targets and model labels describe a configured workflow, not a guaranteed current capacity. An accepted attachment does not prove the model consumed every token. Verify the installed tools and provider limits.
- Repo-specific verification helpers such as `$agentic-testing`, `lat check`, and `lat.md` require that project’s tooling; use the corresponding real verification surface for another repository.

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
