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__consultcall MUST setengine: "browser". - Never use
engine: "api"and never omitengine; the API engine'sOPENAI_API_KEYfailure 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 lacksengine: "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
browserModelLabelandbrowserThinkingTime; 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~/.oracleconfig. 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~/.oracleconfig 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__consultcall in this skill must includebrowserThinkingTime: "extended". - Keep
browserModelLabel: "Latest"andmodel: "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 /
imagineruns only. - If the visible ChatGPT Intelligence pill says
Instantbefore a packx run, change it back through Oracle by sendingbrowserThinkingTime: "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.jsonmaxFileSizeBytes(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, andlat checkto 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}.txtis created locally bypackx.~/.oracle/sessions/{slug}/output.logis 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.logwhen 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:
- Slug header:
[{slug}]. - Project briefing: stack, framework, runtime, and repo rules.
- Goal: the broad outcome the user wants, plus the first shippable slice when the goal is broad.
- Prior-State Ledger: use
prior_oracle_session: nonefor 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. - Forward Progress Gate result:
implemented,verified,blocked, ornarrowed, including Forward Progress Index arithmetic. - Current evidence: attempts, logs, screenshots, failing receipts, blocker outputs, or known constraints.
- 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.
- Deliverable: ask for architecture, implementation plan, critical code snippets, file/function targets, tests, logs, verification strategy, and task breakdown for local agents.
- 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.
- Repo-specific rules: for Script Kit GPUI, include
AGENTS.md, owning skills, relevantlat.mdpages, andlat.md/verification.mdwhen implementation or review checks are part of the question. Never includeCLAUDE.md; preferAGENTS.mdfor repo instructions. - 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
- [ ]
packxpreview ran and produced matching files. - [ ]
~/.oracle/bundles/{slug}.txtexists and is non-empty. - [ ] If under 250k for broad planning/review, you attempted to add useful context before consulting Oracle.
- [ ] You called
mcp__oracle__consultwithengine: "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, ornarrowed. - [ ] 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.mdsupplement. - [ ] 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 - flags, filters, workflows, size management
- Packx deep 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, andlat.mdrequire that project’s tooling; use the corresponding real verification surface for another repository.