{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-oracle-handoff-playbook",
  "slug": "oracle-handoff-playbook",
  "title": "Oracle handoff for a huge codebase question playbook",
  "summary": "Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.",
  "category": "Context",
  "tags": [
    "Oracle",
    "PackX",
    "context",
    "quota",
    "playbook",
    "prompts"
  ],
  "sources": [
    {
      "label": "Agent foundations: Route large codebase questions through Oracle (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-01.html"
    }
  ],
  "sourceUnits": [
    "scenarios/topics.mjs#oracle-handoff",
    "scenarios/oracle-handoff.json#audienceFit",
    "toolkit/prompts/01-oracle-codebase-handoff-prompt.md",
    "toolkit/codex-skills/oracle-codebase-handoff/SKILL.md",
    "scenarios/oracle-handoff.json#scenarios/0",
    "scenarios/oracle-handoff.json#scenarios/1",
    "scenarios/oracle-handoff.json#scenarios/2",
    "scenarios/oracle-handoff.json#implementationNotes",
    "scenarios/oracle-handoff.json#notTaughtOrAvoid/1",
    "scenarios/oracle-handoff.json#notTaughtOrAvoid/2",
    "scenarios/oracle-handoff.json#notTaughtOrAvoid/3",
    "scenarios/oracle-handoff.json#notTaughtOrAvoid/4",
    "scenarios/oracle-handoff.json#notTaughtOrAvoid/5",
    "scenarios/oracle-handoff.json#agentReferences",
    "toolkit/bundles/code-oracle-packx.md"
  ],
  "collection": "foundations",
  "categoryId": "context",
  "wordCount": 3431,
  "url": "/topics/foundations-oracle-handoff-playbook/",
  "markdownUrl": "/markdown/foundations-oracle-handoff-playbook.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-oracle-handoff-playbook.json",
  "headings": [
    {
      "id": "copy-paste-workflow",
      "text": "Copy-paste workflow",
      "level": 2
    },
    {
      "id": "copy-paste-prompt",
      "text": "Copy-paste prompt",
      "level": 3
    },
    {
      "id": "how-it-works",
      "text": "How it works",
      "level": 3
    },
    {
      "id": "reusable-skill",
      "text": "Reusable skill",
      "level": 2
    },
    {
      "id": "scenarios",
      "text": "Scenarios",
      "level": 2
    },
    {
      "id": "unblock-a-tangled-next-js-auth-redirect-bug",
      "text": "Unblock a tangled Next.js auth redirect bug",
      "level": 3
    },
    {
      "id": "agent-brief",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "find-the-real-owner-of-a-checkout-state-bug",
      "text": "Find the real owner of a checkout state bug",
      "level": 3
    },
    {
      "id": "agent-brief-2",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references-2",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification-2",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done-2",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations-2",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "map-a-legacy-migration-before-touching-code",
      "text": "Map a legacy migration before touching code",
      "level": 3
    },
    {
      "id": "agent-brief-3",
      "text": "Agent brief",
      "level": 4
    },
    {
      "id": "implementation-references-3",
      "text": "Implementation references",
      "level": 4
    },
    {
      "id": "browser-verification-3",
      "text": "Browser verification",
      "level": 4
    },
    {
      "id": "definition-of-done-3",
      "text": "Definition of done",
      "level": 4
    },
    {
      "id": "failure-modes-and-mitigations-3",
      "text": "Failure modes and mitigations",
      "level": 4
    },
    {
      "id": "implementation-notes",
      "text": "Implementation notes",
      "level": 2
    },
    {
      "id": "boundaries-and-caveats",
      "text": "Boundaries and caveats",
      "level": 2
    },
    {
      "id": "agent-reference-map",
      "text": "Agent reference map",
      "level": 2
    },
    {
      "id": "oracle-codebase-handoff-prompt",
      "text": "Oracle codebase handoff prompt",
      "level": 3
    },
    {
      "id": "oracle-codebase-handoff-codex-skill",
      "text": "Oracle codebase handoff Codex skill",
      "level": 3
    },
    {
      "id": "verified-oracle-packx-command-surface",
      "text": "Verified Oracle + PackX command surface",
      "level": 3
    },
    {
      "id": "lesson-01-validated-references",
      "text": "Lesson 01 validated references",
      "level": 3
    },
    {
      "id": "packx-preview-command",
      "text": "PackX preview command",
      "level": 3
    },
    {
      "id": "packx-bundle-command",
      "text": "PackX bundle command",
      "level": 3
    },
    {
      "id": "oracle-browser-handoff-command",
      "text": "Oracle browser handoff command",
      "level": 3
    },
    {
      "id": "cmux-browser-local-verification-surface",
      "text": "CMUX browser/local verification surface",
      "level": 3
    },
    {
      "id": "command-reference",
      "text": "Command reference",
      "level": 2
    },
    {
      "id": "oracle-cli-browser-handoff-verified-flags",
      "text": "Oracle CLI (browser handoff) — verified flags",
      "level": 2
    },
    {
      "id": "packx-context-bundling-verified-flags-from-packx-help",
      "text": "PackX (context bundling) — verified flags from `packx --help`",
      "level": 2
    },
    {
      "id": "mcp-equivalent",
      "text": "MCP equivalent",
      "level": 2
    }
  ],
  "markdown": "# Oracle handoff for a huge codebase question playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWorking web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.\n\n[Core principles](/topics/foundations-oracle-context-routing/)\n\n## Copy-paste workflow\n\n**When to use:** When a read-heavy question spans a large codebase and would burn your Codex token/rate budget. Offload the heavy analysis to a browser ChatGPT Pro Extended Thinking session via Oracle + PackX, then bring the returned plan back into Codex and implement locally.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. I have a large, read-heavy question about this codebase and I want to offload the heavy analysis to a browser ChatGPT Pro session via Oracle + PackX instead of burning local tokens. Follow these steps exactly and do not skip the preview.\n\n1. Bundle the relevant files with PackX. First PREVIEW so we see what gets included and the token estimate:\n     packx --preview -s \"<TOPIC>\"\n   When the preview looks right, write the bundle:\n     packx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n\n2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words:\n     ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \\\n       -p \"<THE BIG ANALYSIS QUESTION>\" \\\n       --slug \"<3-5-word-kebab-slug>\" \\\n       --write-output .notes/oracle-plan.md \\\n       --file .notes/handoff-bundle.md\n\n3. Read .notes/oracle-plan.md, then implement the plan locally and verify (run the tests/build). Treat this as a plan -> implement -> verify loop.\n\nGuardrail: keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.\n```\n\n### How it works\n- `packx --preview -s \"<TOPIC>\"` shows the matched files and a token estimate before you commit — always preview first so the bundle is scoped, not bloated.\n- `packx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md` writes a scripted markdown bundle (no prompts).\n- `oracle --engine browser --browser-thinking-time extended` drives ChatGPT Pro in the browser with extended thinking; `--write-output` saves ONLY the final assistant message, and `--file` attaches the bundle (cap raised via `ORACLE_MAX_FILE_SIZE_BYTES=12000000`).\n- The `--slug` must be 3-5 kebab words or Oracle rejects it.\n- The returned plan is the durable artifact: read it back into Codex, implement, then verify. Keep concurrency low (2-3 browser requests) to stay within ChatGPT Pro limits.\n- Reference: [John's Oracle fork](https://github.com/johnlindquist/oracle), [PackX](https://www.npmjs.com/package/packx).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/oracle-codebase-handoff/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: oracle-codebase-handoff\ndescription: Trigger when a read-heavy question spans a large codebase and would burn Codex token/rate budget — offload heavy analysis to a browser ChatGPT Pro session via Oracle + PackX, then resume implementation locally. Do NOT trigger for small, local edits.\n---\n\n# Oracle codebase handoff\n\nOffload a big, read-heavy codebase analysis to a browser ChatGPT Pro session via Oracle + PackX, then bring the plan back and implement locally. Run as a plan -> implement -> verify loop.\n\n## Steps\n\n1. Bundle the relevant files with PackX. PREVIEW first to confirm scope and token estimate, then write the bundle:\n   ```bash\n   packx --preview -s \"<topic>\"\n   packx -s \"<topic>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n   ```\n   `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first; use `--no-interactive` for scripted bundles.\n\n2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words, and the prompt text must start with `[<slug>]` on line 1, a blank line, then the question:\n   ```bash\n   ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \\\n     -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" \\\n     --slug \"<3-5-word-kebab-slug>\" \\\n     --write-output .notes/oracle-plan.md \\\n     --file .notes/handoff-bundle.md\n   ```\n   - `--engine browser` automates ChatGPT in the browser (GPT models).\n   - `--browser-thinking-time extended` sets ChatGPT thinking time (light|standard|extended|heavy).\n   - `--write-output` writes ONLY the final assistant message.\n   - `--file` attaches the bundle (size cap raised via `ORACLE_MAX_FILE_SIZE_BYTES`).\n\n3. Read `.notes/oracle-plan.md`, then implement the plan locally and verify (tests/build).\n\n## Guardrails\n- Slug MUST be 3-5 kebab words or Oracle rejects it.\n- Keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.\n- Do NOT use this for small, local edits — only for read-heavy, large-codebase questions.\n````\n\n## Scenarios\n\n### Unblock a tangled Next.js auth redirect bug\n\n**Role:** As a senior full-stack web developer owning a Next.js app\n\nA production-like local Next.js app has a login redirect loop that only appears after mixing middleware, server components, API route auth checks, and client-side session refresh. The issue spans many files, so asking Codex to read everything directly would burn the interactive session budget.\n\n> As a senior full-stack web developer, I want Codex to offload the broad auth-flow investigation through Oracle and PackX, so that Codex can spend its local context on implementing and verifying the fix instead of reading the whole repo.\n\n#### Agent brief\n\n```text\nYou are my coding agent in this repo. Investigate the auth redirect loop by using the Oracle codebase handoff workflow, then implement only the locally verifiable fix. Do not skip the PackX preview. Create `.notes/` if needed. First run `packx --preview -s \"Next.js auth redirect middleware session login callback API route\"` and inspect the matched files and token estimate. If the scope is reasonable, run `packx -s \"Next.js auth redirect middleware session login callback API route\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then send the bundle through Oracle browser mode with a 3-5 word kebab slug, and make the prompt start with the same bracketed slug on line 1: `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[auth-redirect-loop]\\n\\nWe have a Next.js auth redirect loop. Read the attached PackX bundle and produce: 1) the likely root cause, 2) the exact files/functions to inspect first, 3) a minimal implementation plan, 4) local verification steps using the dev server/browser, and 5) risks or false leads to avoid. Do not propose unrelated rewrites.\" --slug \"auth-redirect-loop\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, read `.notes/oracle-plan.md`, summarize the recommended fix in `.notes/auth-redirect-receipt.md`, implement the smallest safe change, then run the repo's existing typecheck/test/build command discovered from package scripts. Finally start the local dev server and verify the login flow in a browser.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"Next.js auth redirect middleware session login callback API route\"\n```\n\n```text\npackx -s \"Next.js auth redirect middleware session login callback API route\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[auth-redirect-loop]\\n\\n<question>\" --slug \"auth-redirect-loop\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nUse the running local app as proof, not source-code confidence. In a CMUX browser pane or browser-agent workflow, open the dev server, capture an accessibility snapshot of the login page, click the sign-in control, fill the test credentials or scripted local auth fields, submit, and evaluate `window.location.pathname` plus visible authenticated UI text. Save a screenshot or browser transcript showing the flow reaches the expected post-login route without bouncing back to `/login`.\n\n#### Definition of done\n\n- .notes/oracle-plan.md exists and contains the browser-side Oracle recommendation\n- .notes/auth-redirect-receipt.md records the selected fix, files changed, and why alternatives were rejected\n- Repo verification command passes, such as test/typecheck/build from package scripts\n- Browser proof shows login reaches the expected authenticated route without a redirect loop\n- Git diff is limited to the auth-related fix and does not include `.notes/` artifacts\n\n#### Failure modes and mitigations\n\n- Mistake: using Oracle before previewing the bundle, causing a bloated or irrelevant handoff. Mitigation: require `packx --preview` first and adjust the search topic before writing `.notes/handoff-bundle.md`.\n- Mistake: implementing the whole Oracle plan as if it were guaranteed correct. Mitigation: treat `.notes/oracle-plan.md` as a plan, then implement the smallest locally verifiable change and prove it in the browser.\n- Mistake: using a slug that Oracle rejects. Mitigation: use exactly 3-5 kebab words and start the prompt with `[same-slug]` followed by a blank line.\n- Mistake: trusting unit tests for a browser-only redirect bug. Mitigation: require browser proof against the running dev server.\n\n### Find the real owner of a checkout state bug\n\n**Role:** As a product engineer maintaining a checkout funnel\n\nA React or Remix checkout page loses cart state when the user changes shipping method, navigates back, or refreshes after payment intent creation. The logic is split across route loaders/actions, client state, server API handlers, and payment integration code.\n\n> As a product engineer, I want a huge-context Oracle pass to map the checkout state ownership and failure points, so that my local agent can make a targeted fix and prove the checkout flow in the browser.\n\n#### Agent brief\n\n```text\nYou are my coding agent. Use Oracle + PackX only for the broad read-heavy diagnosis, then return to local implementation and verification. Create `.notes/` if needed. Run `packx --preview -s \"checkout cart state shipping method payment intent loader action API\"`. Review the preview for checkout routes, cart/session modules, API handlers, and payment-related files. If relevant, run `packx -s \"checkout cart state shipping method payment intent loader action API\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[checkout-state-owner]\\n\\nRead the attached checkout-related codebase bundle. Identify which layer should own checkout/cart state, where the current flow can lose state during shipping changes, browser back navigation, refresh, or payment intent creation, and propose the smallest fix. Return exact file/function references, a step-by-step implementation plan, and browser verification steps. Avoid broad architecture rewrites unless the current code makes a minimal fix unsafe.\" --slug \"checkout-state-owner\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. Read the returned plan, write `.notes/checkout-handoff-receipt.md` with the chosen path, implement the minimal fix, then run existing tests/build. If the repo has no browser test, use the dev server plus a browser-agent or CMUX browser pane to verify the funnel manually and record evidence.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"checkout cart state shipping method payment intent loader action API\"\n```\n\n```text\npackx -s \"checkout cart state shipping method payment intent loader action API\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[checkout-state-owner]\\n\\n<question>\" --slug \"checkout-state-owner\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nUse browser verification because this bug is about real user navigation. In the local app, open the checkout route, capture a snapshot of cart line items and total, click through shipping method changes, use back/forward navigation, refresh once after the payment-intent step if safe in the local/test environment, and evaluate the visible cart total plus any checkout state exposed in the page. Save a screenshot or transcript proving the cart survives the exact sequence.\n\n#### Definition of done\n\n- PackX preview was inspected before bundle creation\n- .notes/oracle-plan.md contains a file/function-level checkout state diagnosis\n- .notes/checkout-handoff-receipt.md names the selected minimal fix and verification sequence\n- Existing repo checks pass\n- Browser proof shows the checkout state survives shipping change, back navigation, and refresh in the local/test flow\n\n#### Failure modes and mitigations\n\n- Mistake: asking Oracle for a generic checkout redesign. Mitigation: phrase the Oracle prompt around state ownership, exact failure paths, minimal fix, and browser proof.\n- Mistake: including live secrets, customer data, or real payment credentials in logs or screenshots. Mitigation: use local/test data only and redact artifacts before saving.\n- Mistake: letting Codex use Oracle for every small follow-up. Mitigation: use Oracle once for the broad read-heavy map, then continue locally unless another huge-codebase question appears.\n- Mistake: verifying only the happy path. Mitigation: require the back/refresh/shipping-change sequence that reproduced the bug.\n\n### Map a legacy migration before touching code\n\n**Role:** As a tech lead planning a risky front-end migration\n\nA large web app is moving one feature area from legacy pages to a newer app-router or component architecture. The team needs to know which files, routes, shared utilities, and tests are involved before assigning implementation work.\n\n> As a tech lead, I want an Oracle handoff to produce a migration map from the current codebase, so that the implementation agent can work from a grounded plan and avoid guessing across many files.\n\n#### Agent brief\n\n```text\nYou are my coding agent. This is a read-heavy migration-mapping task, so use Oracle handoff first and do not edit source files until the returned plan is reviewed. Create `.notes/` if needed. Run `packx --preview -s \"legacy feature migration routes components shared utilities tests\"`. If the preview includes the expected legacy feature area, run `packx -s \"legacy feature migration routes components shared utilities tests\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[legacy-migration-map]\\n\\nRead the attached PackX bundle for a large web app migration. Produce an implementation-ready migration map: current entry points, route/page ownership, shared components/utilities, test/build commands to run, risky coupling points, safe first slice, and a plan -> implement -> verify sequence. Do not invent tools or recommend a broad rewrite; stay grounded in the attached code.\" --slug \"legacy-migration-map\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, create `.notes/migration-slice-receipt.md` with the first safe slice, explicit files to edit, verification commands, and browser proof needed. Implement only that first slice if it is small enough; otherwise stop with the migration map and receipt for human review.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-context-routing/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"legacy feature migration routes components shared utilities tests\"\n```\n\n```text\npackx -s \"legacy feature migration routes components shared utilities tests\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[legacy-migration-map]\\n\\n<question>\" --slug \"legacy-migration-map\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nBrowser proof is useful only after a concrete migration slice exists. For the planning-only phase, the right proof is `.notes/oracle-plan.md` plus a migration receipt. If implementing the first slice, open old and new routes in a local browser or CMUX browser pane, capture snapshots/screenshots of the same user-visible state, click the primary controls, and confirm the migrated route preserves the expected behavior.\n\n#### Definition of done\n\n- .notes/oracle-plan.md exists and maps entry points, route ownership, shared utilities, risks, and first safe slice\n- .notes/migration-slice-receipt.md converts the Oracle recommendation into a local implementation decision\n- No source files are changed unless the first slice is explicitly small and verifiable\n- If a slice is implemented, existing checks pass and browser comparison proof exists for old versus new route behavior\n- The final review artifact names what remains out of scope\n\n#### Failure modes and mitigations\n\n- Mistake: turning a migration map into a giant unreviewed rewrite. Mitigation: require a first safe slice and stop for review if the change is not small and verifiable.\n- Mistake: packing the entire repo without topic discipline. Mitigation: preview with a migration-specific search phrase and narrow before writing the bundle.\n- Mistake: treating Oracle's output as fresh repo truth after code changes. Mitigation: once implementation begins, inspect current files locally and verify against the running app.\n- Mistake: using browser proof too early. Mitigation: use browser proof after a concrete UI slice exists; use the Oracle plan and receipt as planning proof before edits.\n\n## Implementation notes\n\n- Use Oracle only for read-heavy, large-codebase analysis. Small local edits should stay in Codex without the browser handoff.\n- Always preview PackX output before writing `.notes/handoff-bundle.md`; the preview is the quality gate for scope and token cost.\n- The Oracle slug must be 3-5 kebab words, and the prompt must start with `[same-slug]`, then a blank line, then the question.\n- Keep browser concurrency low: no more than two or three Oracle browser requests at once.\n- Treat `.notes/oracle-plan.md` as a planning artifact, not a commandment. The local agent still has to inspect current files, implement the smallest safe slice, and verify with tests/build/browser proof.\n- Keep `.notes/` artifacts local working files. Do not commit Oracle bundles or plans unless the repo deliberately wants them.\n- For browser proof, prefer user-visible receipts: screenshot, accessibility snapshot, console-free run, route/path evaluation, or a short transcript of click/fill/evaluate steps.\n- Do not put secrets, customer data, real payment credentials, or private cookies into PackX bundles, logs, browser screenshots, or `.notes/` receipts.\n\n## Boundaries and caveats\n\n- Do not introduce NotebookLM as part of this Oracle workflow; it was not retained as a taught workflow for this topic.\n- Do not add a generic API/manual-copy lane as if it were taught here; keep the workflow centered on Oracle + PackX + browser handoff.\n- Do not claim browser-side work is permanently unlimited, free, or policy-proof. Frame quota behavior as the workshop setup and keep concurrency conservative.\n- Do not use Oracle to bypass normal local verification. The final proof still comes from tests, build logs, and the running web app.\n- Do not invent unverified CMUX, PackX, or Oracle flags. Use the verified command shapes in the command reference.\n\n## Agent reference map\n\n### Oracle codebase handoff prompt\n\nUse this as the copy-paste workflow shape for PackX preview, PackX bundle creation, Oracle browser handoff, returned-plan file, and local verification loop.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n### Oracle codebase handoff Codex skill\n\nUse this when the local agent needs the strict runnable version: preview first, slug rules, prompt prefix, `--write-output`, `--file`, and plan -> implement -> verify.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n### Verified Oracle + PackX command surface\n\nUse this to avoid inventing flags. It includes the verified `oracle --engine browser --browser-thinking-time extended` command, `ORACLE_MAX_FILE_SIZE_BYTES`, PackX preview/write commands, token-limit notes, and slug rules.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n### Lesson 01 validated references\n\nUse this as the taught-source boundary for the Oracle topic: Codex-to-browser quota offloading, ChatGPT Pro Extended as a high-context browser surface, PackX context bundling, MCP/browser bridge, low concurrency, and plan -> implement -> verify.\n\n[Open reference](/topics/foundations-oracle-context-routing/)\n\n### PackX preview command\n\nRun before writing any bundle so the agent can check matched files and token estimate instead of blindly sending irrelevant context.\n\n```text\npackx --preview -s \"<TOPIC>\"\n```\n\n### PackX bundle command\n\nWrite the relevant codebase context into a model-readable markdown file that Oracle can attach.\n\n```text\npackx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n### Oracle browser handoff command\n\nSend the PackX bundle to browser ChatGPT with extended thinking and save only the final assistant message to a local plan file.\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" --slug \"<3-5-word-kebab-slug>\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n### CMUX browser/local verification surface\n\nUse a browser pane or browser-agent-style workflow to prove web app behavior after local implementation, especially login, checkout, navigation, and route migration flows.\n\n```text\ncmux --json tree; cmux read-screen; local dev server URL from repo package scripts\n```\n\n## Command reference\n\nThese command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.\n\n## Oracle CLI (browser handoff) — verified flags\n```bash\nORACLE_MAX_FILE_SIZE_BYTES=12000000 \\\noracle --engine browser --browser-thinking-time extended \\\n  -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" \\\n  --slug \"<3-5-word-kebab-slug>\" \\\n  --write-output .notes/oracle-plan.md \\\n  --file .notes/handoff-bundle.md\n```\nVerified options (from `oracle --help` and the Oracle source):\n- `--engine browser` — automate ChatGPT in the browser (GPT models). Default picks api when OPENAI_API_KEY set, else browser.\n- `--browser-thinking-time <light|standard|extended|heavy>` — ChatGPT thinking time (source: src/cli/browserConfig.ts, src/mcp/types.ts).\n- `--write-output <path>` — write ONLY the final assistant message to a file.\n- `--slug \"<words>\"` — session slug, MUST be 3-5 words.\n- `--file <paths...>` — attach files/dirs/globs (cap configurable via `ORACLE_MAX_FILE_SIZE_BYTES`).\n- `--browser-attachments <auto|never|always>`, `--browser-bundle-files` — control upload behavior.\n\nSlug rule (validated): 3-5 kebab words. The oracle prompt text MUST start with `[<slug>]` on line 1, blank line, then the prompt.\n\n## PackX (context bundling) — verified flags from `packx --help`\n```bash\npackx --preview -s \"<TOPIC>\"                                   # preview matching files + token estimate FIRST\npackx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\npackx <PATH> -i \"*.ts\" --no-interactive -o bundle.md          # positional path + glob include\npackx --diff -f markdown --no-interactive -o bundle.md         # only files changed from main\npackx --staged ...  | --dirty ...                              # staged-only / modified+untracked\npackx FILTERS --limit 900k -f markdown --no-interactive -o bundle.md   # token budget\npackx FILTERS --strip-comments --minify ...                    # compressed bundle\npackx FILTERS -M 32k                                           # split into chunks\npackx --no-packignore <DOTFILE_PATH>                           # include dotfiles / ignored paths\n```\nKey rules: `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first. Use `--no-interactive` for scripted bundles. Formats: xml (default), markdown, plain, jsonl.\n\n## MCP equivalent\n`mcp__oracle__consult` with `engine: \"browser\"`, `slug`, `browserThinkingTime: \"extended\"`, `files`, `browserAttachments`. The packx bundle goes in `~/.oracle/bundles/{slug}.txt`; output in `~/.oracle/sessions/{slug}/output.log`. Browser-mode bundle target up to ~900k tokens. Keep concurrency low (2-3 browser requests max)."
}
