opencode-overclock 0.4.0 → 0.5.1

package/README.md

@@ -13,15 +13,17 @@ opencode plugin -g opencode-overclock    # every project
 
 ## What you get
 
-| Module      | What it does                                                                                                                                                  | Tools it adds                                       |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.         | `task_run` `task_status` `task_output` `task_kill`  |
-| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                           | `schedule_create` `schedule_list` `schedule_delete` |
-| `guard`     | Your own quality gates: run a command after the agent edits files, and feed failures back to it once the session goes idle. Built-in recipes & edit recovery. | —                                                   |
-| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                 | —                                                   |
-| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.    | —                                                   |
-| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                 | —                                                   |
-| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                    | —                                                   |
+| Module      | What it does                                                                                                                                                                                   | Tools it adds                                       |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `workflow`  | 5 lifecycle commands (`/define`, `/plan`, `/build`, `/diagnose`, `/ship`), 11 agents (interactive & sandboxed subagents), and 9 bundled engineering skills (`tdd`, `grilling`, `doubt`, etc.). | —                                                   |
+| `safety`    | Blocks destructive git operations (`git reset --hard`, force-push, `clean -f`, `branch -D`, `stash drop`) in `bash` tool calls before they run.                                                | —                                                   |
+| `tasks`     | Run shell commands in the background. The agent gets the result posted back into the session when they finish, and a nudge if one blocks on a prompt.                                          | `task_run` `task_status` `task_output` `task_kill`  |
+| `sched`     | Recurring prompts on a cron expression or an interval (`"5m"`). Survives restarts; an interval on the current session makes a loop.                                                            | `schedule_create` `schedule_list` `schedule_delete` |
+| `guard`     | Your own quality gates: run a command after the agent edits files, feed failures back on idle, edit recovery hints, and `floorGuard` anti-bypass protection.                                   | —                                                   |
+| `recovery`  | Automatically heal provider errors (missing tool results, thinking block sequencing, context limit) and auto-resume sessions.                                                                  | —                                                   |
+| `truncator` | Context-protecting smart output truncation for high-volume tools (`task_output`, `bash`, `grep`, `glob`, `webfetch`) preserving header & tail diagnostics.                                     | —                                                   |
+| `usage`     | Per-day and per-session cost and token totals, collected from the event bus (accessible via TUI `/oc-usage`).                                                                                  | —                                                   |
+| `buddy`     | An ASCII pet next to the prompt that reacts to what the session is doing. Purely cosmetic.                                                                                                     | —                                                   |
 
 On top of the tools, the TUI side adds desktop notifications when a turn finishes or the agent
 needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules`, `/oc-buddy` (pet), `/oc-buddy-switch` (choose species), and `/oc-buddy-cycle` (next species).
@@ -88,14 +90,67 @@ To turn an individual feature off:
 }
 ```
 
-| Module           | Options                                                                                                          |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `tasks`          | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num · `tmux` bool    |
-| `sched`          | `skipIfBusy` bool                                                                                                |
-| `guard`          | `hooks` array · `recipes` array (`["tsc", "eslint", "cargo", "ruff", "go"]`) · `auto` bool · `editRecovery` bool |
-| `recovery`       | `maxAttempts` num · `cooldownMs` num · `autoResume` bool                                                         |
-| `truncator`      | `maxChars` num · `tools` array · `headLines` num · `tailLines` num                                               |
-| `usage`, `buddy` | —                                                                                                                |
+| Module           | Options                                                                                                                                    |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `workflow`       | `enabled` bool · `commands` bool · `subagents` bool · `skillsPath` string                                                                  |
+| `safety`         | `blockDestructiveGit` bool · `allowForcePush` bool · `allowStashDrop` bool · `customPatterns` array                                        |
+| `guard`          | `hooks` array · `recipes` array (`["tsc", "eslint", "cargo", "ruff", "go"]`) · `auto` bool · `editRecovery` bool · `floorGuard` bool / obj |
+| `tasks`          | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num · `tmux` bool                              |
+| `sched`          | `skipIfBusy` bool                                                                                                                          |
+| `recovery`       | `maxAttempts` num · `cooldownMs` num · `autoResume` bool                                                                                   |
+| `truncator`      | `maxChars` num · `tools` array · `headLines` num · `tailLines` num                                                                         |
+| `usage`, `buddy` | —                                                                                                                                          |
+
+### Engineering harness & workflows (`workflow`)
+
+Overclock bundles a structured software engineering harness that elevates opencode from a code generator into an elite engineering partner.
+
+#### 1. Lifecycle Commands (The "When")
+
+| Command     | Purpose                                                                                                                            |
+| :---------- | :--------------------------------------------------------------------------------------------------------------------------------- |
+| `/define`   | Structured inquiry via `grilling` and `domain-modeling`, or direct specification synthesis (`to-spec`) into `SPEC.md`.             |
+| `/plan`     | Decomposes `SPEC.md` into vertical tracer bullets (`to-tickets`) with dependency DAGs and expand/contract migration branches.      |
+| `/build`    | Autonomous TDD implementation (`tdd`) with stop-the-line tripwires (halts on 3 consecutive test failures or schema changes).       |
+| `/diagnose` | Disciplined 6-phase defect isolation loop with automated reproductions, tagged logging (`[DEBUG-xxxx]`), and regression tests.     |
+| `/ship`     | Pre-launch gatekeeper running a parallel 4-way subagent audit across uncommitted, staged, and branch diffs with GO/NO-GO verdicts. |
+
+#### 2. Bundled Engineering Skills (The "How")
+
+Auto-discovered by opencode's `skill` tool when relevant:
+
+- `tdd`: Test-driven development loop enforcing public seam tests before implementation and the Prove-It bug pattern.
+- `grilling`: Requirements interrogation on the decision dependency frontier with opinionated defaults (`➡️ **Recommended:**`).
+- `domain-modeling`: Ubiquitous language management (`CONTEXT.md`) and Architecture Decision Records (`ADR-FORMAT.md`).
+- `to-spec`: Fast requirements synthesis into `SPEC.md` without reopening interview loops.
+- `to-tickets`: Context-sized DAG task planning with expand-and-contract branches for wide refactors.
+- `codebase-design`: Deep module architecture (Ousterhout), 4 dependency categories, and "Design It Twice" exploration.
+- `diagnosing-bugs`: Systematic defect reproduction, ranked hypotheses, secret redaction, and tagged probes.
+- `doubt`: Adversarial verification where artifacts are audited against contracts without author confirmation bias.
+- `source-discipline`: Grounding framework code in official, version-matched documentation.
+
+#### 3. Workflow Agents (The "Who")
+
+Specialized agents available interactively in the TUI (`Tab`) and delegable via the `task` tool:
+
+##### Interactive & Subagent Agents (`mode: "all"`)
+
+- `craftsman`: Disciplined implementation agent enforcing TDD (public seam first), minimal vertical slices, and zero compromises on code quality.
+- `doc-writer`: Technical writer synthesizing accurate documentation, API references, ADRs, and user guides grounded directly in codebase evidence.
+- `engineering-coach`: Elite staff mentor providing Socratic debugging guidance, mental models, and architectural critique (read-only sandboxed).
+- `design-explorer`: Architect formulating contrasting minimalist vs extensible interface proposals ("Design It Twice", read-only sandboxed).
+- `codebase-researcher`: Scout tracing call graphs, seams, and dependencies without cluttering context (read-only sandboxed).
+- `doubt-reviewer`: Adversarial verifier probing race conditions, error bounds, and silent assumptions (read-only sandboxed).
+
+##### Sandboxed Audit Subagents (`mode: "subagent"`)
+
+Leaf subagents invoked via the `task` tool with **enforced read-only tool sandboxing** (`tools: { write: false, edit: false }`, `permission: { edit: "deny" }`):
+
+- `standards-reviewer`: Senior reviewer auditing code diffs against Martin Fowler's code smells and repo idioms.
+- `spec-reviewer`: Product reviewer ensuring strict compliance with `SPEC.md` and zero unrequested scope creep.
+- `security-auditor`: Adversarial security engineer auditing diffs for OWASP Top 10 flaws and secret hygiene.
+- `test-engineer`: QA engineer assessing test coverage gaps, assertion quality, and mocking boundaries.
+- `performance-auditor`: Performance engineer identifying N+1 queries, unbounded memory, and latency bottlenecks.
 
 ### Quality gates (`guard`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-overclock",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Power-ups for opencode: background tasks, cron scheduling, quality-gate hooks, usage telemetry, and companion. Modular, toggleable.",
   "type": "module",
   "repository": {
@@ -16,7 +16,8 @@
     "./tui": "./src/tui.ts"
   },
   "files": [
-    "src"
+    "src",
+    "skills"
   ],
   "keywords": [
     "opencode",
@@ -39,7 +40,8 @@
   },
   "dependencies": {
     "@opencode-ai/plugin": "1.18.9",
-    "croner": "^10.0.1"
+    "croner": "^10.0.1",
+    "yaml": "^2.7.0"
   },
   "peerDependencies": {
     "@opentui/solid": ">=0.4.5"

package/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,35 @@
+# Deepening: Dependency Categories and Seam Discipline
+
+How to deepen a cluster of shallow modules into high-leverage architectural components.
+
+## Dependency Categories
+
+When assessing a module or candidate for deepening, classify its dependencies. The category dictates how the module is structured and tested across its seams:
+
+### 1. In-Process (Pure Computation)
+
+- **Characteristics:** In-memory state, algorithms, data transformations, zero network/disk I/O.
+- **Deepening Strategy:** Merge shallow helpers and test directly through the deep module interface. No adapters, mocks, or ports needed.
+
+### 2. Local-Substitutable
+
+- **Characteristics:** Infrastructure dependencies with reliable in-memory or embedded substitutes (e.g. SQLite in `:memory:`, PGLite, in-memory filesystem, mock clock).
+- **Deepening Strategy:** Deepen the module and run tests directly against the local substitute. The seam remains internal to the module; callers never configure or pass database handles.
+
+### 3. Remote but Owned (Ports & Adapters)
+
+- **Characteristics:** Internal microservices, background job queues, or intra-company APIs deployed across network boundaries.
+- **Deepening Strategy:** Define a clean **port** (interface) at the seam. The deep module owns domain orchestration; the transport is injected via an **adapter**. Tests supply a fast in-memory adapter; production supplies an HTTP/gRPC/queue adapter.
+
+### 4. True External (Third-Party Services)
+
+- **Characteristics:** External vendors (Stripe, Twilio, SendGrid, AWS S3) outside your control.
+- **Deepening Strategy:** The module defines a narrow domain port. Test suites supply a mock/stub adapter verifying request shapes; production supplies the vendor client adapter.
+
+---
+
+## Seam Discipline
+
+- **The Two-Adapter Rule:** One adapter means a hypothetical seam; two adapters means a real one. Do NOT introduce an interface or port unless at least two implementations are justified (typically production + in-memory test). A single-implementation interface is unnecessary indirection.
+- **Internal vs External Seams:** A deep module may have internal seams (private helpers, internal storage engines) for its own tests. Do not leak internal seams to external callers.
+- **The Interface is the Test Surface:** Write unit tests against the deep module interface, not against internal private functions. Tests survive internal refactoring when they test behavior, not implementation mechanics.

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

@@ -0,0 +1,34 @@
+# Design It Twice
+
+When architecting a critical module, interface, or subsystem boundary, your first idea is almost never your best idea. First ideas are typically shallow adaptations of existing local constraints.
+
+## The Exploration Protocol
+
+### 1. Frame the Problem Space
+
+Before generating interfaces, explicitly articulate:
+
+- The caller goals and constraints the interface must satisfy.
+- The dependency category (In-Process, Local-Substitutable, Remote-Owned, or True External) per [DEEPENING.md](DEEPENING.md).
+- A concrete usage scenario with realistic inputs and outputs.
+
+### 2. Formulate Radically Differently Constrained Interfaces
+
+Generate at least 2 (preferably 3) contrasting architectural designs:
+
+- **Option A (Minimalist / High-Leverage):** Absolute minimum public surface (1-3 intuitive functions). Maximum internal power hidden behind simple calls. Optimizes for caller ergonomics.
+- **Option B (Extensible / Composable):** Explicit ports and adapters, pluggable pipeline or middleware, highly configurable. Optimizes for future variance and third-party extensions.
+- **Option C (Default-Optimized):** The common 90% use case requires zero configuration, while advanced capabilities are exposed through optional progressive disclosure.
+
+### 3. Compare Across Concrete Criteria
+
+Evaluate the designs against:
+
+1. **Depth (Leverage):** Ratio of internal power provided to interface complexity imposed on callers.
+2. **Call-Site Simplicity:** How clean and readable is the calling code?
+3. **Information Hiding:** Does the interface leak internal details, vendor types, or database identifiers?
+4. **Blast Radius of Change:** If the internal implementation changes tomorrow, do callers need to change?
+
+### 4. Provide an Opinionated Recommendation
+
+Do not present a bland menu of options without guidance. Recommend the best approach (or a synthesized hybrid), clearly stating the trade-offs and rationale.

package/skills/codebase-design/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: codebase-design
+description: Principles for deep module architecture and high-leverage interface design. Use when creating new services or modules, untangling tightly coupled subsystems, designing APIs, or refactoring architecture.
+pack: core
+license: MIT
+attribution: Adapted from mattpocock/skills (MIT License)
+references:
+  - DEEPENING.md
+  - DESIGN-IT-TWICE.md
+---
+
+# Codebase Design: Deep Modules & High-Leverage Architecture
+
+Rooted in John Ousterhout's _A Philosophy of Software Design_ and domain-driven architectural patterns, this skill guides the creation of deep, high-leverage modules that make codebases simpler to understand, maintain, and evolve.
+
+## When to Use
+
+- Designing a new service, package, module, or domain boundary.
+- Decomposing a tangled god-object or sprawling utility library into cohesive components.
+- Designing API contracts or SDK entry points for internal or external callers.
+- Assessing architectural coupling and seam placement.
+
+## When NOT to Use
+
+- Routine bug fixes or isolated one-line edits.
+- Editing declarative configuration files.
+- Mechanical script maintenance.
+
+---
+
+## Core Architectural Principles
+
+### 1. Deep Modules (Depth Over Shallowness)
+
+- **Shallow Module (Anti-pattern):** A module whose public interface is complicated relative to the small amount of capability it provides. (e.g. A 40-line wrapper around `fetch` that requires callers to pass 6 configuration objects).
+- **Deep Module (Ideal):** A module that provides a simple, intuitive interface while concealing substantial complexity and power behind it. (e.g. Unix file I/O: `open`, `read`, `write`, `close` concealing disk block caching, buffer pools, and kernel drivers).
+- **Measure of Architectural Leverage:**
+  $$\text{Leverage} = \frac{\text{Internal Functionality Provided}}{\text{Interface Complexity Imposed on Callers}}$$
+
+### 2. Information Hiding vs Information Leakage
+
+- **Information Hiding:** Knowledge of private algorithms, data representations, and third-party dependencies is strictly contained within the module.
+- **Information Leakage:** Occurs when an internal change to a module forces ripple edits across caller code (e.g. exposing internal database IDs, ORM models, or vendor SDK types directly to consumers).
+- **Hyrum's Law:** _"With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody."_ Keep public surfaces strictly bounded.
+
+### 3. The Full Caller Contract
+
+An interface is not just a function signature or type signature. The full contract comprises:
+
+- **Ordering:** Must `init()` be called before `run()`?
+- **Error Modes:** How are failures surfaced (exceptions, result tuples, status codes)?
+- **Invariants:** What assumptions must callers hold true?
+- **Configuration & Defaults:** Are sane defaults supplied so simple callers do not configure knobs?
+- **Performance & Resource Cleanup:** Must callers explicitly close or release handles?
+
+### 4. Dependency Classification & Seams
+
+Classify dependencies before introducing interfaces:
+
+- See [DEEPENING.md](DEEPENING.md) for the 4 categories: In-Process, Local-Substitutable, Remote-Owned (Ports & Adapters), and True External.
+- Observe the **Two-Adapter Rule**: Never create an interface or port unless at least two real adapters exist (typically production + in-memory test).
+
+### 5. Design It Twice
+
+When designing a critical subsystem or boundary:
+
+- Never settle on the first design that comes to mind.
+- Explore at least 2 contrasting architectural designs (e.g. Minimalist vs Extensible).
+- See [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md) for the structured comparison protocol.
+
+### 6. Chesterton's Fence in Refactoring
+
+Before modifying or deleting code that appears redundant, verbose, or unusual, you MUST discover and explain why it was originally written. If you cannot explain why it exists, you are not qualified to change it.
+
+---
+
+## Common Rationalizations
+
+| Rationalization                                                                   | Reality                                                                                                         |
+| :-------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
+| _"More small files and 5-line classes are always cleaner."_                       | Fragmenting logic creates shallow modules and cognitive indirection. Colocate cohesive logic into deep modules. |
+| _"Expose all knobs so callers have maximum flexibility."_                         | Forcing callers to configure dozens of low-level options leaks complexity. Provide high-leverage defaults.      |
+| _"I will create an interface just in case we need another implementation later."_ | Speculative interfaces add indirection without value. Introduce ports when you have two concrete adapters.      |
+
+---
+
+## Verification
+
+Architectural design is complete when:
+
+1. Callers can achieve primary use cases using 1-2 intuitive entry points.
+2. Internal changes to storage, third-party libraries, or algorithms cause zero ripple effects on callers.
+3. Automated tests exercise the public interface rather than private internal implementation details.

package/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: diagnosing-bugs
+description: Disciplined root-cause investigation loop for bugs, flakes, and performance regressions. Use when investigating unexpected behavior, diagnosing error traces, resolving flaky tests, or fixing performance bottlenecks.
+pack: core
+license: MIT
+attribution: Adapted from mattpocock/skills (MIT License)
+---
+
+# Diagnosing Bugs: Disciplined Root-Cause Investigation
+
+A systematic discipline for isolating, reproducing, and fixing elusive software defects. Skip phases only when explicitly justified.
+
+## Fast Explanation vs Full Investigation
+
+- **Explanation Request:** If the user asks for a conceptual explanation of an error message ("what does this error mean?"), provide a direct explanation without launching a full diagnostic loop.
+- **Defect Investigation:** When investigating an actual broken feature, unexpected output, crash, or performance regression, execute the structured loop below.
+
+---
+
+## 0. Redaction First
+
+Before displaying commands, outputs, or captured logs:
+
+- **Redact every credential or secret:** Replace tokens, API keys, passwords, and private identifiers with `<REDACTED>`.
+- Use environment variables so sensitive credentials never leak into logs or command strings.
+
+---
+
+## The 6-Phase Diagnostic Loop
+
+### Phase 1: Build a Tight Feedback Loop
+
+**This is the core of the skill.** If you have a fast, automated pass/fail signal that goes red on _this specific bug_, you will isolate the cause. If you do not have one, theorizing about code is speculation.
+
+#### Ways to Construct the Loop (in order of preference):
+
+1. **Failing Unit / Integration Test:** At the seam reaching the bug.
+2. **Automated HTTP / Script Invocation:** `curl` or script against a local server.
+3. **CLI Invocation with Snapshot Diff:** Diffing output against known-good state.
+4. **Headless Browser Test:** Playwright or Puppeteer script asserting on DOM or network.
+5. **Replayed Trace / Fixture:** Load a captured production payload or event in isolation.
+6. **Throwaway Minimal Harness:** Isolated script calling the subsystem directly.
+
+#### Non-Deterministic & Flaky Defects
+
+For intermittent bugs, the goal is to **raise the reproduction rate**:
+
+- Loop the trigger 50–100 times in a test harness.
+- Parallelize requests, add concurrent load, or inject micro-delays around timing windows.
+- A bug that reproduces 40% of the time under stress is debuggable; a 0.5% flake is not.
+
+#### Inaccessible Environments & Missing Access
+
+If a bug cannot be reproduced locally due to missing external credentials or environments:
+
+- **Do not guess blindly.** State what you tried and what is missing.
+- Ask the user for:
+  1. Access or temporary environment credentials, OR
+  2. A sanitized log dump, HAR recording, or telemetry trace, OR
+  3. Permission to add temporary diagnostic instrumentation to staging.
+
+**Completion Criterion:** You have an automated, red-capable command that you have executed and confirmed red on the reported defect.
+
+---
+
+### Phase 2: Reproduce & Minimise
+
+Confirm the failure matches the **user's actual symptom**, not an unrelated error nearby.
+
+#### Minimise the Scenario
+
+Once red, shrink the reproduction to the absolute smallest scenario that still fails:
+
+- Cut parameters, configurations, data fields, and unnecessary steps one at a time.
+- Re-run the loop after each reduction.
+- **Done when every remaining element is load-bearing:** removing any remaining line causes the loop to pass green.
+
+---
+
+### Phase 3: Formulate Ranked, Falsifiable Hypotheses
+
+Formulate 3 to 5 distinct, ranked hypotheses explaining the failure. Generating multiple hypotheses prevents cognitive anchoring on the first plausible idea.
+
+Every hypothesis must be **falsifiable**:
+
+> _"If [Cause X] is the root cause, then [Changing Y] will resolve the failure, and [Changing Z] will exacerbate it."_
+
+If a hypothesis cannot state a testable prediction, discard or sharpen it.
+
+---
+
+### Phase 4: Targeted Tagged Instrumentation
+
+Test predictions one variable at a time:
+
+- **Inspect with Debugger / REPL:** When available, inspecting state beats adding ten log statements.
+- **Unique Hex Tags:** Tag every temporary diagnostic log with a unique searchable prefix:
+  ```ts
+  console.log("[DEBUG-f7a2] Parsed payload headers:", headers)
+  ```
+  Unique tags guarantee that all temporary probes can be identified and removed with a single pass.
+- **Performance Regressions Branch:** Do not use `console.log` for performance bugs (logging distorts timings). Establish a stable baseline measurement (`performance.now()`, profiler, query plan), change one variable, and compare against the baseline.
+
+---
+
+### Phase 5: Fix & Regression Guard
+
+1. **Verify the Seam:** Write an automated regression test at the public seam **before** applying the fix.
+   - If the codebase architecture lacks a seam to test the defect cleanly, note this explicitly as an architectural gap.
+2. **Apply the Minimal Root-Cause Fix:** Never paper over symptoms, suppress errors, or catch-and-ignore. Fix the underlying invariant.
+3. **Assert Green:** Run the regression test and confirm it passes.
+4. **Re-run Full Scenario:** Re-run the Phase 1 loop against the original un-minimised scenario to ensure full resolution.
+
+---
+
+### Phase 6: Clean Up & Document
+
+Before concluding:
+
+- [ ] Remove all `[DEBUG-xxxx]` logging probes (`grep` for the tag).
+- [ ] Delete or clean up throwaway reproduction scripts.
+- [ ] Run full test suite and linters to verify zero side-effects.
+- [ ] Document the verified root cause in the commit message or PR summary so future maintainers learn from the defect.

package/skills/domain-modeling/ADR-FORMAT.md

@@ -0,0 +1,55 @@
+# Architecture Decision Record (ADR) Format
+
+An ADR captures a consequential architectural decision, its context, trade-offs, and alternatives considered.
+
+## When to Write an ADR: The 3-Criteria Filter
+
+An ADR MUST only be recorded if the decision meets ALL THREE criteria:
+
+1. **Hard to Reverse:** Changing it later would require significant refactoring, database migrations, or cross-system coordination.
+2. **Surprising Without Context:** A reasonable engineer might wonder why this path was chosen instead of a conventional alternative.
+3. **A Real Trade-off:** The choice involves clear disadvantages, constraints, or costs that were deliberately accepted in exchange for specific benefits.
+
+If a decision does not meet all three (e.g. choosing a standard linter or routine naming convention), do NOT write an ADR. Record it as a standard or invariant in the project spec instead.
+
+---
+
+## ADR Template
+
+\`\`\`markdown
+
+# ADR-[NUMBER]: [Short Title in Imperative Mood, e.g. Use PostgreSQL for Outbox Queue]
+
+- **Status:** [Proposed | Accepted | Superseded by ADR-xxx]
+- **Date:** [YYYY-MM-DD]
+- **Deciders:** [Names or Roles]
+
+## Context & Problem Statement
+
+What problem are we trying to solve? What forces and constraints exist (performance, delivery deadline, team expertise, infrastructure)?
+
+## Considered Options
+
+1. **Option A:** [Description]
+2. **Option B:** [Description]
+3. **Option C:** [Description]
+
+## Decision Outcome
+
+Chosen option: **Option [X]**, because [concise justification].
+
+### Positive Consequences
+
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative Consequences & Accepted Costs
+
+- [Accepted downside 1]
+- [Accepted downside 2]
+
+## Compliance & Invariants
+
+- [Invariant 1 that future maintainers must observe]
+- [Verification rule or automated test asserting this decision]
+  \`\`\`

package/skills/domain-modeling/CONTEXT-FORMAT.md

@@ -0,0 +1,32 @@
+# CONTEXT.md Format
+
+A project glossary establishing ubiquitous language for the bounded context.
+
+## Structure
+
+```markdown
+# {Context Name}
+
+{One or two sentence description of what this bounded context is and why it exists.}
+
+## Ubiquitous Language
+
+**Order**:
+A customer request to purchase goods, created at checkout and tracked through fulfillment.
+_Avoid_: Purchase, Transaction, Cart.
+
+**Invoice**:
+A formal request for payment issued to a customer with payment terms and due dates.
+_Avoid_: Bill, Receipt.
+
+**Customer**:
+A person or legal entity holding an active account that places orders.
+_Avoid_: User, Client, Buyer.
+```
+
+## Rules
+
+- **Be Opinionated:** When multiple words exist for the same concept, designate the canonical term and list confusing alternatives under `_Avoid_`.
+- **Keep Definitions Tight:** 1 to 2 sentences max. Define what the concept IS, not how it is implemented in code.
+- **Domain Concepts Only:** General programming concepts (buffers, queues, retries, JSON schemas) do NOT belong here unless they are domain entities within the system.
+- **No Implementation Artifacts:** Do not put task lists, scratchpads, or pseudo-code in `CONTEXT.md`.

package/skills/domain-modeling/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: domain-modeling
+description: Builds and sharpens a project's domain model and ubiquitous language. Use when establishing codebase terminology, writing or editing CONTEXT.md, defining entities, or recording Architecture Decision Records (ADRs).
+pack: core
+license: MIT
+attribution: Adapted from mattpocock/skills (MIT License)
+references:
+  - CONTEXT-FORMAT.md
+  - ADR-FORMAT.md
+---
+
+# Domain Modeling
+
+Actively build and sharpen the project's domain model as you design and implement. This is an active discipline: challenging ambiguous terms, discovering edge cases, and recording the glossary and decisions the moment they crystallize.
+
+## When to Use
+
+- Defining new entities, services, APIs, or data models.
+- Resolving ambiguous or conflicting terminology used by stakeholders or in code.
+- Capturing ubiquitous language in `CONTEXT.md` (or existing project glossary).
+- Making consequential, hard-to-reverse architectural decisions that warrant an ADR.
+
+## When NOT to Use
+
+- Routine bug fixes or mechanical refactoring where domain concepts do not change.
+- Storing task lists, implementation steps, or temporary notes (use specs and task plans instead).
+- General programming concepts (e.g. timeouts, HTTP helpers, logger wrappers).
+
+---
+
+## File Structure
+
+### Single Context (Standard)
+
+```
+/
+├── CONTEXT.md                    ← Ubiquitous language glossary
+├── docs/
+│   └── adr/
+│       ├── 0001-storage-engine.md
+│       └── 0002-auth-tokens.md
+└── src/
+```
+
+### Multi-Context Repositories
+
+If different subsystems have distinct ubiquitous languages (e.g. `billing` vs `fulfillment`), a `CONTEXT-MAP.md` at root maps each bounded context:
+
+```
+/
+├── CONTEXT-MAP.md                ← Maps bounded contexts and relationships
+├── docs/adr/                     ← System-wide ADRs
+└── src/
+    ├── ordering/
+    │   └── CONTEXT.md
+    └── billing/
+        └── CONTEXT.md
+```
+
+Create files lazily: only when the first term or ADR is resolved. Respect existing project document conventions if ADRs or glossaries are already placed elsewhere (e.g. `doc/adr/` or `wiki/`).
+
+---
+
+## The Active Modeling Protocol
+
+### 1. Challenge Against the Glossary
+
+When the user or code uses a term conflicting with existing language, call it out immediately:
+
+> _"The glossary defines 'Cancellation' as voiding an unfulfilled order, but you described 'Cancellation' of an already shipped package. Do you mean 'Return' or 'Recall'?"_
+
+### 2. Sharpen Fuzzy and Overloaded Terms
+
+When terms are overloaded or vague, propose a precise canonical term:
+
+> _"You mentioned 'User': in this context, do you mean 'Organization Admin', 'Member', or 'API Service Account'?"_
+
+### 3. Discuss Concrete Scenarios
+
+Probe domain relationships with concrete boundary scenarios:
+
+> _"What happens if an organization subscription expires while an asynchronous batch export is actively running?"_
+
+### 4. Cross-Reference with Code
+
+Compare user descriptions with the existing codebase:
+
+> _"The codebase requires a verified billing address before generating an invoice, but you stated invoices can be drafted without an address. Which is the intended invariant?"_
+
+### 5. Update CONTEXT.md Inline
+
+Update `CONTEXT.md` immediately when a term is settled. Do not batch glossary updates until the end of the session. Keep definitions tight (1-2 sentences defining what the entity IS, not how it is implemented). See [CONTEXT-FORMAT.md](CONTEXT-FORMAT.md).
+
+### 6. Offer ADRs Sparingly: The 3-Criteria Filter
+
+Only propose recording an ADR when ALL THREE criteria are satisfied:
+
+1. **Hard to Reverse:** Changing the decision later imposes high migration, refactoring, or coordination costs.
+2. **Surprising Without Context:** A reasonable future engineer might ask _"Why did they do it this way instead of the standard approach?"_
+3. **A Real Trade-off:** There were genuine alternative options, and one was chosen with deliberate acceptance of specific disadvantages.
+
+If any criterion is missing, do NOT create an ADR. Record it as an invariant or decision in the specification instead. See [ADR-FORMAT.md](ADR-FORMAT.md).