codexkit 1.0.0

package/.codex/skills/repo-orientation/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: repo-orientation
+description: Understand codebase structure, stack, conventions, and architecture before implementation work.
+---
+# repo-orientation
+
+## Purpose
+Build a reliable mental model of the repository before editing code.
+
+## Use This Skill When
+- Starting a new session
+- Onboarding to an unfamiliar repository
+- Context feels stale or contradictory
+- Planning changes across multiple modules
+
+## Workflow Phases
+1. Initial scan
+2. Tech stack identification
+3. Convention discovery
+4. Architecture mapping
+
+## Expected Outputs
+- Brief codebase summary
+- Key files and entry points
+- Conventions and constraints
+- Known risks and unknowns
+
+## Success Indicators
+- Can name runtime, language, package manager, and test framework
+- Can point to the primary entrypoint and two core modules
+- Can list five local conventions with file evidence
+- Can propose safe first-change locations
+
+## Phase Detail
+
+### 1) Initial Scan
+- Map top-level directories; mark generated output folders.
+- Locate entrypoints (`src/index.*`, `cli.*`, `cmd/*`).
+- Separate source, tests, scripts, docs, and artifacts.
+- Read README/setup docs for expected dev loop.
+
+Deliverable: one-paragraph map of layout and intent.
+
+### 2) Tech Stack Identification
+- Detect runtime/language from manifests.
+- Identify package manager via lockfile.
+- Capture lint/typecheck/test/build commands.
+- Confirm minimum versions from engines/toolchain configs.
+
+Deliverable: toolchain matrix (runtime, package manager, build, lint, test).
+
+### 3) Convention Discovery
+- Inspect 5-10 representative files across modules.
+- Capture naming and file organization patterns.
+- Capture error handling, logging, and import boundaries.
+- Capture test file placement and naming style.
+
+Deliverable: convention list with examples.
+
+### 4) Architecture Mapping
+- Sketch major module boundaries.
+- Trace one full path: input → orchestration → side effects.
+- Identify integration points (filesystem, network, db, queues).
+- Mark hotspots (high churn, global state, dynamic loading).
+
+Deliverable: architecture sketch and risk hotspots.
+
+## Quick Reference Commands
+```bash
+# Top-level structure
+find . -maxdepth 2 -type d | sort
+
+# Scripts and quality gates
+cat package.json | jq '.scripts'
+
+# Entrypoints and command wiring
+grep -R "\.command(\|from 'cac'\|new CAC" src --line-number
+
+# Core configs
+find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "vitest*.ts" -o -name "oxlint*" \) | sort
+
+# Test topology
+find src \( -name "*.test.ts" -o -name "*.spec.ts" \) | head -40
+
+# Recent churn clues
+git log --oneline -- src | head -30
+```
+
+## Common Patterns
+
+### Pattern: Command-Driven Layout
+Entrypoint wires commands; handlers live in `src/commands/*`; shared primitives in `src/utils/*`.
+Use it by tracing entrypoint → registration → one handler before diving into utilities.
+
+### Pattern: Validation at Boundaries
+Input checks happen near command boundaries before side effects.
+Look for schema parse/guard calls at handler start.
+
+### Pattern: Generated Output Separation
+Build output folders are regenerated, not hand-edited.
+Identify source-of-truth paths first.
+
+### Pattern: Colocated Tests
+Tests near source modules act as executable behavior docs.
+Use nearest tests to quickly infer intent and edge cases.
+
+## Anti-Patterns
+| Anti-pattern | Why it hurts | Correct move |
+|---|---|---|
+| Starting in random utilities | Misses execution context | Start at entrypoint and follow wiring |
+| Importing conventions from other repos | Introduces style drift | Derive conventions from local evidence |
+| Reading docs only | Docs may lag behavior | Cross-check with source |
+| Mapping only by filenames | Misses runtime connections | Trace imports and registrations |
+| Editing generated folders | Changes are overwritten | Confirm authoritative source path |
+
+## Orientation Checklist
+- [ ] Identify authoritative source vs generated output folders
+- [ ] Locate startup and registration path
+- [ ] Capture runtime, package manager, and quality gates
+- [ ] Read one test file in each core area
+- [ ] Record one high-churn hotspot and one uncertainty
+
+## Evidence Standards
+- Architecture claim → at least one file path.
+- Tooling claim → command or config evidence.
+- Safe first-change recommendation → low-risk target with rationale.
+- Conflicting signals → explicitly documented.
+
+## Output Format
+```markdown
+## Codebase Summary
+- one paragraph
+
+## Stack Card
+- Runtime:
+- Language:
+- Package manager:
+- Build/Lint/Test:
+
+## Entrypoints
+- `path`: role
+
+## Conventions (with evidence)
+- convention -> `path`
+
+## Risk Hotspots
+- module: reason + risk
+
+## Safe First-Change Locations
+- `path`: why safe
+```
+
+## Exit Conditions
+- Another engineer can start implementation without re-scanning.
+- At least one full execution path is documented.
+- Risks and unknowns are explicit.

package/.codex/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: requesting-code-review
+description: Use when completing meaningful implementation work and needing a high-signal review pass before merge or release - dispatches scoped review agents, synthesizes findings, and routes follow-up actions by severity.
+version: 1.0.0
+tags: [workflow, code-quality, research]
+dependencies: []
+---
+
+# Requesting Code Review
+
+## Overview
+
+Request review when work is **potentially shippable** and you need fresh scrutiny before moving on.
+
+This skill is for **asking for review**, not blindly obeying reviewers. The review output is advisory until verified against the codebase.
+
+**Core principle:** tighter review packet → better findings. Fewer files + clearer requirements beats dumping a vague diff at five agents.
+
+## When to Use
+
+- After completing a feature, bugfix, or meaningful task batch
+- Before merging to main or creating a PR
+- Before release or after a risky refactor
+- When you need multiple review angles on the same implementation
+
+## When NOT to Use
+
+- During TDD RED phase or any intentionally failing state
+- When you only need a single targeted technical answer
+- When implementation is still obviously incomplete and review would be premature
+
+## Golden Path
+
+1. **Stabilize the work** — run the relevant verification first
+2. **Build a tight review packet** — what changed, requirements, diff range, notable risks
+3. **Choose review depth** — targeted, standard, or full multi-angle review
+4. **Dispatch review agents in parallel**
+5. **Deduplicate + synthesize findings**
+6. **Fix or push back with evidence**
+7. **Re-verify after changes**
+
+## Review Packet
+
+Before dispatching any reviewer, assemble a packet with:
+
+- **What changed** — 2-6 bullet summary
+- **Requirements / plan** — acceptance criteria or plan excerpt
+- **Diff range** — `BASE_SHA..HEAD_SHA`
+- **Risk hints** — auth, migrations, concurrency, data deletion, perf-sensitive path, etc.
+- **Verification already run** — typecheck/lint/test/build status
+
+Minimal packet template:
+
+```markdown
+What was implemented:
+
+- [change 1]
+- [change 2]
+
+Requirements:
+
+- [acceptance criterion 1]
+- [acceptance criterion 2]
+
+Diff:
+
+- BASE_SHA: {BASE_SHA}
+- HEAD_SHA: {HEAD_SHA}
+
+Already verified:
+
+- [command] — [result]
+
+Risk areas:
+
+- [auth | migrations | concurrency | performance | none]
+```
+
+## Review Depth Selection
+
+Choose the smallest review depth that still covers the risk.
+
+| Depth        | Use When                                    | Agents |
+| ------------ | ------------------------------------------- | ------ |
+| **targeted** | Small fix, one main risk, one area changed  | 1-2    |
+| **standard** | Typical feature/fix ready for merge         | 3      |
+| **full**     | Risky, cross-cutting, release-critical work | 5      |
+
+### Routing Rules
+
+- **targeted**: use 1-2 specific review prompts
+- **standard**: use security/correctness, tests/types, and completeness
+- **full**: use all 5 specialized review prompts
+
+Do **not** dispatch 5 reviewers by reflex for every tiny change. That produces noise, not rigor.
+
+## Review Scope Self-Check
+
+Before writing ANY review finding, the reviewer MUST ask:
+
+> **"Am I questioning APPROACH or DOCUMENTATION/CORRECTNESS?"**
+
+| Answer | Action |
+| --- | --- |
+| **APPROACH** — "I would have done it differently" | **Stay silent.** The approach was decided during planning. Review doesn't re-litigate design. |
+| **DOCUMENTATION** — "A new developer couldn't execute this" | **Raise it.** Missing file paths, vague acceptance criteria, assumed context. |
+| **CORRECTNESS** — "This will break at runtime" | **Raise it.** Bugs, security holes, type errors, logic flaws. |
+
+### Red Flags for Scope Creep
+
+- Suggesting alternative libraries or frameworks → **out of scope** (approach)
+- "I would rename this to..." without a concrete bug → **out of scope** (style preference)
+- "Consider adding feature X" that wasn't in requirements → **out of scope** (scope inflation)
+- "This could be more performant" without evidence of a real problem → **out of scope** (premature optimization)
+
+### What Reviewers SHOULD Flag
+
+- Missing error handling that will crash in production → **correctness**
+- Vague acceptance criteria that workers can't verify → **documentation**
+- Hardcoded values with no explanation → **documentation**
+- Missing file paths for tasks that require edits → **documentation**
+- "Use the existing pattern" without specifying which pattern → **documentation**
+- Security vulnerabilities (injection, auth bypass, secrets) → **correctness**
+
+Include this self-check instruction in EVERY review dispatch prompt to prevent bikeshedding.
+
+## Step 1: Get Git Context
+
+### Setup Checklist
+
+- [ ] Determine `BASE_SHA` and `HEAD_SHA`
+- [ ] Summarize requirements or link plan
+- [ ] Decide review depth
+
+```bash
+BASE_SHA=$(git rev-parse origin/main 2>/dev/null || git rev-parse HEAD~1)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+If work is still uncommitted, use the working tree review path and clearly say so in the review packet.
+
+## Step 2: Dispatch Reviewers in Parallel
+
+### A. Security + Correctness
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Security + correctness review",
+  prompt: `Review this implementation for real bugs in changed code only.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Security vulnerabilities (injection, auth bypass, secrets exposure, missing validation)
+- Logic errors, null/undefined access, incorrect guards
+- Broken async/error handling
+- Data integrity issues
+
+Rules:
+- Review only changed code
+- Read full changed files for context before flagging issues
+- Do not speculate; explain the concrete failure scenario
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references
+- brief reasoning for each finding`,
+});
+```
+
+### B. Performance + Architecture
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Performance + architecture review",
+  prompt: `Review this implementation for performance and architecture issues.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Obviously expensive loops / N+1 / repeated work
+- Over-engineering or abstraction without clear value
+- Coupling that will make maintenance painful
+- Missing use of existing abstractions/utilities
+
+Rules:
+- Flag only meaningful issues
+- Skip style-only comments unless they cause structural problems
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### C. Type Safety + Test Quality
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Type safety + test review",
+  prompt: `Review this implementation for type safety and test quality.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Unsafe assertions, type holes, lossy casts
+- Missing coverage on important branches or edge cases
+- Tests that only prove mocks, not behavior
+- Tests that would still pass if implementation were wrong
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### D. Conventions + Existing Patterns
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Conventions + patterns review",
+  prompt: `Review this implementation against existing codebase patterns.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+  git log --oneline -10
+
+Check for:
+- Divergence from existing code organization or naming
+- Reimplementation of existing utilities/helpers
+- Documentation drift where changed code no longer matches docs
+- New patterns that conflict with established ones
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+### E. Simplicity + Completeness
+
+```typescript
+task({
+  subagent_type: "review",
+  description: "Simplicity + completeness review",
+  prompt: `Review this implementation for completeness and unnecessary complexity.
+
+Review packet:
+{REVIEW_PACKET}
+
+Run:
+  git diff {BASE_SHA}..{HEAD_SHA}
+
+Check for:
+- Missing requirements or acceptance criteria
+- Dead code, TODOs, unreachable branches
+- Complexity that can be deleted without losing behavior
+- Behavior changes that appear unintentional
+
+Return:
+- CRITICAL / IMPORTANT / MINOR findings
+- file:line references`,
+});
+```
+
+## Dispatch Matrix
+
+| Depth        | Reviewers to Run             |
+| ------------ | ---------------------------- |
+| **targeted** | Choose the 1-2 most relevant |
+| **standard** | A + C + E                    |
+| **full**     | A + B + C + D + E            |
+
+## Step 3: Synthesize Findings
+
+### Synthesis Checklist
+
+- [ ] Merge duplicate findings across reviewers
+- [ ] Keep the strongest explanation when multiple reviewers report same issue
+- [ ] Separate real blockers from optional improvements
+- [ ] Mark disputed / uncertain findings explicitly
+
+Output format:
+
+```markdown
+## Review Summary
+
+**Review depth:** [targeted | standard | full]
+**Agents run:** [N]
+**Critical:** [N]
+**Important:** [N]
+**Minor:** [N]
+
+### Critical Issues
+
+- `path/to/file.ts:123` — [issue + why it breaks]
+
+### Important Issues
+
+- `path/to/file.ts:123` — [issue]
+
+### Minor Issues
+
+- `path/to/file.ts:123` — [optional improvement]
+
+### Disputed / Needs Verification
+
+- [finding that may be wrong, plus what evidence would confirm it]
+
+### Assessment
+
+- [ ] Ready to proceed
+- [ ] Fix required first
+```
+
+## Step 4: Act on Findings
+
+### Remediation Checklist
+
+- [ ] Fix all Critical findings before proceeding
+- [ ] Fix Important findings in the current branch unless consciously deferred
+- [ ] Record deferred Minor findings somewhere durable
+- [ ] Push back on wrong findings with code/tests, not opinion
+
+| Severity      | Action                                        |
+| ------------- | --------------------------------------------- |
+| **Critical**  | Fix immediately before any further work       |
+| **Important** | Fix now or explicitly defer with reason       |
+| **Minor**     | Track for later if not worth immediate change |
+
+If a finding looks wrong, verify it against the codebase before changing anything.
+
+## Step 5: Re-verify
+
+After fixing review findings, re-run the relevant verification commands.
+
+At minimum, use the commands appropriate for the project toolchain:
+
+- `npm run typecheck`
+- `npm run lint`
+- `npm test`
+- `npm run build` (if release/build-sensitive)
+
+Do not claim review is resolved until fresh verification passes.
+
+## Placeholders Reference
+
+| Placeholder       | What to fill                     |
+| ----------------- | -------------------------------- |
+| `{REVIEW_PACKET}` | Tight review packet with context |
+| `{BASE_SHA}`      | Starting commit SHA              |
+| `{HEAD_SHA}`      | Ending commit SHA                |
+
+## Integration with Workflows
+
+| Command | When review runs                     |
+| ------- | ------------------------------------ |
+| `/ship` | After work is complete and verified  |
+| `/pr`   | Before pushing or opening PR         |
+| `/lfg`  | Between execution and compound steps |
+
+## Common Mistakes
+
+- Running 5 reviewers on a tiny one-file fix with no real risk
+- Sending vague prompts with no requirements or verification status
+- Treating reviewer output as automatically correct
+- Failing to deduplicate repeated findings
+- Skipping re-verification after review fixes
+
+## After Review: Compound
+
+Run `/compound` after resolving review findings to capture:
+
+- Patterns review caught that should be prevented earlier
+- False positives that should not be repeated
+- Newly discovered codebase conventions
+
+That turns review from a gate into a feedback loop.