claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/codex/skills/dev-orchestrator/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: dev-orchestrator
+description: Coordinate development through 16 phases (0-15) across planning, implementation, verification, and review gates when a task needs multiple dependent steps or consequential decisions.
+user-invocable: true
+tokens: 5197
+---
+
+# Development Orchestrator
+
+Run the development cycle for the user's request as 16 numbered phases (0-15). Read each referenced skill and preserve its authority and verdict contract. Use available, authorized delegation with explicit model/effort and scoped clean-context packets following project routing; otherwise execute suitable roles inline and disclose self-review. Do not waive a required independent or Astra acceptance gate when that capability is unavailable.
+
+## Task
+
+Parse the user's request to determine scope and parameters.
+
+## Codex Runtime and Skill Resolution
+
+Read the applicable `AGENTS.md` instructions and discover the current runtime's file, command, planning, and delegation capabilities before using them. Resolve each named role to an existing `SKILL.md` from the session's skill catalog or the project's `.agents/skills/<name>/SKILL.md` / `.codex/skills/<name>/SKILL.md`; these may be aliases of the same installation. Read that role directly and give delegated workers its resolved path, scoped task, authority, and evidence. A role name is not a registered agent type. Do not invoke a global skill loader or recursively restart this orchestrator to reach a role. The standalone install does not require a `.claude` tree, plugins, or documentation templates. Missing required expertise or tools remain explicit blockers; suitable inline passes are self-review, not independent acceptance.
+
+## Hard Rules
+
+1. Execute phases in order 0 -> 15. Skip a phase ONLY when the Skip Matrix says so for the task's declared complexity class.
+2. A phase is complete only when its **Done when** condition holds. If a phase produces errors, fix them before advancing.
+3. Consume gate verdicts exactly as produced: plan-checker -> PASS/REVISE/BLOCK; evaluator -> PROCEED/ITERATE/ESCALATE; goal-verifier -> PASS/NEEDS-ATTENTION/NEEDS-REMEDIATION; critic -> APPROVE/CONCERN/BLOCK.
+4. Gate roles review only. The coordinator assigns separately authorized implementation work for corrections. Reuse evidence bound to unchanged relevant code, inputs, environment, and command/results; rerun for relevant changes or concrete uncertainty. On retry, state what changed; a missing tool or evidence is not an observed defect.
+5. Never claim completion while mandatory criteria fail or remain unverified. Issue an incomplete checkpoint whenever blocked; the completion report requires every non-skipped phase to pass. Retry exhaustion is not acceptance.
+6. If the task is ambiguous, ask the user before Phase 7 (Implement) -- not after.
+7. Always read existing patterns before writing new code -- search first, reuse the closest implementation as reference.
+
+## Phase Overview & Skip Matrix
+
+Complexity (Simple / Standard / Complex) is decided in Phase 1 by risk and dependencies. Reassess it if new evidence changes the scope or risk; do not skip a required gate to preserve the original classification.
+
+| # | Phase | Simple | Standard | Complex | Gate skill |
+|---|-------|:------:|:--------:|:-------:|-----------|
+| 0 | Read Docs | yes | yes | yes | - |
+| 1 | Understand | yes | yes | yes | - |
+| 2 | Architect | - | - | yes | architect |
+| 3 | Pseudocode | - | - | yes | - |
+| 4 | Plan | yes | yes | yes | - |
+| 5 | Contract | - | yes | yes | - |
+| 6 | Validate Plan | - | yes | yes | plan-checker |
+| 7 | Implement | yes | yes | yes | - |
+| 8 | Evaluate | - | yes (max 2 passes) | yes (max 3 passes) | evaluator |
+| 9 | Verify | yes | yes | yes | health-checker |
+| 10 | Test | yes | yes | yes | test-generator |
+| 11 | Verify Goals | - | yes | yes | goal-verifier |
+| 12 | Review | yes | yes | yes | reviewer skills |
+| 13 | Critic | - | - | yes | critic |
+| 14 | Document | yes | yes | yes | docs-reviewer |
+| 15 | Report | yes | yes | yes | - |
+
+Simple skips phases 2, 3, 5, 6, 8, 11, 13. Standard skips 2, 3, 13. Complex runs all 16.
+
+## Phase 0 -- Read Docs
+
+Read `docs/architecture/` files relevant to the task scope:
+- Backend task -> `backend-layers.md`, `api-reference.md`, `database-schema.md`
+- Frontend task -> `frontend-state.md`
+- Auth task -> `auth-and-sessions.md`
+- Full-stack -> relevant cross-component contracts and architecture docs
+
+Missing docs are not an error -- note what was absent and continue.
+**Done when:** relevant existing docs are read (or confirmed absent).
+
+## Phase 1 -- Understand
+
+1. **Detect the stack** by scanning the repository root and subdirectories:
+
+   | Marker file | Stack |
+   |---|---|
+   | `go.mod` | Go backend |
+   | `package.json` + `tsconfig.json` | TypeScript (check for React, Vue, Svelte, etc.) |
+   | `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
+   | `Cargo.toml` | Rust |
+   | `pom.xml` / `build.gradle` | Java/Kotlin |
+   | `docker-compose.yml` | Docker infrastructure |
+   | `migrations/` or `db/migrate/` | Database migrations |
+
+2. **Parse the task**: affected components (backend, frontend, infra, bots, docs); feature / enhancement / bug fix / refactor; inputs and expected outputs.
+
+3. **Assess complexity** by consequences, coupling, and uncertainty. Simple means a narrow low-risk change following a proven pattern. Standard needs coordinated implementation and behavioral acceptance. Complex includes consequential architecture, security/authority, data-loss or irreversible changes, or unresolved design risk. File and line counts may inform effort, but cannot reduce risk or waive a mandatory gate.
+
+4. **Search the codebase** for existing related patterns: grep domain terms, endpoint paths, function names; read files that will be modified; check routing files and API specs (OpenAPI, GraphQL schema).
+
+5. **Identify the closest existing implementation** and read it -- it is the reference pattern for Phase 7.
+
+**Done when:** stack detected, complexity class declared, reference pattern read.
+
+## Phase 2 -- Architect (Complex only)
+
+Perform an architecture design pass following the **architect** skill:
+```
+Design the architecture for this task:
+Task: [description]
+Current architecture: [from Phase 0 docs]
+Affected components: [from Phase 1]
+Compare viable approaches and explain relevant trade-offs; do not invent alternatives.
+```
+Use the recommendation to shape Phase 4.
+**Done when:** one approach chosen, with a stated reason.
+
+## Phase 3 -- Pseudocode (Complex only)
+
+Draft language-agnostic pseudocode for the core logic (algorithm, state machine, data pipeline): input/output contract, main control flow, error paths, data transformations. 30-50 lines maximum -- longer means the task needs decomposition. No file paths, no framework syntax.
+
+Present to the user: "Here's the pseudocode for [core logic]. Does this match your expectations?"
+**Done when:** user approves (or explicitly waives) the pseudocode; it becomes the Phase 4 skeleton.
+
+## Phase 4 -- Plan
+
+Produce a checklist plan organized by component -- include only relevant sections. Use a discovered planning tool when available; otherwise maintain the checklist in the conversation or the project's existing plan file.
+
+```
+## Implementation Plan
+### Database
+- [ ] Migration: NNNN_description
+### Backend
+- [ ] Repository/data layer: path
+- [ ] Service/business logic: path
+- [ ] DTOs/schemas: path
+- [ ] Handler/controller: path
+- [ ] Routes: path
+- [ ] Tests: path
+### Frontend
+- [ ] Types / API client / state / component: paths
+### Infrastructure
+- [ ] Docker/config changes
+### Documentation
+- [ ] API spec, architecture docs, README
+```
+
+**Done when:** every planned item names a concrete file path.
+
+## Phase 5 -- Contract
+
+Write testable acceptance criteria -- Phase 8 evaluates exactly these:
+
+```
+## Sprint Contract
+| # | Criterion | Test Method | Threshold | Priority |
+|---|-----------|-------------|-----------|----------|
+| 1 | [specific, testable outcome] | [grep / curl / test / read] | Score >= 7 | MUST |
+| 2 | ... | ... | ... | MUST/SHOULD |
+```
+
+Threshold uses the evaluator's 0-10 scale -- default 7 unless a criterion warrants stricter. Good criteria are testable, specific ("returns 200 with user.id in JSON", not "endpoint works"), independent, and measurable. Never include subjective items ("code is clean") or unmeasurable ones ("performance is good").
+**Done when:** every criterion has a concrete test method.
+
+## Phase 6 -- Validate Plan
+
+Validate the Phase 4 plan plus Phase 5 contract following the **plan-checker** skill.
+- **PASS** -> Phase 7.
+- **REVISE** -> fix the blocking issues, re-validate (max 2 iterations, then treat as BLOCK).
+- **BLOCK** -> stop; present the issues to the user.
+**Done when:** verdict is PASS.
+
+## Phase 7 -- Implement
+
+Execute the plan in dependency order; for each step, read the reference pattern first, then implement.
+
+1. **Migration** -- follow the detected tool's actual format and ordering, existing database dialect, and project rollback policy. Use the installed **new-migration** skill for scaffolding when relevant. Creating files does not authorize database execution; use **migrate** only with verified target, action, and authority. Conditional DDL is not a guarantee against data loss, and not every tool supports paired up/down files or a lossless reverse.
+2. **Data layer** -- follow the project's existing data-access patterns (Go: pgx/sqlx/gorm, nil-safe repos, `fmt.Errorf("Context.Method: %w", err)`; Python: SQLAlchemy/Django ORM; TypeScript: Prisma/TypeORM/Drizzle).
+3. **Business logic** -- constructor DI via interfaces; Go: `context.Context` first param, domain errors; Python: type hints, async where applicable; TypeScript: strict types.
+4. **Transport** -- follow existing handler patterns (chi, gin, echo, express, FastAPI, etc.); input validation at the boundary; errors mapped to proper status codes.
+5. **Routes** -- register endpoints, apply auth/middleware.
+6. **Frontend** -- read existing components first (animation library, styling, state); API client and types matching the backend contract.
+
+**Done when:** every Phase 4 checklist item is implemented (no placeholders/TODOs left).
+
+## Phase 8 -- Evaluate
+
+Assess implementation against the Sprint Contract following the **evaluator** skill, passing the changed scope, bound evidence, pass number, and prior report. Preserve UNVERIFIED and N/A criterion results; never turn missing evidence into a zero score or a pass.
+- **PROCEED** -> Phase 9.
+- **ITERATE** -> assign the local correction or authorized evidence collection, then re-evaluate affected criteria as pass N+1. If the matrix budget is exhausted (Standard 2 / Complex 3), or correction makes no meaningful progress, stop this loop and report the unresolved mandatory criteria and next decision. Do not advance on a warning alone.
+- **ESCALATE** -> route the stated cause: architect/Astra for design or consequential acceptance; contract owner for requirements; appropriate owner for missing authorization, tool, or external evidence. Resume at the affected phase only after resolution.
+**Done when:** verdict is PROCEED and mandatory evidence is sufficient. Otherwise report incomplete.
+
+## Phase 9 -- Verify
+
+Follow the **health-checker** skill if present with the selected components, relevant compilation/build/static checks, and any other mandatory verification explicitly required by the task/project. Declare that scope; do not automatically run its entire nine-domain dashboard or let optional checks redefine this phase. Otherwise discover the project's actual configured commands and available tools, inspect effects, and run those same selected checks directly. Keep build/compilation separate from static analysis (for example, `go vet` alone is not a build); do not use a launcher that installs missing tools.
+
+Keep this verification pass read-only apart from authorized disposable build/test outputs. Preserve original command exits, failed/timeout/unavailable states, full appropriately redacted evidence, and actual test skips; a shortened log or formatter exit is not the check result. Reuse recorded checks only for unchanged relevant code, inputs, and environment. Corrections belong to the coordinator or authorized implementer, not the health report.
+
+**Done when:** all declared mandatory Phase 9 checks pass with sufficient evidence and no blocking result remains; if using health-checker, Progression must be ALLOWED. Optional warnings/unknowns remain explicit and do not block by themselves. An unavailable, skipped, or unverified mandatory check leaves this phase incomplete; report its dependency instead of endlessly retrying it.
+
+## Phase 10 -- Test
+
+Generate or update tests for the new/changed backend behavior in scope following the **test-generator** skill and existing runner/conventions. Select meaningful happy/failure/boundary/state cases from requirements or observed defects; no mandatory case quota or implementation-mirroring assertions. The generator owns scoped test/fixture edits and authorized focused execution; the coordinator owns required suite verification and assigns production fixes only within existing implementation authority. Do not weaken tests to obtain green results.
+
+Record actual commands, exits, passed/failed/skipped cases, and missing runtime evidence. A valid red regression test may complete a test artifact but does not pass this development gate. Reuse unchanged, properly bound focused or suite evidence instead of repeating it by ritual; run the required project suite for the final relevant state.
+**Done when:** required tests actually ran and passed, required coverage is satisfied, and no mandatory skipped/unverified result remains (include the actual final summary line and command). If a required check or authorized correction is unavailable, report the bounded blocker; do not treat a failed, unrun, or all-skipped suite as green.
+
+## Phase 11 -- Verify Goals
+
+Verify results against Phase 4 goals following the **goal-verifier** skill, passing changed scope and bound evidence. It assesses applicable levels: EXISTS -> SUBSTANTIVE -> WIRED -> DATA-FLOW; preserve justified N/A and unresolved UNVERIFIED results.
+- **PASS** -> Phase 12.
+- **NEEDS-ATTENTION** -> distinguish local fixes from missing evidence. Assign bounded corrections/checks, or report the dependency; never repeatedly retry an unavailable capability.
+- **NEEDS-REMEDIATION** -> substantive goal mismatch or missing capability; return to Phase 7 (or Phase 4 if the plan itself was wrong).
+**Done when:** verdict is PASS.
+
+## Phase 12 -- Review
+
+First, a 30-second inline self-pass on the diff: (a) no placeholders/TODOs/`unimplemented`, (b) types/signatures consistent with callers, (c) every acceptance criterion has a corresponding change. Fix the obvious now.
+
+Then perform matching reviews with available skills and authorized delegation; inline passes are self-review. Use the mapping below to identify relevant expertise, and scope each pass to actual risk and requirements:
+
+| Changed files | Skill |
+|---|---|
+| `*.go` (not migrations, not tests) | **go-reviewer**, **security-scanner** |
+| `*.sql` migrations | **migration-reviewer**, **database-reviewer** |
+| Data-access files (`*_repo.go`, repositories) | **database-reviewer** |
+| `*.ts`, `*.tsx` | **ts-reviewer** |
+| `*.py` | **py-reviewer**, **security-scanner** |
+| `*.rs` | **rs-reviewer** |
+| Bot code | **bot-reviewer** |
+| UI components | **design-system-reviewer**, **ui-reviewer** |
+| OpenAPI/GraphQL spec changed | **api-contract-sync** |
+| Any changed code | **silent-failure-hunter**, **comment-rot-analyzer** |
+
+For each skill, review the selected diff/base and changed-file list against the task description, applying that skill's two-stage discipline (discover, then triage by Severity + Confidence). Keep reviewer passes read-only; assign corrections separately within existing implementation authority. Preserve each report's coverage, evidence, and unresolved prior findings.
+
+Triage findings -- route, don't drop:
+- CRITICAL or WARNING at HIGH/MEDIUM confidence -> fix before proceeding.
+- LOW confidence / ambiguous -> carry into the **Open Questions** section of the Phase 15 report.
+- A clean review (0 findings) is a valid result -- do not pad it.
+- For silent-failure-hunter and comment-rot-analyzer, incomplete required coverage or a mandatory UNVERIFIED condition blocks progression without becoming a defect. Optional uncertainty may remain explicitly non-blocking; an Open Questions entry does not waive required evidence.
+
+**Done when:** all CRITICAL/WARNING findings fixed or explicitly deferred with reason within the task's acceptance rules, and no mandatory review evidence/coverage remains unresolved. If the required check cannot be completed, report the dependency and stop this phase instead of retrying indefinitely.
+
+## Phase 13 -- Critic (Complex only)
+
+Perform a final quality gate following the **critic** skill over the changed scope, original task, and Phase 12 findings/evidence. Use relevant security, maintainer, and operations perspectives without a findings or predictions quota.
+- **APPROVE** -> Phase 14.
+- **CONCERN** -> address or document explicit non-blocking disposition; advance only when Progression is ALLOWED and no mandatory evidence/acceptance is missing.
+- **BLOCK** -> resolve the stated defect, evidence gap, or acceptance dependency. Recheck affected scope; if it cannot be resolved within authority/capability, report incomplete.
+**Done when:** verdict is APPROVE, or CONCERN with ALLOWED progression and justified non-blocking disposition. Repeated unsuccessful correction requires a bounded escalation, not an endless review loop.
+
+## Phase 14 -- Document
+
+Verify documentation completeness and accuracy for the selected changes following the **docs-reviewer** skill and the project's actual documentation map. The reviewer reports evidence and proposed corrections read-only; the coordinator or assigned implementer performs these updates within already-authorized scope:
+1. **API spec** (OpenAPI/GraphQL) if endpoints changed.
+2. **Architecture docs** if system behavior changed.
+3. **README** if setup, commands, or structure changed.
+**Done when:** applicable mandatory documentation has been reviewed, required updates verified, and no unresolved mandatory MISSING, STALE, BROKEN, DRIFT, or UNVERIFIED items remain. Preserve justified N/A and optional suggestions; no MISSING findings alone is not acceptance. Recheck affected claims after corrections, retaining prior unresolved items. If a required source/check is unavailable, report incomplete and the next owner/action; do not silently advance or repeat an unavailable check indefinitely.
+
+## Phase 15 -- Report
+
+Emit only after all non-skipped phases completed:
+
+```
+## Development Report
+
+### Task
+[Original task description]
+
+### Phases Executed
+| # | Phase | Status | Notes |
+|---|-------|--------|-------|
+| 0 | Read Docs | done | N docs read |
+| 1 | Understand | done | [components], [complexity] |
+| 2 | Architect | done/skipped | [approach chosen / not Complex] |
+| 3 | Pseudocode | done/skipped | |
+| 4 | Plan | done | N items |
+| 5 | Contract | done/skipped | N criteria |
+| 6 | Validate Plan | done/skipped | PASS after N iterations |
+| 7 | Implement | done | N created, M modified |
+| 8 | Evaluate | done/skipped | PROCEED at pass N |
+| 9 | Verify | done | compilation clean |
+| 10 | Test | done | X tests green |
+| 11 | Verify Goals | done/skipped | PASS (all applicable mandatory levels) |
+| 12 | Review | done | [skills]: N findings fixed |
+| 13 | Critic | done/skipped | APPROVE |
+| 14 | Document | done | [docs updated] |
+| 15 | Report | done | this report |
+
+### Changes Made
+| File | Action | Description |
+|------|--------|-------------|
+
+### Open Questions (LOW-confidence review items -- surfaced, not dropped)
+- file:line -- suspicion + what would confirm it (omit section if none)
+
+### Metrics
+| Metric | Value |
+|--------|-------|
+| Complexity | Simple / Standard / Complex |
+| Skill passes | N (list) |
+| Evaluator passes | N (ITERATE -> ... -> PROCEED) |
+| Sprint contract | X/Y criteria met |
+
+### Suggested Commit Message
+type(scope): description
+```
+
+Co-authorship trailers are optional; do not add one unless the project explicitly requires it.
+
+## Recap -- non-negotiables
+
+- Phases run in order 0 -> 15; the Skip Matrix is the only source of skips.
+- Gate verdicts consumed verbatim (plan-checker PASS/REVISE/BLOCK, evaluator PROCEED/ITERATE/ESCALATE, goal-verifier PASS/NEEDS-ATTENTION/NEEDS-REMEDIATION, critic APPROVE/CONCERN/BLOCK); failed gate -> retry with the critique in context and say so.
+- No completion claims over failed or unverified mandatory criteria; report incomplete at a blocker instead of advancing or hiding it behind exhausted retries.
+- LOW-confidence findings go to Open Questions, never silently dropped.
+- Conventional commits: `feat|fix|docs|refactor|chore|test|perf(scope): description`.

package/packages/codex/skills/docs-reviewer/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: docs-reviewer
+description: Review documentation freshness, accuracy, and required coverage against selected changes and actual project evidence. Distinguish confirmed drift from unavailable verification.
+user-invocable: false
+tokens: 2176
+---
+
+# Docs Reviewer
+
+Check whether documentation makes accurate claims about the requested scope and meets the project's applicable documentation requirements. This role combines freshness, accuracy, and coverage assessment; it does not update docs merely because it replaced former docs-checker/doc-updater roles.
+
+## Establish the documentation contract
+
+Read applicable `AGENTS.md` first, then relevant conventions and the actual documentation map. Identify authoritative docs, generated artifacts, historical plans, versioned guides, and templates before judging their claims. Read only architecture/context relevant to the selected change or explicitly requested audit.
+
+For a Codex installation, compare any skill inventory or routing claim in `AGENTS.md` with the actual installed skill locations (for example `.codex/skills/<name>/SKILL.md`) and relevant `.codex/config.toml` configuration. Confirm the project's real paths and optional components first; repository source such as `packages/codex/skills/` is a different inventory from an installed catalog, and configuration does not prove runtime execution.
+
+Use the caller's exact base/head, working-tree diff, or named documentation scope. Do not default to the last five commits or assume `main`. Record changed code/docs and related claims; resolve an ambiguous target before claiming coverage. Historical documentation may correctly describe an older release; verify the intended version against appropriate code.
+
+Review only: return proposed corrections for the coordinator or a separately authorized editing step. Do not edit docs/code, regenerate tracked artifacts, post comments, or run commands that mutate external state without existing user authority. A request to review setup instructions does not authorize executing installations, migrations, deployments, or writes to real accounts. Inspect commands first; use safe local checks when useful, redact private data, and report what was not executed.
+
+Honor task/project routing. Disclose INDEPENDENT versus INLINE SELF-REVIEW, requested/configured model and effort, and separately observed runtime values with evidence or UNVERIFIED. Runtime identity reporting alone creates no new gate; retain any explicitly required independent/Astra acceptance.
+
+## Review claims against evidence
+
+### Freshness: changed behavior to affected claims
+
+Map changed interfaces, behavior, configuration, storage, or structure to the maintained docs that describe them. Use actual references and project rules, not a universal filename checklist. API handlers may map to OpenAPI or inline API docs; a database change may map to a generated schema instead of `database-schema.md`.
+
+An unchanged doc is a candidate for inspection, not proof of staleness. A changed doc is not proof of correctness. Compare the relevant claim to before/after behavior and assess whether an update is required. Refactors, tests, and bug fixes that restore documented behavior often need no narrative update; a project's explicit changelog/tree requirements may still apply. Config changes need docs when their usage or a binding rule requires it.
+
+### Accuracy: inspect the source behind each relevant assertion
+
+- Verify file paths, symbols, command names/flags, configuration keys/defaults, dependency versions, and installation steps against actual files and supported project versions. A file's absence locally may mean generated output, a different documented version, or missing checkout content; distinguish those cases.
+- Check API routes and request/response/error contracts in route registration and implementation, including relevant feature flags and callers. A handler count is not automatically an endpoint count.
+- Verify migration/schema and component/skill counts with a defined inclusion rule and source tree. Do not compare installed, optional, generated, and shipped inventories as if they were identical.
+- Compare architecture, feature behavior, operational constraints, and plan status to implementation and acceptance evidence. Source presence does not prove a deployed feature works, a constraint is resolved, or a plan is complete.
+- For documented commands, distinguish source inspection from execution. Record the actual command/result/environment if run; an unexecuted example is UNVERIFIED where runtime evidence is required, not automatically incorrect. Failed setup due to unavailable credentials/network is not proof the documented command is wrong.
+- Check relevant links/references when permitted and necessary. Authentication failures, rate limits, unavailable network, or suspicious-looking URLs do not establish a broken link.
+
+### Coverage: apply the real documentation map
+
+Identify which changed capabilities must be documented under project rules or the user task, and where that information belongs. Do not demand a separate architecture file for every code directory or introduce a new documentation system. Use **MISSING** for a confirmed required document or required content that is absent, including an unfilled template when it is the required source of usable instructions. An optional topic can be suggested without blocking acceptance.
+
+Templates and TODOs are not stale factual claims merely because they are incomplete. Old release notes, examples, and superseded plans should be judged according to their stated purpose. Mark genuinely inapplicable checks N/A with a reason; do not treat missing access as N/A.
+
+## Classification and evidence
+
+Keep existing finding labels for callers:
+- **STALE:** a descriptive claim is out of sync with the target behavior/version, including an incorrect new claim that was never accurate.
+- **BROKEN:** a reference or instruction demonstrably points to a nonexistent/invalid target for its stated context.
+- **DRIFT:** a verified count/inventory differs under the same definition and target version.
+- **MISSING:** required documentation or required content is confirmed absent.
+
+An **INCORRECT** claim is a confirmed contradiction, reported under the applicable existing label above (STALE for descriptive claims, BROKEN for references, DRIFT for counts); it is not UNVERIFIED. These labels are issue types, not a severity ladder. Give each finding its mandatory/non-blocking status and user impact. Do not relabel a false claim MISSING merely to satisfy a caller gate.
+
+**UNVERIFIED** is an evidence state, not a defect label: record the unavailable source, unexecuted required check, uncertain applicability, or unreviewed area and the decision/check needed. **OK** means the applicable claim was checked against sufficient evidence; **N/A** needs a stated applicability reason. Unverified mandatory docs block acceptance even with zero MISSING findings.
+
+Cite the exact doc location and actual code/config/command evidence for each finding. For an absent document, cite the requirement and searched location/scope rather than inventing a doc line. Reuse verification only with recorded command/results and unchanged relevant code, inputs, and environment. Preserve prior unresolved findings by reference; a later narrow pass cannot erase them.
+
+## Report and stop
+
+```text
+Documentation Review Report
+Scope: <selected diff/version/docs, relevant requirements and exclusions>
+Coverage: COMPLETE | PARTIAL | UNAVAILABLE — <reviewed and unreviewed areas>
+Execution: INDEPENDENT | INLINE SELF-REVIEW
+Requested model/effort: <explicit route or labeled configured default; UNSPECIFIED if absent>
+Observed model/effort: <values + runtime evidence, or UNVERIFIED>
+
+Claim/document | Requirement/trigger | Evidence | Status (OK/N/A/UNVERIFIED or issue label)
+
+[STALE|BROKEN|DRIFT|MISSING] doc:line or <missing path + requirement reference>
+  Actual claim / expected behavior: <precise discrepancy>
+  Evidence and impact: <source/check + why it matters>
+  Required: YES | NO — <binding rule or optional improvement>
+  Fix: <specific proposed update>
+
+Verification: <actual commands/results, source-only checks, and reuse binding>
+Prior findings: <unresolved references/disposition, or none>
+Open Questions: <missing evidence/applicability and next owner/check, or none>
+Progression: ALLOWED | BLOCKED — <mandatory documentation conditions>
+Summary: <checked scope, confirmed issues, unverified items, justified N/A>
+```
+
+Stop after the scoped review or when required evidence is unavailable. A clean result needs complete assigned coverage and satisfied mandatory documentation conditions, not merely zero MISSING items. Keep optional proposals separate. Route corrections to the authorized implementation owner and recheck affected claims after changes; do not demand repeated full audits or retry inaccessible sources indefinitely.

package/packages/codex/skills/drizzle-orm-expert/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: drizzle-orm-expert
+description: Expert in Drizzle ORM for TypeScript — schema design, relational queries, migrations, serverless DB integration. Use when building type-safe database layers with Drizzle, migrating from Prisma, or optimizing edge runtime DB access
+user-invocable: false
+---
+
+# Drizzle ORM Expert
+
+TypeScript-first ORM that compiles to raw SQL with zero runtime overhead. Ideal for edge runtimes and serverless. Two complementary APIs: SQL-like query builder and Prisma-style relational queries.
+
+## Use this skill when
+
+- Setting up Drizzle ORM in a new or existing project
+- Designing database schemas with Drizzle's TypeScript-first approach
+- Writing complex relational queries (joins, subqueries, aggregations)
+- Setting up or troubleshooting Drizzle Kit migrations
+- Integrating Drizzle with Next.js App Router, tRPC, or Hono
+- Optimizing performance (prepared statements, batching, pooling)
+- Migrating from Prisma, TypeORM, or Knex
+
+## Do not use this skill when
+
+- The DB layer uses Prisma, TypeORM, or raw SQL exclusively
+- You need a database-agnostic ORM guide
+- The task is about DB server configuration (use `postgresql-optimization`)
+
+## Workflow
+
+1. Identify the DB driver (PostgreSQL, SQLite, MySQL) and select the adapter
+2. Define schema in `db/schema.ts` (or domain-split `db/schema/users.ts`)
+3. Define relations separately so the relational query API (`db.query.*`) works
+4. Use `InferSelectModel` and `InferInsertModel` for type inference — never manual interfaces
+5. Run `drizzle-kit generate` then `migrate` for schema changes in production
+6. **Never** use `drizzle-kit push` in production
+
+## Core Architecture
+
+Drizzle ORM compiles TypeScript schema definitions into prepared SQL statements at build time. There is no runtime query engine binary (unlike Prisma), which makes it edge-compatible (Cloudflare Workers, Vercel Edge Functions, Deno Deploy).
+
+Two APIs coexist:
+- **SQL-like builder**: `db.select().from().where().join().orderBy()` — close to SQL semantics
+- **Relational query API**: `db.query.users.findMany({ with: { posts: true } })` — Prisma-style nested fetching
+
+## Schema Design
+
+```typescript
+import { pgTable, uuid, text, timestamp, pgEnum, index, uniqueIndex } from 'drizzle-orm/pg-core';
+
+export const roleEnum = pgEnum('role', ['admin', 'user', 'guest']);
+
+export const users = pgTable('users', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  email: text('email').notNull().unique(),
+  role: roleEnum('role').default('user').notNull(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+}, (table) => ({
+  emailIdx: uniqueIndex('users_email_idx').on(table.email),
+  createdIdx: index('users_created_idx').on(table.createdAt),
+}));
+
+export const posts = pgTable('posts', {
+  id: uuid('id').defaultRandom().primaryKey(),
+  userId: uuid('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(),
+  title: text('title').notNull(),
+});
+```
+
+## Relations API
+
+```typescript
+import { relations } from 'drizzle-orm';
+
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.userId], references: [users.id] }),
+}));
+
+// Initialize client WITH schema for db.query.* to work:
+import { drizzle } from 'drizzle-orm/node-postgres';
+import * as schema from './schema';
+export const db = drizzle(pool, { schema });
+```
+
+Many-to-many requires an explicit junction table — Drizzle has no implicit join tables.
+
+## Queries
+
+### SQL-like builder
+```typescript
+import { eq, and, desc, count } from 'drizzle-orm';
+
+const recent = await db
+  .select({ id: posts.id, title: posts.title, author: users.email })
+  .from(posts)
+  .innerJoin(users, eq(users.id, posts.userId))
+  .where(and(eq(users.role, 'user'), eq(posts.published, true)))
+  .orderBy(desc(posts.createdAt))
+  .limit(20);
+```
+
+### Relational
+
+In `db.query.<table>.findMany`, the `where` / `orderBy` clauses can be either a value built from the imported schema's table (`eq(users.role, 'user')`) or, with the latest relational query builder, a callback that receives the table:
+
+```typescript
+import { users, posts } from './schema';
+
+const activeUsers = await db.query.users.findMany({
+  where: (user, { eq }) => eq(user.role, 'user'),
+  orderBy: (user, { desc }) => desc(user.createdAt),
+  with: {
+    posts: {
+      where: (post, { eq }) => eq(post.published, true),
+      limit: 5,
+    },
+  },
+  limit: 20,
+});
+```
+
+Both forms work. The callback form avoids shadowing the imported `users` table when the local result variable would otherwise collide.
+
+## Mutations
+
+```typescript
+// Insert + returning (Postgres only)
+const [inserted] = await db.insert(users).values({ email: 'a@b.c' }).returning();
+
+// Batch
+await db.insert(users).values([{ email: 'x@x' }, { email: 'y@y' }]);
+
+// Update
+await db.update(users).set({ role: 'admin' }).where(eq(users.id, id));
+
+// Delete
+await db.delete(posts).where(eq(posts.userId, id));
+
+// Upsert
+await db.insert(users)
+  .values({ id, email })
+  .onConflictDoUpdate({ target: users.id, set: { email } });
+```
+
+## Transactions
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.insert(orders).values(order);
+  await tx.update(inventory).set({ stock: sql`stock - 1` });
+  // any throw → rollback
+});
+```
+
+## Drizzle Kit
+
+```bash
+drizzle-kit generate    # write SQL migration files (review them)
+drizzle-kit migrate     # apply pending migrations — production
+drizzle-kit push        # sync schema directly — DEV ONLY, NEVER prod
+drizzle-kit studio      # GUI database browser
+```
+
+`drizzle.config.ts`:
+```typescript
+import type { Config } from 'drizzle-kit';
+export default {
+  schema: './db/schema.ts',
+  out: './db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: { url: process.env.DATABASE_URL! },
+} satisfies Config;
+```
+
+## Adapters
+
+| DB | Adapter |
+|---|---|
+| Postgres (Neon) | `drizzle-orm/neon-http` |
+| Postgres (node-pg) | `drizzle-orm/node-postgres` |
+| Postgres (postgres.js) | `drizzle-orm/postgres-js` |
+| SQLite (Turso) | `drizzle-orm/libsql` |
+| SQLite (local) | `drizzle-orm/better-sqlite3` |
+| MySQL (PlanetScale) | `drizzle-orm/planetscale-serverless` |
+| MySQL (mysql2) | `drizzle-orm/mysql2` |
+
+Always pass `{ schema }` to enable `db.query.*`.
+
+## Type Inference
+
+```typescript
+import { InferSelectModel, InferInsertModel } from 'drizzle-orm';
+type User = InferSelectModel<typeof users>;
+type NewUser = InferInsertModel<typeof users>;
+```
+
+Never write manual TS interfaces for DB rows — schema is the source of truth.
+
+## Performance
+
+- **Prepared statements** for hot paths: `.prepare('getUser')` once, execute many times
+- **Partial select**: choose only needed columns
+- **Batch**: `db.batch([...])` for many independent queries in one round-trip (libsql / d1 only)
+- **Indexes**: declare `index()` / `uniqueIndex()` inside the table builder
+
+## Next.js Integration
+
+```typescript
+// app/dashboard/page.tsx — Server Component
+import { db } from '@/db';
+
+export default async function Dashboard() {
+  const allUsers = await db.query.users.findMany({ limit: 20 });
+  return <UsersList users={allUsers} />;
+}
+```
+
+```typescript
+// Server Action
+'use server';
+import { db } from '@/db';
+export async function createUser(formData: FormData) {
+  await db.insert(users).values({ email: formData.get('email') as string });
+}
+```
+
+## Constraints
+
+- **NEVER** use `drizzle-kit push` in production — can cause data loss
+- **NEVER** write raw SQL when the query builder supports the op
+- **ALWAYS** define `relations()` before using `db.query.*` with `with`
+- **ALWAYS** use connection pooling (`pgBouncer`, `Neon serverless`, `node-pg Pool`)
+- **MySQL** doesn't support `.returning()` — read `insertId` from the result
+
+## Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `db.query.users` is undefined | `{ schema }` not passed to `drizzle()` | Pass schema |
+| Migration conflict | Out-of-sync DB state | `generate` new migration, review SQL, `migrate` |
+| Type error on `relations` | Forgot to `export const usersRelations = relations(...)` | Add export |
+| Slow query in Edge runtime | New connection per request | Use a serverless adapter (Neon, PlanetScale) or HTTP-based driver |
+
+Adapted from VKirill/codex-starter-kit (Apache 2.0 community skill).