codex-orchestrator 2.0.3 → 2.0.4

package/internal-workflow/skills/cleanup-review/SKILL.md

@@ -1,84 +0,0 @@
----
-name: "cleanup-review"
-description: "Run an independent post-implementation simplification review only when a concrete cleanup risk cannot fit final code review. Find removable duplication, obsolete paths, workarounds, and unjustified abstractions without re-reviewing correctness."
----
-
-# Cleanup Review
-
-Use this skill after implementation has settled and before final `$code-review`.
-It is a cleanup-only Adapter: its job is to reduce maintenance surface without
-changing required observable behavior.
-
-Do not invoke it separately from implementation size or risk classification.
-The final `$code-review` spec/standards lens owns bounded hygiene for every
-profile, with a dedicated parallel reviewer track for `high`. Use this Adapter
-only when the user, approved source, or repo policy names a concrete evidenced
-cleanup risk that cannot be covered proportionately by that lens.
-
-When an Implementation Review Module schedules this Adapter, follow
-`../../docs/agents/implementation-review-loop.md` for topology, state, defect
-lifecycle, and Closure. Otherwise follow
-`../../docs/agents/review-gates.md`. This skill does not create its own loop.
-
-## Invocation Contract
-
-- Use one profile-selected independent reviewer. Root never reviews or certifies cleanup inline.
-- One logical activation spans the Full pass and every lineage-preserving Closure; protocol session rotation creates neither a new activation nor Full pass.
-- Run one Full cleanup review only after the complete implementation diff and required validation have settled. Never run it per slice or re-enter cleanup after final code review starts.
-- The implementation owner integrates accepted fixes. The reviewer remains read-only and returns evidence and bounded changes.
-- If independent review is unavailable, report the gate as unavailable; do not substitute root self-review.
-
-## In Scope
-
-- duplicated logic, sources of truth, registrations, or old/new paths kept in parallel
-- dead helpers, flags, adapters, branches, comments, tests, or documentation left by the change
-- workaround-shaped conditionals, magic ordering, symptom patches, and unnecessary state
-- compatibility or fallback behavior without current repository, source-authority, or production evidence
-- new services, events/listeners, adapters, or indirection with one current consumer and only speculative reuse
-- ownership placement only when moving or deleting code restores an existing owner without redesigning the system
-- stale or duplicated tests/docs only when their cleanup debt is itself the finding
-
-## Out Of Scope
-
-- functional correctness, acceptance completeness, security, privacy, performance, or product decisions
-- missing regression coverage or weak behavior proof by itself; route it to the scheduled code-review/test-quality lens
-- broad architecture redesign, future extensibility, or a request for a new abstraction unrelated to removing current duplication
-- discovery of new sibling edge cases in unchanged behavior
-- style, naming, or formatting preferences without concrete maintenance cost
-
-## Review Method
-
-1. Pin the target revision/diff and source authority supplied by the Review Plan or root.
-2. Inventory material additions, replacements, compatibility paths, and new runtime owners.
-3. Classify each material complexity decision:
-   - `KEEP`: required by a current invariant and supported by evidence or a boundary proof.
-   - `SIMPLIFY`: required behavior can use a smaller existing seam or fewer states/branches.
-   - `REMOVE`: no current behavior, authority, consumer, or compatibility evidence requires it.
-4. Report a finding only when it names exact evidence, concrete maintenance cost, and a behavior-preserving simplification. Uncertain removal becomes follow-up, not a guessed blocker.
-
-A one-producer/one-consumer abstraction defaults to `SIMPLIFY` unless a concrete
-lifecycle, transaction, dependency-direction, or fanout invariant requires the
-boundary. Do not request a new abstraction unless it reduces current duplication
-or restores an existing owner now.
-
-For Module-scheduled Closure, inspect only accepted cleanup repairs and their
-causal fan-out. Do not restart broad discovery or convert proof-only gaps into
-cleanup defects.
-
-In Module mode, reuse supplied stable cleanup IDs and return each as `verified`
-or `reopened`. Hand settled decisions/IDs to final code review; that reviewer
-rechecks hygiene only for a concrete regression caused by its own repair.
-
-## Output
-
-Return exactly:
-
-1. `Verdict: Clean | Cleanup Needed | Cleanup Blocked`
-2. `Final Coverage: cleanup-only`
-3. `Decisions`: concise `KEEP | SIMPLIFY | REMOVE` records for material complexity, each with evidence and protected invariant or maintenance cost
-4. `Findings`: actionable cleanup defects with supplied ID/lifecycle update, exact path/line evidence, and a behavior-preserving fix; otherwise `None`
-5. `Follow-up Needed`: only risky removals or missing authority/evidence; otherwise `None`
-
-`Cleanup Blocked` means the cleanup decision requires unavailable evidence or an
-explicit product/ownership choice. It never means that correctness or test-quality
-review should be performed inside this skill. Keep the result short and auditable.

package/internal-workflow/skills/cleanup-review/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Cleanup Review"
-  short_description: "Exceptional independent simplification review"
-  default_prompt: "Use $cleanup-review only when an explicit concrete cleanup risk cannot fit the final code-review standards lens."
-policy:
-  allow_implicit_invocation: true

package/internal-workflow/skills/codebase-design/DEEPENING.md

@@ -1,35 +0,0 @@
-# Deepening
-
-How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](./SKILL.md) — `module`, `interface`, `seam`, `adapter`.
-
-## Dependency categories
-
-When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
-
-### 1. In-process
-
-Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
-
-### 2. Local-substitutable
-
-Dependencies that have local test stand-ins. Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
-
-### 3. Remote but owned (Ports & Adapters)
-
-Your own services across a network boundary. Define a port at the seam. The deep module owns the logic; the transport is injected as an adapter. Tests use an in-memory adapter. Production uses a network adapter.
-
-### 4. True external (Mock)
-
-Third-party services you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
-
-## Seam discipline
-
-- **One adapter means a hypothetical seam. Two adapters means a real one.**
-- **Internal seams vs external seams.** A deep module can have internal seams used by its own tests. Don't expose internal seams through the interface just because tests use them.
-
-## Testing strategy: replace, don't layer
-
-- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
-- Write new tests at the deepened module's interface. The interface is the test surface.
-- Tests assert on observable outcomes through the interface, not internal state.
-- Tests should survive internal refactors — they describe behaviour, not implementation.

package/internal-workflow/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -1,50 +0,0 @@
-# Design It Twice
-
-When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern.
-
-Uses the vocabulary in [SKILL.md](./SKILL.md) — `module`, `interface`, `seam`, `adapter`, `leverage`.
-
-Run this workflow only when the candidate is selected, its constraints are known, and the interface decision is consequential enough to justify independent alternatives. Do not run it for a vocabulary question, one bounded recommendation, or routine helper extraction.
-
-This file defines the comparison protocol; the active root driver executes it and retains session ownership, user dialogue, delegation, and the final decision.
-
-## Process
-
-### 1. Frame the problem space
-
-The active root driver writes a user-facing explanation of the problem space for the chosen candidate:
-
-- The constraints any new interface would need to satisfy
-- The dependencies it would rely on, and which category they fall into
-- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
-
-Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
-
-### 2. Spawn sub-agents
-
-Delegate 3+ radically different interfaces to isolated subagent contexts using the exact named role selected by local coding-skill routing. Run them in parallel when supported. This shared reference must not invent a provider-specific tool or override the configured role, model, or effort.
-
-If independent subagents are unavailable, state that the normal comparison cannot run. As a fallback, produce three sequential inline alternatives labelled **non-independent**; do not claim that they provide independent design evidence.
-
-Prompt each sub-agent with a separate technical brief and a different design constraint:
-
-- Agent 1: minimize the interface
-- Agent 2: maximize flexibility
-- Agent 3: optimize for the most common caller
-- Agent 4 (if applicable): design around ports & adapters for cross-seam dependencies
-
-Include both [SKILL.md](./SKILL.md) vocabulary and `CONTEXT.md` vocabulary in the brief so each sub-agent names things consistently.
-
-Each sub-agent outputs:
-
-1. Interface
-2. Usage example
-3. What the implementation hides behind the seam
-4. Dependency strategy and adapters
-5. Trade-offs
-
-### 3. Present and compare
-
-The active root driver presents designs sequentially so the user can absorb each one, then compares them in prose. Contrast by depth, locality, and seam placement.
-
-After comparing, give your own recommendation. If elements from different designs would combine well, propose a hybrid.

package/internal-workflow/skills/codebase-design/SKILL.md

@@ -1,82 +0,0 @@
----
-name: codebase-design
-description: Design or evaluate a named module interface, deep-module seam, or durable public test seam. Provides bounded design vocabulary; not a session driver, repository-wide scan, or implementation workflow.
----
-
-# Codebase Design
-
-Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
-
-## Reference Contract
-
-Use this skill as the vocabulary owner and bounded decision lens. Answer the named design question through supplied or locally verified evidence. Do not start repository-wide exploration, implementation, writes, subagents, or an open-ended design session merely because this skill loaded.
-
-Let the active driver own workflow, checkpoints, user dialogue, and mutations. Use `$improve-codebase-architecture` for an explicitly requested architecture scan, `$grilling` for an interactive decision tree, and the normal plan/spec/TDD flows for design authority and implementation.
-
-Use Design It Twice only after a consequential deepening candidate is selected and its constraints are known.
-
-## Glossary
-
-Use these terms exactly — don't substitute "component", "service", "API", or "boundary". Consistent language is the whole point.
-
-**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service.
-
-**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. Avoid: API, signature.
-
-**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation or a large adapter with a small implementation. Reach for "adapter" when the seam is the topic; "implementation" otherwise.
-
-**Depth** — leverage at the interface: the amount of behaviour a caller or test can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
-
-**Seam** — a place where you can alter behaviour without editing in that place; the location at which a module's interface lives. Avoid: boundary.
-
-**Adapter** — a concrete thing that satisfies an interface at a seam. Describes role, not substance.
-
-**Leverage** — what callers get from depth: more capability per unit of interface they learn.
-
-**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers.
-
-## Deep vs shallow
-
-**Deep module** = small interface + lots of implementation.
-
-**Shallow module** = large interface + little implementation.
-
-When designing an interface, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?
-
-## Principles
-
-- **Depth is a property of the interface, not the implementation.**
-- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
-- **The interface is the test surface.**
-- **One adapter means a hypothetical seam. Two adapters means a real one.**
-
-## Designing for testability
-
-Good interfaces make testing natural:
-
-1. Accept dependencies, don't create them.
-2. Return results, don't produce side effects.
-3. Keep the surface area small.
-
-## Relationships
-
-- A **Module** has exactly one **Interface**.
-- **Depth** is a property of a **Module**, measured against its **Interface**.
-- A **Seam** is where a **Module**'s **Interface** lives.
-- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
-- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
-
-## Rejected framings
-
-- **Depth as ratio of implementation-lines to interface-lines** — rewards padding the implementation.
-- **"Interface" as the TypeScript `interface` keyword or a class's public methods** — too narrow.
-- **"Boundary"** — overloaded with DDD's bounded context. Say **seam** or **interface**.
-
-## Going deeper
-
-- **Deepening a cluster given its dependencies** — see [DEEPENING.md](./DEEPENING.md)
-- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](./DESIGN-IT-TWICE.md)

package/internal-workflow/skills/codebase-design/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Codebase Design"
-  short_description: "Reference vocabulary for deep-module decisions"
-  default_prompt: "Use $codebase-design inside the current workflow as a bounded reference to evaluate this named Module Interface or Seam; keep the active driver in control and do not start a broader workflow."
-policy:
-  allow_implicit_invocation: true

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

@@ -1,107 +0,0 @@
----
-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_standard` child; root owns source
-verification, artifact integration, user communication, and later decisions.
-
-## 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_standard` 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, tickets, and implementation specs cite the artifact as their
-  external Evidence Map 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

@@ -1,6 +0,0 @@
-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/ui-evidence-proof/SKILL.md

@@ -1,123 +0,0 @@
----
-name: ui-evidence-proof
-description: Prove UI, layout, copy, responsive, browser, mobile, or frontend changes with fresh visual artifacts. Use when app-facing completion requires workflow/viewport evidence and criterion-to-artifact mapping.
----
-
-# UI Evidence Proof
-
-Use this skill when the task needs visual proof in normal Codex app chat. It is a prompt-level proof workflow, not the package runner's machine-enforced Acceptance Proof. The goal is to stop "some screenshot exists" from becoming "the UI is proven."
-
-## Activation
-
-Use this skill for:
-
-- explicit requests for visual proof, UI proof, screenshots, videos, browser proof, app proof, or layout checks;
-- frontend, web, mobile, app-facing, responsive, visual, copy, or styling changes before final handoff;
-- checking a screenshot/video/UI dump against an expected user workflow or visual complaint.
-
-If a stronger project-specific proof runner exists, use it when appropriate, but still use this skill to inspect and explain the evidence before claiming success.
-
-## Non-Negotiable Standard
-
-Visual proof passes only when the current artifact visibly proves the requested user-facing state. A screenshot, video, or UI dump is not proof by itself.
-
-Before claiming success, produce or verify a UI Evidence Report with:
-
-1. **Exact workflow** - the entrypoint and user path used to reach the state.
-2. **Source inputs** - issue/request criteria, screenshot complaint, manual QA notes, implementation evidence, or reproduction signal used to derive checks.
-3. **Viewport coverage** - the relevant desktop/mobile/tablet sizes and why they are sufficient.
-4. **Artifact freshness** - the final post-change artifacts inspected after the last run/edit.
-5. **Layout review** - spacing, padding, clipping, overlap, alignment, responsive placement, and the specific visual complaint.
-6. **Copy review** - user-facing labels and absence of rejected technical terms when copy is part of the task.
-7. **Criterion mapping** - which artifact proves which criterion.
-
-If any required dimension is missing, do not say proof passed. Continue the proof loop when in scope; otherwise report a blocker or residual risk.
-
-## Workflow
-
-### 1. Extract The Proof Target
-
-Identify the task-specific checks before opening tools:
-
-- user workflow: login/entrypoint, create/edit/detail/settings/modal state, relevant route or screen;
-- expected state: visible controls, content, copy, data, interaction result;
-- layout expectations: spacing, grouping, alignment, overflow, clipping, responsive behavior;
-- copy expectations: accepted wording and rejected implementation terms;
-- source inputs: issue, user request, PRD/spec, prior screenshot, manual QA plan, reproduction signal.
-
-If criteria are underspecified, derive the smallest explicit checklist from the request and state assumptions. Ask only when ambiguity would materially change the proof.
-
-### 2. Drive The Real UI Path
-
-- Prefer the same entrypoint a user would use.
-- When credentials are available through the repo's documented environment or smoke setup, use the real login UI.
-- If you seed cookies/session state, record why the normal UI path was unavailable or irrelevant.
-- For web layout proof, include a wide desktop viewport unless the task clearly excludes desktop.
-- Include mobile only when the task mentions mobile/responsive behavior or the change is likely to affect small screens.
-
-### 3. Capture Current Artifacts
-
-Capture artifacts after reaching the exact state:
-
-- screenshots for visual state;
-- video or step screenshots for interaction flows;
-- UI tree/DOM text dump when it helps verify labels or hidden overflow;
-- console/log output only as supporting evidence, not a visual substitute.
-
-Do not reuse old screenshots. Check timestamp/path or recapture after the final change. If a path is overwritten, inspect the current file before using it in the final report.
-
-### 4. Inspect The Artifact
-
-Look at the artifact, not only DOM selectors or test assertions.
-
-Check:
-
-- correct workflow/state, not a nearby equivalent screen;
-- enough surrounding context, not a crop that hides the layout relationship;
-- spacing/padding/breathing room;
-- overlap, clipping, scroll traps, sticky headers/footers, and text truncation;
-- alignment/grouping against neighboring controls;
-- expected copy and absence of rejected technical wording;
-- obvious loading, error, empty, stale-data, or permission states.
-
-Use measurements when helpful, but do not let convenient geometry replace the actual visual complaint.
-
-### 5. Decide And Act
-
-- If the proof passes, write the UI Evidence Report.
-- If proof reveals an in-scope defect and the user asked for implementation, fix it and rerun proof.
-- If proof reveals an out-of-scope defect, record it as residual risk or follow-up.
-- If required tools, credentials, or services are missing, report a concrete blocker with the proof attempted.
-
-## UI Evidence Report
-
-Use this compact format in final answers or proof notes:
-
-```markdown
-## UI Evidence
-
-- **Workflow:** <entrypoint -> path -> exact screen state>
-- **Source inputs:** <request/issue/spec/reproduction/manual QA sources used>
-- **Viewports:** <viewport names and dimensions, with reason>
-- **Fresh artifacts:** <current screenshot/video/UI dump paths captured after final run>
-- **Layout review:** <spacing/padding/overlap/clipping/alignment findings>
-- **Copy review:** <accepted labels and rejected terms checked>
-
-| Criterion | Artifact | Evidence | Result |
-| --- | --- | --- | --- |
-| <criterion> | <path/url> | <what is visible and why it proves it> | Pass/Fail/Risk |
-```
-
-Keep it short. Do not include the table when the task is tiny and prose is clearer, but still cover every proof dimension.
-
-## Failure Conditions
-
-Treat these as proof failures:
-
-- artifact does not show the exact requested workflow or screen state;
-- only mobile/narrow proof exists for a desktop layout claim;
-- artifact was captured before the final change or may be stale;
-- screenshot exists but layout/copy was not inspected;
-- only selector/DOM existence is verified for a visual/layout claim;
-- proof uses technical labels the user rejected;
-- direct session seeding bypasses a relevant login/user path without explanation.

package/internal-workflow/skills/ui-evidence-proof/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "UI Evidence Proof"
-  short_description: "Prove UI changes with fresh visual evidence"
-  default_prompt: "Use $ui-evidence-proof to verify this UI change with the exact workflow, relevant viewports, current artifacts, layout and copy review, and criterion-to-artifact mapping before claiming it is done."
-policy:
-  allow_implicit_invocation: true