codex-orchestrator 2.0.2 → 2.0.4

package/internal-workflow/skills/small-task-implementer/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: small-task-implementer
+description: Implement small low-risk coding tasks with narrow edits and targeted validation. Use for tiny fixes, UI/copy changes, config/build corrections, simple tests, or one-module changes that do not need plans, specs, orchestration, or heavy review.
+---
+
+# Small Task Implementer
+
+Use this skill for fast, bounded implementation when creating a PRD and approved ticket-delivery flow would be disproportionate.
+
+## Fit Gate
+
+Proceed only when all are true:
+
+- The requested behavior is clear or can be inferred from local code/tests without a product decision.
+- The change is expected to touch one small area or a few tightly related files.
+- There is a narrow validation path: targeted test, lint/typecheck, build check, UI proof, or direct command.
+- The task does not require a new plan, PRD, issue breakdown, implementation spec, migration, rollout, or multi-agent orchestration.
+
+Escalate out of the tiny-task route when the work has more than one coherent
+behavior, a broad ownership boundary, material rollback/recovery risk, unclear
+product intent, no credible affected validation, or genuine multi-agent/live
+coordination. Statefulness alone does not require escalation into planning or
+orchestration; a clear API, persistence, cache, queue, or DTO change normally
+becomes direct medium implementation.
+
+Escalation rule:
+
+- For clear authority and one coherent outcome, escalate to direct medium root
+  implementation under `$tdd`, affected validation, and one final review when
+  `review-gates.md` applies.
+- Use optional `$grilling`, then `$spec-to-tickets` and `$tickets-orchestrator`,
+  only for unresolved product decisions or a real approved ticket graph,
+  delivery dependency, or explicit orchestration request.
+- For one risky behavior or technical contract, prefer one approved ticket and mark `compact spec` or `standard spec` only when the ticket plus repository evidence cannot remove execution ambiguity.
+- For several tickets sharing one unresolved contract or validation path, make the contract-defining ticket block its consumers; merge tickets that cannot be specified or verified independently instead of creating a wave-level implementation spec.
+- Escalate if the bug requires Bugfix Quality Gate analysis across multiple paths, states, async events, persistence, auth, cache, retries, workers, or contracts.
+
+## Workflow
+
+1. Inspect local context just enough to confirm fit.
+   - Read repo instructions and the smallest relevant code/test files.
+   - Check `git status --short` before editing.
+   - Preserve unrelated dirty work.
+
+2. Write a compact contract in the working update or internal task notes:
+
+```text
+Behavior:
+Scope boundary:
+Validation:
+```
+
+3. Implement the smallest complete change.
+   - Prefer existing patterns and owner modules.
+   - Avoid unrelated refactors, abstractions, cleanup, and compatibility paths.
+   - Before adding a helper, module, layer, or seam, apply the deletion test; keep it only if it improves current locality or leverage.
+   - Do not add pass-through modules, one-adapter seams, or tests coupled to Implementation details; escalate if no natural public test seam exists.
+   - Add or update a focused test only when behavior risk justifies it and the repo has a natural seam.
+   - For pure copy/docs/config changes, do not invent tests; run the cheapest relevant syntax/lint/check instead.
+
+4. Run targeted validation.
+   - Use the narrowest meaningful command first.
+   - If validation is unavailable or too expensive, state the concrete reason and residual risk.
+   - Do not run full CI unless local policy or the changed surface makes it necessary.
+
+5. Stop and escalate if implementation reveals hidden risk.
+   - Examples: shared contract drift, duplicate source of truth, missing test
+     seam, material concurrency/recovery uncertainty, or product ambiguity.
+   - Leave a short explanation of what was discovered and which heavier flow should take over.
+
+## Output
+
+Final response must stay compact:
+
+```text
+Small Task Result
+
+Changed:
+- ...
+
+Proof:
+- ...
+
+Skipped:
+- none / ...
+
+Risk:
+- low / reason
+```
+
+If escalated, use:
+
+```text
+Escalated
+
+Reason:
+- ...
+
+Recommended flow:
+- Direct medium implementation / canonical ticket delivery
+
+Evidence:
+- ...
+```

package/internal-workflow/skills/small-task-implementer/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Small Task Implementer"
+  short_description: "Fast bounded low-risk code changes"
+  default_prompt: "Use $small-task-implementer to make this small low-risk change with targeted validation."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/spec-implementer/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: "spec-implementer"
+description: "Executes approved specs continuously with honest checklist updates, proportional validation, opt-in Git checkpoints, and required review/signoff."
+---
+
+# Spec Implementer
+
+Execute one approved implementation spec continuously. Keep its checklist
+truthful and stop only at a real authority, evidence, safety, or explicit pause
+boundary. Do not redesign approved scope.
+
+Read before editing:
+
+- the complete approved spec and applicable repository instructions;
+- `references/review-loop.md` for approved-spec review ownership;
+- `../../docs/agents/contract-test-ledger.md` only when the spec contains
+  material contract invariants.
+
+## Modes
+
+Compact and full specs use the same direct phase flow. `compact` describes
+document density, not implementation size or risk. Full mode adds only the
+concrete `Risk Controls`, stop conditions, validation, or coordination contract
+already present in the approved spec; it does not add review or reporting
+ceremony by itself.
+
+Use multiple agents only when the spec defines perfectly disjoint write scopes
+and one integrator. Otherwise execute single-agent.
+
+## Preflight
+
+1. Confirm `status`, `spec_mode`, `implementation_size`, `review_profile`,
+   repository count, authority, scope, and exclusions.
+2. Confirm first-phase targets, required services/env/data/fixtures, commands,
+   observable proof, protected paths, and rejected approaches.
+3. Stop if execution needs invented paths, symbols, contracts, commands, or
+   product decisions; if reality differs only in a bounded technical detail,
+   resolve it from repository evidence and record the adjustment.
+4. Keep an intermediate review checkpoint only when the spec explicitly names
+   a stable high-risk slice that later work will not invalidate. Move every
+   ordinary or unstable checkpoint to final review.
+5. Do not create `## Implementation Review State` yet.
+
+## Implementation
+
+For each phase:
+
+1. Re-read its scope and preconditions.
+2. Implement narrow vertical behavior slices through `$tdd` when applicable.
+3. Update reached checklist and Contract Test Ledger items at natural
+   checkpoints; never save all updates for the end.
+4. Run the phase's targeted exit proof.
+5. Record a short `Blocked:` note for any item that cannot complete.
+6. Continue immediately when the exit proof passes and no stop condition
+   applies.
+
+Do not add cleanup, comments, helpers, abstractions, retries, flags, fallbacks,
+or compatibility paths outside the spec. A small implementation adjustment is
+allowed only when it preserves approved behavior and is supported by current
+repository evidence.
+
+## Git Checkpoints
+
+Default to no commits. `$spec-implementer` does not authorize Git writes.
+
+Use per-slice commits only when explicitly authorized and they materially help
+a disjoint multi-agent handoff, planned cross-session pause, or approved
+rollback boundary. Require a passed slice proof, stage only owned paths, follow
+`$commit`, and never push without separate authority. File/slice count and risk
+profile alone do not justify checkpoints.
+
+## Review And Validation
+
+Run targeted behavior tests and the smallest affected integration checks first.
+Use a full repository suite only when the spec or repository policy requires
+it, broad contract fan-out cannot be isolated, or the task is genuinely high.
+
+Run final `$code-review` only when the spec, repository policy, or
+`../../docs/agents/review-gates.md` applies. Ordinary medium work gets one
+`reviewer_standard` Full review on the settled diff. High gets two disjoint
+`reviewer_deep` lenses. Cleanup stays inside spec/standards review.
+
+Immediately before the first reviewer launch, create only the minimal
+`## Implementation Review State` required by `references/review-loop.md`.
+Reconcile a recorded live session before replacement after interruption.
+
+Repair compatible findings once and rerun affected validation. Coordinator
+verification closes ordinary medium/low behavior-preserving repairs. Use
+Closure only for critical/high, protected trust/data/concurrency/shared-contract
+impact, or invalidated mandatory coverage. Do not restart broad Full review
+unless the repair actually invalidated its coverage.
+
+## Stop Conditions
+
+Stop and report the exact blocker when:
+
+- a precondition, source contract, required proof, or protected path differs
+  materially from the approved spec;
+- exact execution requires a new product, scope, ownership, or risky trade-off
+  decision;
+- required validation or reviewer is unavailable and no approved substitute
+  exists;
+- multi-agent scopes overlap or integration ownership is missing;
+- an explicit user pause or halt condition is reached.
+
+Do not stop merely because the work is broad, review took time, or a medium/low
+finding required one repair.
+
+## Completion
+
+Complete only when reached checklist items are reconciled, affected proof and
+required review pass, protected paths and rejected approaches remain intact,
+and every unfinished item has a concrete status.
+
+For ordinary medium work report only:
+
+- behavior/contract implemented;
+- review result and repaired/open findings;
+- affected validation;
+- skipped checks and residual risk;
+- changed files and any authorized commits.
+
+For high, actual Closure, accepted risk, interrupted recovery, or multi-agent
+delivery, add the relevant invariants, reviewer coverage, defect IDs, session
+recovery, and handoff ownership. Do not create a separate report file unless
+the spec or the complexity of that exceptional handoff requires it.

package/internal-workflow/skills/spec-implementer/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Spec Implementer"
+  short_description: "Execute approved specs with lean delivery"
+  default_prompt: "Use $spec-implementer to execute the approved spec continuously, default to no Git checkpoints, validate proportionately, and launch only stable required review gates."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/spec-implementer/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "schema_version": 1,
+  "skill": "spec-implementer",
+  "cases": [
+    {
+      "id": "state-created-at-launch",
+      "prompt": "Execute an approved medium spec whose final review has not started yet.",
+      "expected": ["do not create review state during implementation", "persist minimal state immediately before reviewer launch"],
+      "forbidden": ["create per-slice review bookkeeping"]
+    },
+    {
+      "id": "medium-one-final-review",
+      "prompt": "Execute a normal medium spec with several vertical slices and no stable high-risk checkpoint.",
+      "expected": ["implement continuously", "run one final reviewer_standard on the settled diff"],
+      "forbidden": ["review after every slice", "run a full repository suite from file count"]
+    },
+    {
+      "id": "closure-stays-affected",
+      "prompt": "Final review finds one high defect in a shared schema and several ordinary low findings.",
+      "expected": ["repair once", "Closure verifies only the affected high-risk contract"],
+      "forbidden": ["restart all Full reviewers"]
+    },
+    {
+      "id": "resume-live-reviewer",
+      "prompt": "Resume after a reviewer poll timed out while the recorded session is still live.",
+      "expected": ["reconcile the existing session"],
+      "forbidden": ["mark it failed from timeout alone", "launch a duplicate reviewer"]
+    }
+  ]
+}

package/internal-workflow/skills/spec-implementer/references/review-loop.md

@@ -0,0 +1,94 @@
+# Approved Spec Implementation Review Loop
+
+This reference owns review orchestration for `$spec-implementer`. Read it only
+when executing an approved implementation spec. Shared Full/Closure and defect
+mechanics live in `../../../docs/agents/review-protocol.md`.
+
+Direct work and deterministic issue delivery use normal TDD and review gates;
+they must not create Implementation Review State.
+
+## Authority
+
+Only an approved implementation spec may own `## Implementation Review State`.
+PRDs, tickets, architecture notes, and chat summaries are not review-state
+owners. A substantive spec change returns through artifact review before
+implementation continues.
+
+Use the spec's `review_profile`; if absent, infer it from current evidence:
+
+- `simple`: narrow change with direct proof;
+- `medium`: default for ordinary implementation;
+- `high`: material failure consequence plus an uncertainty amplifier.
+
+Implementation evidence may raise but never lower the approved profile.
+
+## Default Review Shape
+
+Implement continuously through vertical slices. Validate each affected behavior
+and run one final review on the settled diff when the gate applies.
+
+- `simple`: one `reviewer_fast` when review is required.
+- `medium`: one `reviewer_standard`, one bounded final Full, no intermediate
+  checkpoint by default.
+- `high`: two parallel `reviewer_deep` Full reviews with disjoint correctness
+  and spec/standards lenses.
+
+Add an intermediate checkpoint only when the approved spec explicitly names a
+stable high-risk slice whose review will remain valid after later work. Do not
+review unstable intermediate diffs or create per-slice review cycles.
+
+Cleanup stays inside the spec/standards lens. A concrete simplification risk may
+amplify that lens; size and profile labels alone do not create another gate.
+
+## Minimal Durable State
+
+Do not create review state during preflight or implementation. Immediately
+before the first actual reviewer launch, persist:
+
+- profile, authority path, settled target revision, and assigned lenses;
+- launch ID, reviewer/session handle, lineage, and `pending | completed | failed`;
+- returned findings, repair revision, affected validation, and Closure need.
+
+Write `pending` before launch and reconcile that session before replacing it
+after interruption or resume. A usable result becomes `completed`; an explicit
+failure becomes `failed`. A poll timeout while the session remains live is not
+a failure and does not authorize duplicate review.
+
+Record extended lineage/session history only for `high`, a real intermediate
+checkpoint, actual Closure, accepted risk, or interrupted recovery. Normal
+medium execution does not keep epochs, pass thresholds, activation counters, or
+per-slice handoff bookkeeping.
+
+## Findings And Closure
+
+Root aggregates findings, repairs compatible defects once, and reruns only
+affected validation. Coordinator verification closes ordinary medium/low
+behavior-preserving findings after confirming the repair matches the failure.
+
+Use shared-protocol Closure only for critical/high defects, protected
+trust/data/concurrency/shared API impact, or invalidated mandatory coverage.
+Closure stays with the affected reviewer lineage and repaired targets. Start a
+new Full only when the repair invalidated mandatory-lens coverage.
+
+Do not repeat review without a material change in target, evidence, repair, or
+source decision. Stop and surface the actual decision or evidence blocker when
+no progress is possible.
+
+## Completion
+
+Run gates in this order:
+
+1. affected behavior and integration validation;
+2. applicable final code review;
+3. Closure only when triggered;
+4. repository architecture/build/smoke gates required by policy or the spec;
+5. delivery actions explicitly authorized by the user or workflow.
+
+Return `Approved` only for the final settled revision when mandatory lenses and
+validation are complete and shared protocol state is clear. `Waived` records
+skipped coverage but is not approval. `Blocked` requires a concrete authority,
+evidence, reviewer, or convergence blocker—not elapsed time or review count.
+
+For normal medium work report only profile, review result, repaired/open
+findings, affected validation, skipped checks, and residual risk. Add extended
+session/defect accounting only when the exceptional state above exists.

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

@@ -0,0 +1,72 @@
+---
+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.
+---
+
+# 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 and refactor only while GREEN.
+
+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. For contract-risk changes, create or update the shared [Contract Test Ledger](../../docs/agents/contract-test-ledger.md) and map each invariant to its first failing test or observable proof.
+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
+
+Refactor as a separate review-stage activity, never while RED. Use [refactoring.md](refactoring.md) for candidates and rerun affected tests after each step.
+
+## 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
+[ ] Refactoring starts only after GREEN
+```

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

@@ -0,0 +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."
+policy:
+  allow_implicit_invocation: true

package/internal-workflow/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

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

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, 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

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

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

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, item) => sum + item.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value comes from an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```