codex-orchestrator 2.0.2 → 2.0.3

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

@@ -0,0 +1,257 @@
+---
+name: "code-review"
+description: "Evidence-first review of code, PRs, commits, regressions, or review-and-fix work using correctness and standards/cleanup lenses. Auto-fix only qualifying high-confidence severe issues."
+---
+
+# Code Review
+
+This skill performs evidence-based code review. It is not a style pass and not a summary. Treat the change as potentially wrong until independent review tracks fail to break it.
+
+The review always covers two lenses:
+
+- **Correctness reviewer**: bugs, regressions, runtime behavior, security, contracts, caches, concurrency, framework rules, and failure paths.
+- **Spec & standards reviewer**: requested behavior, documented repo standards, architecture fit, duplication, cleanup, and workaround-shaped implementation.
+
+The main agent is the coordinator. It pins the review target, assigns both
+lenses to one reviewer for `simple` and `medium`, and splits them across two
+independent reviewers only for `high`. It verifies the strongest findings,
+applies only safe fixes, and returns a concise findings-first report.
+
+## When To Use
+
+Use this skill when the user asks for:
+
+- code review, PR review, commit audit, regression scan, or bug hunt
+- review since a branch, commit, tag, merge-base, or working tree state
+- review and fix of critical or high-severity high-confidence defects
+- framework-focused review such as `NestJS`, `Next.js`, `Flutter`, or `Dart`
+
+For every implementation profile, the spec/standards lens includes bounded
+cleanup for duplication, obsolete paths, workaround branches, and unjustified
+abstractions. High-risk work assigns that lens to its own reviewer in the same
+parallel final wave. Run separate `$cleanup-review` first only for an explicit
+concrete evidenced reason that cannot fit this bounded lens.
+
+Exception for approved spec execution: follow
+`../../docs/agents/implementation-review-loop.md`. Intermediate code-review
+checkpoints do not automatically run cleanup first; final cleanup and final code
+review use the durable Review Plan and canonical Defect Ledger.
+
+## Implementation Review Adapter
+
+When this skill is called from `$spec-implementer`:
+
+- read the Module and persisted `## Implementation Review State`
+- accept the scheduled mode, session, revision, and lenses from that state
+- pin the target and give reviewers the Module-defined capsule
+- return the usable result and stable defect updates to the executor
+- when exceptional separate cleanup ran, consume its settled decisions/IDs and avoid broad hygiene rediscovery unless a code-review repair caused a concrete regression
+
+Do not infer a fresh review loop, choose another mode, or make the Module's
+terminal decision inside this Adapter.
+
+## Progressive References
+
+Read only the references the current review needs:
+
+- Detailed bug classes: `references/bug-classes.md`
+- Framework lenses for Next.js, NestJS, Flutter, and Dart: `references/framework-lenses.md`
+- Targeted recipes for recurring diff shapes: `references/targeted-recipes.md`
+- Contract test ledger: `../../docs/agents/contract-test-ledger.md`
+- Shared confidence rubric: `../../docs/agents/confidence-rubric.md`
+
+Load `references/framework-lenses.md` when the user names a framework or files/configs strongly imply one. Load `references/targeted-recipes.md` and `../../docs/agents/contract-test-ledger.md` when the diff shape matches new fields, retries, DTO/schema/runtime contracts, caches, state merge precedence, ordering, evidence/snapshots, determinism, or aggregation summaries. Load `references/bug-classes.md` for substantial reviews or broad bug hunts.
+
+## Coordinator Workflow
+
+### 1. Pin The Review Target
+
+Identify exactly what is being reviewed.
+
+- If the user gave a fixed point, use it directly: branch, commit SHA, tag, `main`, `HEAD~5`, etc.
+- If they did not, infer from context:
+  - current uncommitted work: `git diff` plus staged diff if relevant
+  - branch review: `git diff <base>...HEAD`
+  - commit review: `git show <commit>`
+- If there is no safe inference, ask one short question: "Review against which branch or commit?"
+
+Capture:
+
+- `git status --short`
+- diff stat
+- the exact diff command used
+- commit list when reviewing a branch range
+- changed files and nearest related tests/docs
+
+Use three-dot diff for branch/base reviews: `git diff <fixed-point>...HEAD`.
+
+### 2. Discover Spec And Standards
+
+Do this before reviewer tracks so both tracks receive bounded inputs.
+
+Spec sources, in priority order:
+
+1. Issue or PR references in commit messages, branch names, PR metadata, or user prompt.
+2. A spec/PRD/plan path supplied by the user.
+3. Matching files under `docs/`, `specs/`, `.scratch/`, or local issue folders.
+4. If none exists, continue and mark the spec axis as "no spec found" instead of inventing requirements.
+
+Standards sources:
+
+- `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`
+- `CONTEXT.md`, context maps, domain docs, ADRs
+- `STYLE.md`, `STANDARDS.md`, style guides, review checklists
+- `.editorconfig`, ESLint, Biome, Prettier, TypeScript, analyzer, or framework configs
+- relevant test files and existing examples in the touched area
+
+Machine-enforced config matters as context, but do not spend review findings on issues a required formatter/linter would already catch unless the tool is absent or failing.
+
+### 3. Activate Lenses
+
+Before deep review, decide which lenses apply.
+
+- Always activate the general correctness and spec/standards lenses.
+- Add framework lenses when explicit or strongly implied by files/configs.
+- Add targeted recipes when the diff shape matches them.
+- If the user, plan, or implementation spec provides `Review Focus`, treat each listed lens, targeted recipe, invariant, and risk as mandatory. Do not replace it with a generic review; report any focus item that cannot be verified as a verification gap.
+- If inference is uncertain, say so and continue with the best-supported review instead of pretending certainty.
+
+Mandatory delta lenses:
+
+- **Contract Delta Review:** If the diff expands a shared contract, enum/status, schema, DTO, permission, capability, token, or scope, search old consumers and report `changed contract -> searched call sites -> risky fallback/default branches -> tests or fix`.
+- **Backend Trust Boundary Review:** If the diff adds a credential, OAuth scope, permission, role-sensitive write, or external capability, verify the backend-side guard. UI controls, query/state flags, and caller intent are not authorization.
+
+Common framework signals:
+
+- **Next.js**: `next.config.*`, `app/**`, `pages/**`, route handlers, server actions, `use server`, `use client`, revalidation APIs.
+- **NestJS**: `@nestjs/*`, controllers, providers, modules, guards, pipes, interceptors, DTOs, `nest-cli.json`.
+- **Flutter**: `pubspec.yaml`, `lib/**`, widgets, navigation, bloc/provider/riverpod/notifiers.
+- **Dart**: `.dart`, `Future`, `Stream`, isolates, generated serializers, null-safety constructs.
+
+### 4. Run Profile-Selected Reviewers
+
+For `simple`, run one `reviewer_fast`; for `medium`, run one
+`reviewer_standard`. Assign that child both correctness and spec/standards
+lenses in one bounded Full review. For `high`, run two `reviewer_deep` children
+in parallel with one disjoint lens each. Invoking `$code-review` authorizes
+these reviewers. Preserve every fulfilled launch handle if a parallel peer
+fails, then close all launched children. Tell every reviewer not to edit or
+revert unrelated work.
+
+For spec-driven checkpoints, obey the track assignment in the persisted Review
+Plan instead of automatically launching both default tracks.
+
+When already inside an assigned reviewer child, execute its assigned lens set
+inline and return it to root; do not spawn a grandchild.
+If the user forbids delegation, report the independent review gate as waived or
+unavailable according to the parent workflow; root must not self-review inline.
+
+#### Correctness Reviewer Brief
+
+Include the exact diff command or commit under review, changed file list, commit list, active references, any `Review Focus`, and an instruction to read surrounding execution paths.
+
+> Review runtime correctness adversarially. Hunt concrete bugs in control flow, state, async/concurrency, security, auth, contracts, schemas, caching, persistence, UI/API integration, and framework-specific behavior. If a Review Focus is provided, explicitly test the named risks first, such as duplicate side effects, retry/idempotency, ordering, source-of-truth ownership, partial failure, DTO/schema drift, or false user-facing state. For each finding, provide file/line, trigger path, impact, why guards do not prevent it, severity, and confidence. Do not report style nits or generic "needs tests" comments.
+> For bugfixes, check claim boundaries: what changed tests prove, what they do not prove, and whether sibling execution paths can still violate the claimed invariant.
+> When Contract Delta Review applies, follow new values through old consumers and default/fallback branches before trusting local tests. When Backend Trust Boundary Review applies, verify the server-side authorization predicate at the write/callback boundary.
+
+#### Spec & Standards Reviewer Brief
+
+Include the exact diff command or commit under review, spec source path/content or "no spec found", standards source list, changed file list, commit list, any `Review Focus`, and an instruction to cite the spec or standard behind each finding.
+
+> Review the change against the requested work and repo standards. Check missing requirements, partial behavior, scope creep, undocumented contract changes, architecture drift, duplicate source-of-truth logic, dead/legacy branches, and workaround-shaped implementation. If a Review Focus is provided, explicitly verify each named ownership, scope, validation, and invariant risk against the spec. Cite the spec or standard when available. If there is no spec, skip requirement claims and focus on documented standards and architecture evidence.
+
+### 5. Aggregate And Verify
+
+The coordinator must not blindly relay reviewer output.
+
+1. Deduplicate findings across tracks.
+2. Re-read the relevant code for the strongest findings.
+3. Drop findings that lack a concrete trigger path.
+4. Reclassify severity/confidence using `../../docs/agents/confidence-rubric.md` if evidence does not support the label.
+5. For real contract defects, identify the missing or inadequate Contract Test Ledger invariant when TDD/spec evidence is available.
+6. Confirm every mandatory `Review Focus` item and mandatory delta lens was reviewed; if not, report the unverified item as a verification gap.
+7. Decide whether auto-fix is allowed.
+8. Run the narrowest meaningful verification after any fix.
+
+Keep the two axes visible in your own notes, but present the final report by severity unless the user explicitly asked for side-by-side Standards/Spec output.
+
+For a Module-scheduled Closure, send the bounded capsule to the reviewer lineage
+and session selected by the shared protocol, then return its defect updates.
+
+## Evidence Standard
+
+A valid finding explains:
+
+- what breaks
+- why it breaks
+- the input, sequence, role, tenant, environment, or timing that triggers it
+- where the defect lives
+- why existing guards do not prevent it
+- severity and confidence
+
+Do not file:
+
+- style nits disguised as correctness issues
+- speculative races without a shared-state path
+- generic "needs tests" comments without a concrete regression risk
+- architecture discomfort without wrong ownership, duplication, leakage, or a regression path
+- performance comments without a hot path or failure mode
+
+## Auto-Fix Policy
+
+Automatically fix only when all are true:
+
+- severity is critical or high
+- confidence is high under `../../docs/agents/confidence-rubric.md`
+- root cause is clear
+- correct fix is narrow and low-risk
+- fix matches local project patterns
+- verification is available, or the edit is obviously safe and syntax-checkable
+
+When auto-fixing:
+
+- patch only the bug
+- add/update behavior tests when regression risk is meaningful and the codebase supports it; for contract defects, add the missing ledger invariant first when a ledger exists or is being created
+- rerun relevant verification
+- never revert unrelated user changes
+
+Do not auto-fix ambiguous semantics, product decisions, broad refactors, or low-confidence concerns. Report them with evidence.
+
+## Output Contract
+
+For review-only tasks:
+
+1. Findings first, ordered by severity.
+2. File and line references for each finding.
+3. Trigger path, impact, severity, confidence, and evidence.
+4. Open questions, assumptions, or verification gaps.
+5. Short summary only after findings.
+
+For review-and-fix tasks:
+
+1. State which critical or high-severity high-confidence issues were fixed.
+2. Report remaining findings that were not fixed.
+3. Give one short verification note and any blocked checks.
+4. Keep the closing summary user-facing and outcome-based.
+
+If there are no findings, say so clearly and mention residual test or verification gaps.
+
+For spec-driven review checkpoints or final review gates, include a compact review handoff that can feed the executor's Final Risk Handoff: reviewed target, Review Focus status, high/critical findings fixed or remaining, skipped checks, and residual verification gaps. Keep findings first.
+
+If inline review comments are requested, emit one `::code-comment{...}` directive per actionable finding.
+
+## Tooling Defaults
+
+- Use `rg`/`rg --files` for code search.
+- Prefer parallel reads for status, diff, changed files, related modules, tests, repo docs, and standards.
+- Use official docs or Context7 only when a finding depends on version-sensitive framework/library behavior.
+- Run the narrowest meaningful tests first, then required lint/build/analyzer checks for touched areas.
+- Keep raw command output out of the final response unless the user asks for it.
+
+## Decision Defaults
+
+- If the user says "review", default to findings-first review.
+- If the user says "review and fix", auto-fix only critical or high-severity high-confidence issues that satisfy the auto-fix policy.
+- If the user provides a framework focus, explicitly use it.
+- If no focus is provided, infer active lenses from the diff and say when they materially affected findings.
+- Ask clarification only when the correct review target or fix would otherwise be risky or ambiguous.

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Code Review"
+  short_description: "Profile-routed correctness and standards review"
+  default_prompt: "Use $code-review for one final profile-selected wave; high risk uses two parallel reviewers and the spec/standards lens includes bounded cleanup."

package/internal-workflow/skills/code-review/references/bug-classes.md

@@ -0,0 +1,56 @@
+# Code Review Bug Classes
+
+Use this reference for substantial reviews and broad bug hunts.
+
+## Review Mindset
+
+- Findings first; summary second.
+- Prefer a few high-signal findings over a long speculative list.
+- Read enough surrounding code to understand the real execution path.
+- Include pre-existing bugs only when they materially affect the reviewed path.
+- Treat workaround-shaped code as a review target.
+- Treat duplicated business rules, builders, cleanup rules, normalization, cache keys, restart paths, and persistence math as likely drift vectors.
+- Treat "tests pass" as insufficient when contracts, ownership, or source-of-truth logic moved.
+- Do not stop after the edited hunk unless the change is truly trivial.
+
+## Non-Negotiable Passes
+
+Every substantial review covers:
+
+1. **Scope**: exact diff/commit/branch/files under review.
+2. **Execution path**: entrypoints, callers, callees, side effects, state writes, network/DB boundaries, cleanup.
+3. **Architecture fit**: correct owning layer, no leaky abstractions, no duplicate source of truth, no symptom patch in the wrong layer.
+4. **Invariants**: validation, authorization, ordering, idempotency, data shape, permissions, cache visibility, and lifecycle rules.
+5. **Failure modes**: empty, null, duplicate, stale, delayed, retried, timeout, cancellation, partial failure, concurrent execution.
+6. **Blast radius**: DTOs, schemas, cache keys, feature flags, config, metrics, tests, consumers, migrations, and backward compatibility.
+7. **Verification**: narrow tests/lint/build/analyzer for touched areas, or a clear note when a check cannot run.
+
+## Bug Classes To Hunt
+
+- Control-flow mistakes: wrong branch, inverted predicate, missing return, incorrect default, off-by-one, pagination errors.
+- State/lifecycle bugs: stale state, forgotten reset, double writes, orphaned cleanup, leaks, inconsistent derived state.
+- Async/concurrency bugs: missing `await`, race windows, non-idempotent retries, shared mutable state, closure mutation in retryable callbacks.
+- Partial-failure bugs: one side effect succeeds while durable follow-up fails.
+- Contract drift: DTO/schema/type mismatch, nullable changes, enum drift, serialization differences, `ObjectId`/`Date` runtime mismatch.
+- Cache bugs: stale reads, bad cache keys, cross-tenant leakage, missed invalidation, TTL mismatch.
+- Auth regressions: missing actor checks, wrong tenant scope, optional-param bypass, client-only enforcement.
+- Data correctness: timezones, DST, rounding, units, locale parsing, duplicate filtering, sort instability.
+- UI/API regressions: optimistic state not rolled back, loading/error/empty states broken, incompatible response handling.
+- Observability gaps: critical failures suppressed without logs, metrics, retries, or surfaced errors.
+- Workarounds: magic delays, one-off guards, forced ordering, duplicated normalization, cross-layer patches.
+- Architecture drift: business logic in the wrong layer, source-of-truth splits, unnecessary coupling.
+- Deep-module drift: shallow pass-through modules, hypothetical one-adapter seams, lost locality, weak leverage, or tests reaching inside the implementation instead of crossing the Module Interface.
+
+## Mandatory Questions
+
+Ask the relevant subset for each meaningful path:
+
+- What happens with empty, null, duplicated, delayed, retried, stale, or out-of-order input?
+- What happens when a dependency throws, times out, returns partial data, or returns stale data?
+- Can two executions interleave and corrupt state, leak data, or duplicate work?
+- Are validation and authorization enforced before side effects?
+- Does the change rely on a type guarantee that is weaker at runtime?
+- Do all readers and writers agree on field names, units, nullability, and semantics?
+- If state is rebuilt, cloned, merged, normalized, serialized, or persisted, are all required fields preserved?
+- Can feature flags, optional params, defaults, or fallback paths bypass intended behavior?
+- If failure happens halfway through, what durable state remains and who repairs it?

package/internal-workflow/skills/code-review/references/framework-lenses.md

@@ -0,0 +1,34 @@
+# Code Review Framework Lenses
+
+Load this reference when a framework is explicit or strongly implied by files/configs.
+
+## Next.js
+
+- Server/client component boundaries, hydration assumptions, browser APIs on server.
+- `fetch` cache modes, route segment caching, `revalidatePath`/`revalidateTag`, stale data behavior.
+- Route handlers/server actions: input validation, auth, serialization of dates/errors/nullables.
+- Loading, empty, error, navigation, optimistic update, rollback, back/refresh behavior.
+- SSR/client mismatch from locale, feature flags, sessions, params, and search params.
+
+## NestJS
+
+- Request flow through controller, guard, pipe, interceptor, service, repository, events/queues.
+- DTO validation versus runtime payload, especially transforms, enums, optionals, nested objects.
+- Server-side auth and tenant scope before side effects.
+- Transaction boundaries, partial writes, outbox/queue ordering, retry safety.
+- Exception mapping, HTTP status behavior, cache decorators, request scope, singleton mutable state, cron/queue concurrency.
+
+## Flutter
+
+- Widget lifecycle: `init`, `build`, async callbacks, `dispose`, state updates after unmount.
+- Navigation/back stack, dialog/sheet dismissal, duplicate submit from rapid taps.
+- State management transitions, stale emissions, missed listeners, dropped fields.
+- Loading, offline, empty, error, retry states.
+- Platform permissions, keyboard insets, small-screen overflow, animation/controller/stream cleanup.
+
+## Dart
+
+- Null-safety assumptions, casts, `late`, `!`, JSON parsing, generated serializers.
+- `Future`, `Stream`, timer, isolate ordering, cancellation, uncaught errors.
+- Equality, copy semantics, immutable updates, mutation during iteration.
+- Date/duration/timezone handling, numeric precision, parsing, generic runtime assumptions.

package/internal-workflow/skills/code-review/references/targeted-recipes.md

@@ -0,0 +1,49 @@
+# Code Review Targeted Recipes
+
+Load this reference when the diff shape matches one of these recurring risks.
+
+## Activation
+
+- new field or contract: run **New Field Threading**
+- transaction/retry/queue/background job: run **Retryable Persistence**
+- DTO/schema/type/persistence change: run **Runtime Contract Alignment**
+- cache or invalidation change: run **Cache Coherence**
+- server/AI/cache/fallback state merged into client state: run **State Merge Precedence**
+- preview/trace/summary/score/winner field: run **Aggregation Cardinality**
+
+## New Field Threading
+
+1. Search for the field name.
+2. Search nearby `build`, `apply`, `adjust`, `replan`, `normalize`, `merge`, `compile`, `serialize`, `clone`, and fallback helpers.
+3. Confirm the field survives primary construction, correction/replan paths, persistence reload, response serialization, and externally visible tests.
+
+## Retryable Persistence
+
+1. Read the whole transaction/retry callback.
+2. List outer-scope variables referenced inside it.
+3. Flag mutation of outer arrays, counters, iterators, derived inputs, or one-shot streams that changes behavior on retry.
+4. Compare transactional and non-transactional paths for parity.
+
+## Runtime Contract Alignment
+
+1. Compare DTO validation, internal type, persistence schema, normalization, API response shape, and frontend/state consumers.
+2. Treat `string` versus `ObjectId`, `Date` versus string, enum drift, and nested optional mismatches as review targets.
+3. Prefer boundary validation when malformed input should be rejected.
+
+## Cache Coherence
+
+1. Identify cache key inputs, tenant/user scope, feature flags, locale, and permissions.
+2. Confirm invalidation covers every write path and revalidation timing matches user-visible expectations.
+3. Check stale reads, cross-tenant leakage, and optimistic UI/cache rollback.
+
+## State Merge Precedence
+
+1. Identify precedence between user-entered state, server state, AI-generated state, fallback state, cache state, and defaults.
+2. Verify omitted fields, empty objects, `false`, `0`, or `null` cannot erase stronger user choices unless intended.
+3. Check both backend merge logic and frontend state update logic.
+
+## Aggregation Cardinality
+
+1. Determine whether source data is global, per-group, per-item, per-step, or per-tenant.
+2. Verify top-level summary/trace/score/winner fields do not collapse multiple meaningful entities into one misleading value.
+3. Treat `.find()`, first-selected, `sort()[0]`, and flat-array winner logic as suspicious when multiple groups can each have a result.

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

@@ -0,0 +1,35 @@
+# 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

@@ -0,0 +1,50 @@
+# 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

@@ -0,0 +1,82 @@
+---
+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

@@ -0,0 +1,6 @@
+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