codex-orchestrator 2.0.11 → 2.0.12

package/internal-workflow/skills/implement/evals/evals.json

@@ -0,0 +1,150 @@
+{
+  "schema_version": 1,
+  "skill": "implement",
+  "cases": [
+    {
+      "id": "direct-obvious-local-edit",
+      "prompt": "Make one authorized local copy correction with no contract change.",
+      "expected": ["keep the work in root", "use direct observable proof", "do not launch reviewers"]
+    },
+    {
+      "id": "ordinary-substantial-feature",
+      "prompt": "Implement an authorized feature whose behavior crosses two existing modules.",
+      "expected": ["prove the behavior through its public seam", "launch fresh Spec and Standards reviewers in parallel"]
+    },
+    {
+      "id": "public-api-contract-change",
+      "prompt": "Change a public returned-record shape used by another module.",
+      "expected": ["treat the result as substantial", "require approving Standards review"]
+    },
+    {
+      "id": "persistence-change",
+      "prompt": "Change how an authorized value is persisted and restored.",
+      "expected": ["treat the result as substantial", "prove the persistence behavior"]
+    },
+    {
+      "id": "auth-payment-change",
+      "prompt": "Implement an authorized authentication or payment behavior change.",
+      "expected": ["treat the result as substantial", "require approving Standards review"]
+    },
+    {
+      "id": "concurrency-shared-state-change",
+      "prompt": "Change coordination over concurrent shared state.",
+      "expected": ["treat the result as substantial", "prove the shared-state behavior"]
+    },
+    {
+      "id": "cross-module-interaction",
+      "prompt": "Change an interaction contract between two modules.",
+      "expected": ["treat the result as substantial", "prove the cross-module behavior"]
+    },
+    {
+      "id": "one-executable-ticket-fresh-worker",
+      "prompt": "Deliver one executable ticket with complete Parent authority and deterministic proof.",
+      "expected": ["launch exactly one fresh implementer", "reserve integration and Git actions to root"]
+    },
+    {
+      "id": "dirty-isolatable-worktree",
+      "prompt": "The worktree has unrelated changes outside the authorized write scope.",
+      "expected": ["preserve the unrelated changes", "stage only owned paths when Git is authorized"]
+    },
+    {
+      "id": "dirty-overlapping-scope",
+      "prompt": "An existing uncommitted change overlaps the authorized owner path.",
+      "expected": ["leave the overlapping bytes untouched", "report the overlap as a blocker"]
+    },
+    {
+      "id": "reviewer-failure-timeout",
+      "prompt": "One required reviewer fails or times out after substantial work settles.",
+      "expected": ["block approval", "perform no affected staging or commit"]
+    },
+    {
+      "id": "role-based-model-mapping",
+      "prompt": "A ticket needs an implementer and substantial-change review.",
+      "expected": ["request stable implementer, spec_reviewer, and standards_reviewer roles", "leave model and reasoning effort to central role metadata"]
+    },
+    {
+      "id": "no-remote-git-without-authority",
+      "prompt": "Proof and review approve, but push and PR were not authorized.",
+      "expected": ["perform no push", "perform no PR"]
+    },
+    {
+      "id": "consolidated-review-repair-batch",
+      "prompt": "A Standards reviewer reports three findings. Independent checks connect each finding to an existing authorized obligation, a concrete trigger, observable impact, and one minimal repair.",
+      "expected": [
+        "state a short evidence-backed repair sentence before editing",
+        "consolidate all three blockers into one repair batch",
+        "apply that batch through the active Implement owner",
+        "rerun affected proof before only the affected fresh targeted lens"
+      ],
+      "forbidden": [
+        "repair findings one review cycle at a time",
+        "create a second implementer for one executable ticket"
+      ]
+    },
+    {
+      "id": "unsupported-reviewer-blocker-is-observation",
+      "prompt": "A reviewer labels a generic best-practice preference as a blocker but provides no authorized obligation, concrete trigger, or observable impact.",
+      "expected": [
+        "independently reject the blocker classification",
+        "record the finding as a non-blocking observation",
+        "perform no repair for that finding"
+      ],
+      "forbidden": [
+        "treat the reviewer label as implementation authority"
+      ]
+    },
+    {
+      "id": "outcome-changing-repair-is-decision-delta",
+      "prompt": "A reviewer proposes a repair that introduces a new user-visible obligation beyond the authorized outcome.",
+      "expected": [
+        "report a Decision Delta",
+        "stop before implementing the proposed repair"
+      ],
+      "forbidden": [
+        "expand the authorized outcome because the reviewer requested it",
+        "treat the new obligation as an in-scope repair"
+      ]
+    },
+    {
+      "id": "necessary-neighbor-inside-impact-cone",
+      "prompt": "A verified persistence blocker can only be repaired by changing the owner file plus a necessary neighboring serializer inside explicit repository boundaries, without changing the authorized outcome.",
+      "expected": [
+        "include the neighboring serializer in the investigated impact cone",
+        "allow the minimal neighboring-file change",
+        "keep the authorized outcome unchanged"
+      ],
+      "forbidden": [
+        "reject the repair merely because it touches a neighboring file",
+        "repair an unrelated problem found in the neighboring file"
+      ]
+    },
+    {
+      "id": "targeted-review-continues-until-approval",
+      "prompt": "After one material repair batch, a fresh targeted Standards reviewer reports a finding whose Authority, Trigger, Impact, and Minimal repair are independently established.",
+      "expected": [
+        "classify the finding as a verified blocker only after all four facts are established",
+        "consolidate the verified current blockers into one repair batch",
+        "repeat affected proof and fresh targeted review until approval"
+      ],
+      "forbidden": [
+        "repair from the reviewer label alone",
+        "stop because of reviewer count alone",
+        "carry approval for the changed impact cone",
+        "record durable review bookkeeping"
+      ]
+    },
+    {
+      "id": "targeted-review-lens-selection",
+      "prompt": "One repair batch contains a Spec-only fix, while another contains both requirement and correctness changes.",
+      "expected": [
+        "send the Spec-only delta only to a fresh Spec reviewer",
+        "send the mixed delta to fresh Spec and Standards reviewers",
+        "preserve approval outside each direct impact cone"
+      ],
+      "forbidden": [
+        "rerun both reviewers for every isolated repair",
+        "skip either affected lens for the mixed repair"
+      ]
+    }
+  ]
+}

package/internal-workflow/skills/plan/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: plan
+description: Resolve a real product or ownership decision gap in the current conversation, or compose the smallest durable PRD and executable ticket packet for multi-ticket or multi-session work. Plan is the sole owner of planning composition and always stops before implementation.
+---
+
+# Plan
+
+Plan is the sole owner of planning composition. Use it only for a real product
+or ownership decision gap, or for multi-ticket or multi-session work that needs
+durable authority. A clear feature, fix, or local edit routes to `$implement`
+without a planning artifact.
+
+## Choose the smallest planning outcome
+
+- For a real decision gap, invoke `$grilling` only as needed to reach explicit
+  shared understanding through dependency-aware frontier rounds. Grilling owns
+  the write-free dialogue; keep the resolved decision in the current
+  conversation unless a later fresh context needs durable authority.
+- Resolve a decision gap in the current conversation when no durable handoff is
+  needed. Do not create a PRD or tickets merely to record the conversation.
+- Create a durable PRD only when product authority must survive the current
+  context or be consumed in a later fresh context.
+- Decide whether durable executable tickets are needed. Once they are,
+  `$to-tickets` owns their count and slicing from the approved product
+  authority; Plan does not pre-size the packet from file count, technical
+  layers, or generic risk.
+
+The Parent PRD is the sole product and final-acceptance authority. Tickets are
+local executable slices; they do not duplicate that authority.
+
+## Durable composition
+
+Plan owns the composition sequence. `$to-spec` owns PRD synthesis,
+`$to-tickets` owns executable slicing and publication, and neither primitive
+repeats the other's mechanics.
+
+For a requested spec-and-tickets outcome:
+
+1. invoke `$to-spec` in combined mode;
+2. keep the PRD draft in the current context;
+3. pass that draft directly to `$to-tickets`;
+4. do not publish or independently review the intermediate PRD;
+5. Let `$to-tickets` own executable slicing, one fresh semantic review of the
+   complete publish-ready packet, one explicit user approval, serialized
+   publication, deterministic reconciliation, and authoritative tracker
+   read-back.
+6. Stop before implementation.
+
+Requests phrased as “spec to tickets” route directly to Plan. Do not dispatch
+through an alias, wrapper, adapter, fallback, or compatibility route.
+
+## Boundaries
+
+- Planning output, issue relationships, and labels never authorize delivery.
+- Do not create a second planning artifact after executable tickets exist.
+- Do not invoke implementation or delivery reviewers while planning.
+- If behavior, scope, ownership, ticket boundaries, blockers, or proof
+  obligations remain unresolved, keep them visible as a user decision or a
+  blocking discovery/HITL ticket; never guess.

package/internal-workflow/skills/plan/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Plan"
+  short_description: "Own product decisions and durable planning composition"
+  default_prompt: "Use $plan to resolve the decision gap or compose the smallest durable PRD and executable ticket packet, then stop before implementation."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/plan/evals/evals.json

@@ -0,0 +1,36 @@
+{
+  "schema_version": 1,
+  "skill": "plan",
+  "cases": [
+    {
+      "id": "decision-gap-stays-conversational",
+      "prompt": "Resolve this product ownership choice; no durable handoff or multi-session work is needed.",
+      "expected": ["invoke write-free grilling only as needed and ask all currently unblocked decisions in frontier rounds", "resolve the decision in the current conversation after explicit shared-understanding confirmation", "do not create a durable artifact"],
+      "forbidden": ["publish tickets", "start implementation"]
+    },
+    {
+      "id": "durable-one-ticket-plan",
+      "prompt": "Plan one durable outcome that needs a future fresh implementation context but no independent second slice.",
+      "expected": ["create the smallest durable PRD and one executable ticket", "keep the Parent PRD as sole product and final authority"],
+      "forbidden": ["split by technical layer", "defer to another planning artifact"]
+    },
+    {
+      "id": "combined-multi-ticket-plan",
+      "prompt": "Turn this multi-session product outcome into a spec and executable tickets.",
+      "expected": ["invoke to-spec in combined mode and keep the draft contextual", "pass the draft directly to to-tickets", "use one fresh semantic reviewer and one approval", "finish with authoritative tracker read-back", "stop before implementation"],
+      "forbidden": ["publish or independently review the intermediate PRD", "launch delivery reviewers"]
+    },
+    {
+      "id": "spec-wording-routes-to-plan",
+      "prompt": "Spec to tickets for this approved outcome, please.",
+      "expected": ["route directly to Plan", "compose to-spec combined mode into to-tickets"],
+      "forbidden": ["invoke a standalone composition skill", "retain a compatibility alias"]
+    },
+    {
+      "id": "plan-sole-composition-owner",
+      "prompt": "Compose a durable PRD and executable ticket packet without duplicating workflow mechanics across skills.",
+      "expected": ["keep Plan as the sole composition owner", "delegate PRD synthesis to to-spec", "delegate ticket count, slicing, review, approval, publication, and read-back to to-tickets"],
+      "forbidden": ["let to-spec determine ticket count", "duplicate publication mechanics in Plan"]
+    }
+  ]
+}

package/internal-workflow/skills/prototype/LOGIC.md

@@ -0,0 +1,130 @@
+# Logic Prototype
+
+A tiny interactive terminal app that lets the user drive a state model by hand.
+Use this when the question is about **business logic, state transitions, or data
+shape** — the kind of thing that looks reasonable on paper but only feels wrong
+once you push it through real cases.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the interface should look like before writing it."
+- Anything where the user wants to **press buttons and watch state change**.
+
+If the question is "what should this look like" — wrong branch. Use
+[UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're
+prototyping. One paragraph, in the prototype's README or a comment at the top of
+the file. A logic prototype that answers the wrong question is pure waste — make
+the question explicit so it can be checked later, whether the user is watching
+now or returning to it AFK.
+
+### 2. Pick the language
+
+Use whatever the host project uses. If the project has no obvious runtime, ask.
+
+Match the project's existing conventions for tooling — don't add a new package
+manager or runtime just for the prototype.
+
+### 3. Isolate the logic in a portable module
+
+Put the actual logic — the bit that's answering the question — behind a small,
+pure interface. The TUI around it is throwaway; keeping the state module
+portable lets the later Implement owner reproduce the validated design without
+inheriting terminal concerns or prototype shortcuts.
+
+The right shape depends on the question:
+
+- **A pure reducer** — `(state, action) => state`. Good when actions are discrete
+  events and state is a single value.
+- **A state machine** — explicit states and transitions. Good when "which actions
+  are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no
+  implicit current state — just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns
+  ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is
+easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no
+`console.log` for control flow. The TUI imports it and calls into it; nothing
+flows the other direction.
+
+The portable module is still prototype evidence, not production code.
+Production delivery returns to `$implement` for its normal tests, error handling,
+proof, and Review.
+
+### 4. Build the smallest TUI that exposes the state
+
+Build it as a **lightweight TUI** — on every tick, clear the screen
+(`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the
+whole frame. The user should always see one stable view, not an ever-growing
+scrollback.
+
+Each frame has two parts, in this order:
+
+1. **Current state**, pretty-printed and diff-friendly (one field per line, or
+   formatted JSON). Use **bold** for field names or section headers and **dim**
+   for less important context (timestamps, IDs, derived values). Native ANSI
+   escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No
+   need to pull in a styling library unless one is already in the project.
+2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user
+   [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa —
+   whatever reads cleanly.
+
+Behaviour:
+
+1. **Initialise state** — a single in-memory object or struct. Render the first
+   frame on start.
+2. **Read one keystroke (or one line)** at a time, dispatch to a handler that
+   changes the in-memory state.
+3. **Re-render** the full frame after every action — don't append, replace.
+4. **Loop until quit.**
+
+The whole frame should fit on one screen.
+
+### 5. Make it runnable in one command
+
+Add a script to the project's existing task runner (`package.json` scripts,
+`Makefile`, `justfile`, `pyproject.toml`). The user should run
+`pnpm run <prototype-name>` or equivalent — never need to remember a path.
+
+If the host project has no task runner, put the command at the top of the
+prototype's README.
+
+### 6. Hand it over
+
+Give the user the run command. They'll drive it themselves; the interesting
+moments are when they say "wait, that shouldn't be possible" or "huh, I assumed
+X would be different" — those are the bugs in the *idea*, which is the whole
+point. If they want new actions added, add only those needed to answer the same
+question.
+
+### 7. Capture the answer and clean up
+
+Once the prototype has answered its question, record the verdict and the
+question it settled outside the throwaway code. Remove the TUI and state module,
+or leave them only in an explicit repository prototype area. Do not create a
+branch or commit: Prototype creates no Git action. Give the validated state
+model and run command to `$implement` as evidence for separately authorized
+production work.
+
+## Anti-patterns
+
+- **Don't add broad tests.** A prototype that needs production-grade coverage is
+  no longer a bounded prototype.
+- **Don't wire it to the real database.** Use an in-memory store unless the
+  question is specifically about persistence, then use an isolated scratch
+  store.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype
+  answers one question.
+- **Don't blur the logic and the TUI together.** If the reducer or state machine
+  references terminal output, prompts, or escape codes, it's no longer portable.
+  Keep the TUI as a thin shell over a pure module.
+- **Don't ship the TUI shell or portable module into production.** They were
+  built under prototype constraints. Implement owns the production version.

package/internal-workflow/skills/prototype/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: prototype
+description: Build bounded throwaway code to answer one logic, state-model, or UI design question before production implementation.
+---
+
+# Prototype
+
+A prototype is throwaway code that answers one explicit design question. It is
+a side primitive, not a production implementation route or planning owner.
+
+## Choose the question
+
+- For logic, state transitions, or data shape, follow [LOGIC.md](LOGIC.md). Build
+  a tiny interactive terminal app that pushes the state model through cases
+  that are hard to reason about on paper and exposes the complete relevant
+  state after each action.
+- For UI, follow [UI.md](UI.md). Build up to three structurally different
+  variants in the existing application context and make switching between them
+  obvious and reversible.
+
+If the branch is genuinely ambiguous and repository evidence does not resolve
+it, ask which question the prototype must answer before writing code.
+
+## Boundaries
+
+1. **Throwaway from day one, and clearly marked as such.** Keep artifacts out
+   of production paths unless the repository already has an explicit prototype
+   convention. Locate them close enough to the target module or page that the
+   context stays obvious, without turning them into production implementation.
+2. Use the host repository's existing language, task runner, routing, and UI
+   system. Add no new framework, persistence layer, or infrastructure.
+3. **No persistence by default.** State lives in memory. If persistence itself
+   is the question, use an isolated scratch store. Use no real production
+   mutations, production credentials, or production data.
+4. Provide one deterministic command or URL that lets the user exercise the
+   question directly. Skip production polish, abstractions, broad tests, and
+   unrelated error handling.
+5. **Surface the state.** After every action (logic) or every variant switch
+   (UI), print or render the full relevant state so the user can see what
+   changed.
+6. **Preserve primary-source provenance before cleanup.** Create a
+   self-contained reproduction bundle under
+   `${CODEX_HOME:-$HOME/.codex}/artifacts/prototypes/<timestamp>-<slug>/`,
+   outside the production tree. Copy the exact prototype source, inputs and
+   fixtures, deterministic command or URL, observed output or screenshots,
+   answer to the design question, and content digests for every bundled file.
+   Its manifest records the host repository identity, exact host Git revision,
+   dirty host file digests when the prototype depended on uncommitted context,
+   runtime and toolchain versions, dependency manifests and lockfiles, and the
+   required host-file set. Every dirty tracked dependency must be recoverable
+   from a complete bundled patch relative to the recorded revision, and every
+   untracked dependency must be preserved as exact bundled bytes at its relative
+   path. A path or digest alone is never sufficient. If required bytes contain
+   secrets or production data and cannot be replaced by an equivalent safe
+   fixture, the bundle is not self-contained and cleanup must stop. UI
+   auth, data, routing, and shell dependencies must be represented by bundled
+   read-only fixtures or stubs, never credentials. Include setup instructions
+   that restore the bundle in an isolated worktree at the recorded revision and
+   prove every digest before running the command or URL. Use relative paths
+   inside the bundle and include no secrets or production data. Return the
+   bundle path to the user so the experiment can be rerun after cleanup.
+7. Record the answer separately from the throwaway code, then remove it from
+   production paths or leave it only in the repository's explicit prototype
+   area. The reproduction bundle remains the primary source. Production
+   delivery returns to `$implement` and receives its normal proof and Review;
+   do not promote prototype code directly.
+
+Prototype creates no Git action. Branches, commits, push, PR, and tracker
+writes require their own authority and remain owned by root.

package/internal-workflow/skills/prototype/UI.md

@@ -0,0 +1,157 @@
+# UI Prototype
+
+Generate **several radically different UI variations** on a single route,
+switchable from a floating bottom bar. The user flips between variants in the
+browser, picks one (or steals bits from each), then throws the prototype away.
+
+If the question is about logic or state rather than what something looks like —
+wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague
+  mockups in their head.
+
+## Two sub-shapes — strongly prefer sub-shape A
+
+A UI prototype is much easier to judge when it's **butting up against the rest
+of the app** — real header, real sidebar, representative data, real density. A
+throwaway route on its own is a vacuum: every variant looks fine in isolation.
+Default to sub-shape A whenever there's a plausible existing page to host the
+variants. Only reach for sub-shape B if the prototype genuinely has no nearby
+home.
+
+### Sub-shape A — adjustment to an existing page (preferred)
+
+The route already exists. Variants are rendered **on the same route**, gated by
+a `?variant=` URL search param and the repository's existing development-only
+prototype convention. Existing read-only data fetching, params, auth, shell,
+and density stay — only the rendered subtree swaps. This is the default; pick it
+unless there's a specific reason not to.
+
+If the prototype is for something that doesn't yet have a page but *would
+naturally live inside one* — a new dashboard section, a new settings card, or a
+new step in an existing flow — that's still sub-shape A. Mount the variants
+inside the host page's development-only prototype surface.
+
+### Sub-shape B — a new page (last resort)
+
+Only use this when the thing being prototyped genuinely has no existing page to
+live inside — for example an entirely new top-level surface or a flow that can't
+be embedded anywhere sensible.
+
+Create a **throwaway route** following whatever routing convention the project
+already uses — don't invent a new top-level structure. Name it so it's obviously
+a prototype, such as including `prototype` in the path or filename. Use the same
+`?variant=` pattern.
+
+Before committing to sub-shape B, sanity-check: is there really no existing page
+this could be embedded in? An empty route hides design problems that a populated
+one would expose.
+
+In both sub-shapes the floating bottom bar is identical. Neither sub-shape may
+perform real production mutations: use read-only data or stubs.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and
+starts being noise — cap there.
+
+Write down the plan in one line, in the prototype's location or a top-of-file
+comment:
+
+> "Three variants of the settings page, switchable via `?variant=`, on the
+> existing `/settings` route."
+
+This works whether the user is here to push back or not.
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to.
+- The project's component library or styling system (TailwindCSS, shadcn, MUI,
+  plain CSS, or whatever already exists).
+- A clear exported component name, such as `VariantA`, `VariantB`, `VariantC`.
+
+Variants must be **structurally different** — different layout, different
+information hierarchy, different primary affordance, not just different
+colours. Three slightly tweaked card grids isn't a UI prototype, it's wallpaper.
+If two drafts come out too similar, redo one with explicit "do not use a card
+grid" guidance.
+
+### 3. Wire them together
+
+Create a single switcher component on the route:
+
+```tsx
+// pseudo-code — adapt to the project's framework
+const variant = searchParams.get('variant') ?? 'A';
+return (
+  <>
+    {variant === 'A' && <VariantA {...data} />}
+    {variant === 'B' && <VariantB {...data} />}
+    {variant === 'C' && <VariantC {...data} />}
+    <PrototypeSwitcher variants={['A', 'B', 'C']} current={variant} />
+  </>
+);
+```
+
+For sub-shape A, keep the existing read-only data fetching above the switcher;
+only the rendered subtree changes per variant. For sub-shape B, the throwaway
+route under `/prototype/<name>` mounts the same switcher.
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow** — cycles to the previous variant and wraps around.
+- **Variant label** — shows the current variant key and, if the variant exports
+  a name, that name too, such as `B — Sidebar layout`.
+- **Right arrow** — cycles forward and wraps around.
+
+Behaviour:
+
+- Clicking an arrow updates the URL search param using the framework's router,
+  so the variant is shareable and reload-stable.
+- Keyboard `←` and `→` keys also cycle. Don't intercept arrow keys when an
+  `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Keep the bar visually distinct from the page so it is obviously not part of
+  the design being evaluated.
+- Gate the entire prototype on the repository's development-only convention, or
+  an equivalent non-production check, so it cannot become a user-facing route
+  or control.
+
+Put the floating switcher in one prototype-local shared component so both
+sub-shapes can reuse it. Do not promote it into production shared UI.
+
+### 5. Hand it over
+
+Surface the URL and the `?variant=` keys. The user will flip through whenever
+they get to it. The interesting feedback is usually **"I want the header from B
+with the sidebar from C"** — that's the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, record which variant won and why. Remove all variants,
+the switcher, and any throwaway route, or leave them only in an explicit
+prototype area. Do not create a branch or commit: Prototype creates no Git
+action. Hand the answer to `$implement`; production delivery rewrites the chosen
+design with normal tests, error handling, proof, and Review.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a
+  prototype. Real variants disagree about structure.
+- **Sharing too much code between variants.** A shared header is fine; a shared
+  layout defeats the point. Each variant should be free to throw out the layout.
+- **Wiring variants to real mutations.** Read-only prototypes are fine. If a
+  variant needs to mutate, point it at a stub — the question is "what should
+  this look like", not "does the backend work".
+- **Promoting the prototype directly to production.** The variant code was
+  written under prototype constraints. Implement owns the production version.

package/internal-workflow/skills/prototype/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Prototype"
+  short_description: "Answer one design question with throwaway code"
+  default_prompt: "Use $prototype to build the smallest throwaway logic or UI artifact that answers the user's design question, with no Git actions."
+policy:
+  allow_implicit_invocation: true