Oracle and PackX execution runbook

Published browser-only Packx→Oracle skill covering model settings, bundle preparation and validation, compact evidence and attachments, progress-gated follow-ups, blocking session recovery, full-response reading, implementation summaries, optional…

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:

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:

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:

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.

Pipeline

Step 1: Choose a slug

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

mkdir -p ~/.oracle/bundles

Step 2: Preview with packx

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

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.

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

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:

# 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:

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:

~/.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.

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:

<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:

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

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.

Source references