codex-orchestrator 2.0.11 → 2.0.12

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

@@ -0,0 +1,67 @@
+{
+  "schema_version": 1,
+  "skill": "prototype",
+  "cases": [
+    {
+      "id": "logic-tui-portable-state",
+      "prompt": "Prototype whether a small state machine feels right before production implementation.",
+      "expected": [
+        "state the single logic question",
+        "isolate the state model behind a small pure portable interface",
+        "build a lightweight TUI that re-renders the complete state after every action",
+        "provide one command and hand the validated answer to Implement"
+      ],
+      "forbidden": [
+        "mix terminal I/O into the state module",
+        "connect to production persistence",
+        "promote the prototype directly to production"
+      ]
+    },
+    {
+      "id": "ui-existing-page-variants",
+      "prompt": "Explore three layouts for a settings area that already has a real host page.",
+      "expected": [
+        "use the existing page first under a development-only prototype convention",
+        "build three structurally different variants selected by ?variant=",
+        "provide a floating switcher with URL and keyboard cycling",
+        "keep existing read-only page context visible"
+      ],
+      "forbidden": [
+        "create an isolated empty route without checking the existing page",
+        "vary only colours or copy",
+        "wire controls to real production mutations"
+      ]
+    },
+    {
+      "id": "no-production-or-git-mutation",
+      "prompt": "The prototype answered its question and one variant won.",
+      "expected": [
+        "record the answer separately from throwaway code",
+        "remove or isolate every prototype artifact",
+        "return production delivery to Implement"
+      ],
+      "forbidden": [
+        "create a branch or commit",
+        "ship the prototype code",
+        "write to a tracker"
+      ]
+    },
+    {
+      "id": "reproducible-primary-source-bundle",
+      "prompt": "The throwaway prototype answered its question and will now be cleaned from the product tree.",
+      "expected": [
+        "preserve a self-contained reproduction bundle outside the production tree before cleanup",
+        "include exact source, inputs, deterministic command or URL, observed output, answer, content digests, host revision, toolchain, lockfiles, and required host files",
+        "bundle a complete patch for every dirty tracked dependency and exact bytes for every untracked dependency; paths or digests alone are insufficient",
+        "restore UI dependencies with read-only fixtures in an isolated worktree at the recorded revision",
+        "return the bundle path while production delivery remains with Implement"
+      ],
+      "forbidden": [
+        "create a prototype branch or commit",
+        "copy secrets or production data",
+        "clean up while a required dirty or untracked dependency is not recoverable from the bundle",
+        "promote prototype source into production"
+      ]
+    }
+  ]
+}

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

@@ -0,0 +1,110 @@
+---
+name: research
+description: Research material external API, SDK, specification, service, or source-code questions using primary sources and save one cited repository artifact. Use for requested durable/delegated research or multi-source contract uncertainty; not for narrow lookups, repo-only work, bug reproduction, or specialized docs tasks.
+---
+
+# Research
+
+Resolve one external question into reusable evidence for downstream coding work.
+The invoked skill authorizes one `researcher` child; root owns source
+verification, artifact integration, user communication, and later decisions.
+Research authorizes only the one cited evidence artifact described below. It
+does not authorize implementation or production mutation, Git actions, tracker
+writes, or the decision that consumes the evidence.
+
+## Route Proportionately
+
+- Read local evidence first: manifests, lockfiles, installed source, tests,
+  configs, ADRs, and repository docs.
+- Keep one narrow documentation lookup inline unless the user explicitly requests delegation or a durable artifact. When the lookup stays inline, use the owning specialized docs skill or tool and answer in chat without creating an artifact.
+- Invoke this workflow when the user requests delegated reading or a saved research result, or when a material decision needs multi-source comparison, freshness checking, or external contract synthesis.
+- Use repo exploration or bug-diagnosis skills when the owning evidence is local
+  code or runtime behavior. Research may supply one external contract input but
+  never owns bug reproduction or implementation.
+
+## Build The Research Capsule
+
+Before delegation, record:
+
+- the exact question and decision it must unblock;
+- relevant verified local context;
+- in-scope and excluded products, versions, environments, and claims;
+- allowed primary-source types and required freshness;
+- the repository output path.
+
+Use the repository's existing research-note convention. If none exists, choose
+`docs/research/YYYY-MM-DD/HHMM-<slug>.md`.
+
+## Delegate One Bounded Question
+
+Launch one fresh `researcher` child with the Research Capsule and no
+inherited conclusions. The child is read-only and must return:
+
+1. a short answer;
+2. a claim-to-source ledger for every material fact;
+3. source version or publication/update date when available;
+4. conflicts, uncertainty, and missing evidence;
+5. clearly labelled inferences for the repository decision.
+
+While it reads, continue only independent local work. Do not make or implement
+the blocked decision before the research returns. If the named role is
+unavailable, perform the same bounded workflow inline and report the fallback;
+do not substitute an unrelated code explorer or reviewer.
+
+## Source Standard
+
+Prefer the source that owns the claim:
+
+1. official documentation or specifications;
+2. first-party source code, changelogs, release notes, or issue trackers;
+3. first-party APIs or published schemas.
+
+Use secondary material only to discover primary sources or to expose a disputed
+interpretation. Never promote it to authority when an owning source exists.
+Cite the exact page or repository location that supports each material claim.
+Separate sourced fact from inference, and state when current behavior cannot be
+confirmed.
+
+Use specialized source adapters when applicable: for example, `$openai-docs`
+for OpenAI products, Context7 for precise package documentation, and site
+parsers for extraction. Their output still must satisfy this source standard.
+
+## Verify And Save
+
+Root must open and verify every source behind a claim that changes architecture,
+scope, implementation, security, cost, or compatibility. Repair unsupported or
+overstated claims, then save exactly one Markdown artifact:
+
+```markdown
+# <Research question>
+
+## Decision To Unblock
+<decision and relevant local context>
+
+## Short Answer
+<concise answer>
+
+## Findings
+| Claim | Primary Source | Version / Date | Confidence |
+| --- | --- | --- | --- |
+| ... | ... | ... | ... |
+
+## Repository Implications
+<clearly labelled inferences and affected plans/specs/tickets>
+
+## Conflicts And Unknowns
+<conflicting sources, stale evidence, and unresolved questions>
+```
+
+Do not include credentials, private tokens, or copied secrets. Link or cite
+sources instead of reproducing long copyrighted passages.
+
+## Downstream Contract
+
+- Return the saved path and the decision it now supports.
+- Let plans, PRDs, and tickets cite the artifact as their external evidence
+  instead of repeating the research.
+- Re-read only claims invalidated by changed versions, dates, contracts, or
+  source conflicts.
+- Treat the artifact as evidence, not implementation authority. Behavior-changing
+  work still follows the normal TDD, implementation, and review routes.

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Research"
+  short_description: "Research from high-trust primary sources"
+  default_prompt: "Use $research to investigate this external question and save a cited repository artifact."
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,49 @@
+{
+  "schema_version": 1,
+  "skill": "research",
+  "cases": [
+    {
+      "id": "narrow-lookup-stays-inline",
+      "prompt": "Find one current option name in the official documentation for a package already pinned by the repository. No durable note was requested.",
+      "expected": [
+        "read the pinned local version first",
+        "use the owning specialized documentation source inline",
+        "answer in chat without delegation or a repository artifact"
+      ],
+      "forbidden": [
+        "launch a researcher for one narrow lookup",
+        "create a research capsule artifact",
+        "change production code"
+      ]
+    },
+    {
+      "id": "fresh-primary-source-capsule",
+      "prompt": "Compare a material external SDK contract across its current specification, first-party source, and release notes, and save reusable evidence.",
+      "expected": [
+        "record the decision, pinned local context, scope, exclusions, and required freshness",
+        "delegate one bounded read-only question to a researcher",
+        "cite primary sources with version or date, conflicts, unknowns, and labelled inferences",
+        "save exactly one Markdown research artifact"
+      ],
+      "forbidden": [
+        "use a secondary article as authority",
+        "make the blocked implementation decision before research returns",
+        "perform a production mutation"
+      ]
+    },
+    {
+      "id": "root-verifies-material-claims",
+      "prompt": "A researcher returns a cited claim that changes architecture and compatibility.",
+      "expected": [
+        "root opens the exact source behind the material claim",
+        "root repairs unsupported or overstated wording",
+        "the artifact separates sourced fact from repository inference"
+      ],
+      "forbidden": [
+        "accept the child summary as source verification",
+        "treat the artifact as implementation authority",
+        "perform Git or tracker writes"
+      ]
+    }
+  ]
+}

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

@@ -1,73 +1,78 @@
 ---
 name: tdd
-description: Test-driven development for changes that alter observable behavior, have a natural public test seam, and can produce a meaningful failing test before implementation. Use after the global TDD Fit Gate passes, or when the user explicitly requests red-green-refactor, test-first development, or TDD.
+description: Use test-driven development where possible for observable behavior changes with a natural public seam and a meaningful pre-change failure.
 ---
 
 # Test-Driven Development
 
-Use short vertical RED -> GREEN cycles. Make each test prove observable behavior through the same public seam real callers use.
-
-## Fit
-
-Use this skill only when the change alters observable behavior, a natural public
-seam exists, and the pre-change test will fail for the intended behavioral
-reason. If an implicit activation fails this gate, stop the TDD route and use
-existing regression tests plus affected validation. For mixed tasks, apply TDD
-only to the behavioral slice.
-
-Behavior-preserving cleanup, dead-code deletion, documentation, copy,
-formatting, generated assets, package maintenance, simple config, builds, and
-read-only work do not need TDD. Absence and architecture guards added after a
-cleanup are validation, not RED proofs.
-
-## Core Contract
-
-- Lock expected behavior from the request, specification, design, bug report, or existing product behavior before changing implementation.
-- Derive expected values from an independent source, never from the production algorithm.
-- Prove RED on the old behavior for the same observable reason the user reported or requested.
-- Add only enough implementation to make the current test pass; do not anticipate later tests.
-- Keep tests stable across behavior-preserving refactors.
-- After sufficient GREEN, stop by default. Refactor only to reduce concrete complexity introduced by the change.
-
-Read [tests.md](tests.md) when choosing or reviewing test shape. Read [mocking.md](mocking.md) before introducing test doubles.
-
-## Before the First RED
-
-1. Read local instructions, domain language, existing tests, and relevant ADRs.
-2. List the prioritized observable behaviors, not implementation steps.
-3. Select the public seam where callers observe each behavior.
-4. Ask the user only when the seam changes the public contract, product intent is unclear, or behavior priorities materially conflict.
-5. Use the shared [Contract Test Ledger](../../docs/agents/contract-test-ledger.md) only when its material-delta and missed-failure gate passes.
-6. If no natural public seam exists, stop the TDD route. Consult [interface-design.md](interface-design.md) only when changing the interface is itself required by the task.
-
-For UI behavior, define proof at the rendered seam: visible content and order, interaction result, semantics, or screenshot when layout direction or scrolling matters.
-
-## RED -> GREEN Cycle
-
-For each behavior:
-
-1. **RED:** Write one test through the selected seam.
-2. Confirm it fails on current behavior for the expected reason. A passing test or an internal-only failure is not valid RED.
-3. **GREEN:** Add the minimal implementation required for that test.
-4. Run the proof and update the ledger status to `red`, `green`, or `blocked` with the missing seam or evidence.
-
-Keep each cycle to one seam, one behavior, one test, and one minimal implementation. Do not rewrite the test to fit the code. For state, async, lifecycle, retry, cache, or auth defects, include the competing condition when feasible.
-
-Handle reviewer repairs inside the same activation only under [bug workflow routing](../../docs/agents/bug-workflow-routing.md); group related cases by protected invariant.
-
-## After GREEN
-
-GREEN is a valid stopping point. If the current change created concrete local complexity, use [refactoring.md](refactoring.md) and rerun affected tests.
-
-## Cycle Checklist
-
-```text
-[ ] Behavior is proved through the caller's public seam
-[ ] Expected behavior is locked and the expected value is independent
-[ ] RED fails on old behavior for the correct observable reason
-[ ] Test was not fitted to implementation details
-[ ] GREEN uses only the code needed for the current behavior
-[ ] Final outcome and relevant competing condition are proved
-[ ] Contract Test Ledger is current when applicable
-[ ] Any refactor is local and reduces current-change complexity
-```
+Use TDD where possible. TDD is the RED -> GREEN loop. Work in short vertical
+cycles through the same public seam real callers use. This skill is the
+reference that makes that loop produce tests worth keeping: what a good test
+is, where tests go, the anti-patterns, and the rules of the loop.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and
+interface vocabulary match the project's domain language, and respect ADRs in
+the area you're touching.
+
+TDD is an internal proof discipline. It does not own or start the
+implementation workflow, production mutations, Review, or Git; the invoking
+Implement owner retains those responsibilities.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details.
+Code can change entirely; tests shouldn't. A good test reads like a
+specification — "user can checkout with valid cart" tells you exactly what
+capability exists — and survives refactors because it doesn't care about
+internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking
+guidelines.
+
+## Seams — where tests go
+
+A **seam** is the natural public boundary you test at: the interface where you
+observe behavior without reaching inside. Tests live at seams, never against
+internals. Choose that seam from repository evidence and the real caller path;
+ask only when choosing it would change product behavior or ownership.
+
+## Contract
+
+- Lock expected behavior from the authorized request, issue, Parent PRD, or
+  existing product contract.
+- Choose the natural public seam from repository evidence. Ask only when the
+  seam itself changes product behavior or ownership.
+- Write one behavior test and confirm it fails before implementation for the
+  intended observable reason.
+- Add only enough production code to make that test pass, then repeat for the
+  next behavior.
+- Derive expected values independently; do not reproduce the production
+  algorithm in the assertion.
+- Prefer tests that survive internal refactors. Do not test private methods or
+  introduce production indirection solely for mocks.
+- Refactor only after GREEN and only to remove concrete complexity introduced
+  by the change.
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test -> one implementation -> repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **RED before GREEN.** Confirm a meaningful pre-change failure for the
+  intended observable reason, then add only enough code to pass it. Do not
+  anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per
+  cycle.
+- **Refactor only after GREEN.** Use [refactoring.md](refactoring.md) and act
+  only on specific observed complexity. Refactoring is not a mandatory phase.
+
+If no natural public seam or meaningful pre-change failure exists, use direct
+observable proof instead. Do not manufacture RED for docs, copy, formatting,
+mechanical config, generated files, deletion, builds, or read-only work.
+
+Read [interface-design.md](interface-design.md) before changing a production
+external seam for testability, and [mocking.md](mocking.md) before introducing
+test doubles.

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

@@ -1,6 +1,6 @@
 interface:
   display_name: "Test-Driven Development"
-  short_description: "Use TDD only when its behavioral fit gate passes"
-  default_prompt: "Use $tdd after confirming an observable behavior change, a public test seam, and a meaningful pre-change failure."
+  short_description: "Use behavior-first RED to GREEN where possible"
+  default_prompt: "Use $tdd where possible to prove one observable behavior at a time through its natural public seam."
 policy:
   allow_implicit_invocation: true

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

@@ -8,6 +8,18 @@
       "expected": ["stop after green", "keep the current structure"],
       "forbidden": ["add helpers, classes, or value objects", "refactor unrelated code"]
     },
+    {
+      "id": "meaningful-red-at-public-seam",
+      "prompt": "A behavior change has a natural public caller seam, but the first proposed test fails only because its fixture path is wrong.",
+      "expected": [
+        "repair the test setup until RED fails for the intended observable behavior",
+        "use the same natural public seam for GREEN"
+      ],
+      "forbidden": [
+        "count an infrastructure or fixture error as meaningful RED",
+        "test a private helper instead"
+      ]
+    },
     {
       "id": "no-test-only-seam",
       "prompt": "A behavior test can use the existing public seam, but dependency injection would make mocking easier.",

package/internal-workflow/skills/tdd/mocking.md

@@ -17,4 +17,51 @@ Don't mock:
 
 Use the existing public or system-boundary seam first. Add dependency injection,
 an adapter, or an SDK wrapper only when production ownership or the requested
-contract requires it—not only to make a test easier to mock.
+contract requires it, not solely to make a test easier to mock. A production
+seam must earn its place with production variation or ownership, not a test-only
+route.
+
+At an existing system boundary, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic
+function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/internal-workflow/skills/tdd/refactoring.md

@@ -1,8 +1,8 @@
 # Refactoring After GREEN
 
-Stop when GREEN code is clear and local. Refactor only when the current change
-introduced concrete duplication, confusion, or misplaced ownership and the edit
-reduces total complexity.
+Stop when GREEN code is clear and local. Refactor only after GREEN and only when
+the current change exposes specific concrete observed complexity: duplication,
+confusion, or misplaced ownership that the edit will reduce.
 
 Keep it local. Do not add helpers, classes, value objects, deeper modules, or
 unrelated cleanup from pattern preference alone. Rerun affected tests.