opencode-overclock 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # opencode-overclock
 
-Power-ups for [opencode](https://opencode.ai): background tasks, cron-style scheduling,
-sandboxed bash, quality-gate hooks, cost telemetry, checkpoints — and an ASCII pet.
+The modular workflow suite and power-ups for [opencode](https://opencode.ai): background
+tasks, cron-style scheduling, quality-gate hooks, cost telemetry — and an ASCII companion.
 
 Everything is a separate module you can turn off individually, so you can take one feature and
 ignore the rest. When opencode ships a native equivalent, the matching module goes away.
@@ -13,18 +13,20 @@ 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.                           | —                                                          |
-| `usage`       | Per-day and per-session cost and token totals, collected from the event bus.                                                                          | `usage_report`                                             |
-| `checkpoints` | Rewind a session to any earlier message, files included, on top of opencode's own snapshots. Reverting asks for permission first.                     | `checkpoint_list` `checkpoint_revert` `checkpoint_restore` |
-| `sandbox`     | Wrap every bash call in bwrap: read-only `/`, writable project and `/tmp`, network off by default. Off unless you enable it.                          | `bash_unsandboxed` (escape hatch)                          |
-| `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`), 9 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` and `/oc-buddy`.
+needs you, plus `/oc-tasks`, `/oc-usage`, `/oc-schedules`, `/oc-buddy` (pet), `/oc-buddy-switch` (choose species), and `/oc-buddy-cycle` (next species).
 
 **Please read this before installing:** overclock gives the agent the ability to run shell
 commands in the background (`task_run`) and to schedule recurring prompts (`schedule_create`).
@@ -54,142 +56,283 @@ a plugin's `dispose` hook, without which this plugin's timers and watchers are n
 
 ## Configuration
 
-Everything is optional. With no config file you get every module except `sandbox`, and `guard`
-sits inert until you give it hooks — so the one thing worth configuring on day one is a quality
-gate. A reasonable `.opencode/overclock.json` to start from:
+Everything is optional. With no options configured, overclock runs with sensible defaults: background
+tasks, cron-style scheduling, quality gates, usage telemetry, and the buddy are active immediately.
 
-```json
+Configure options directly in your project or global `opencode.json`:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "tasks": { "killOnExit": true },
+        "guard": { "auto": true },
+      },
+    ],
+  ],
+}
+```
+
+To turn an individual feature off:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "buddy": false,
+      },
+    ],
+  ],
+}
+```
+
+| 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. Sandboxed Worker Subagents (The "Who")
+
+Specialized leaf subagents invoked via the `task` tool with **enforced read-only tool sandboxing** (`tools: { write: false, edit: false }`, `permission: { edit: "deny" }`):
+
+- `codebase-researcher`: Scout tracing call graphs, seams, and dependencies without cluttering orchestrator context.
+- `design-explorer`: Architect formulating contrasting minimalist vs extensible interface proposals ("Design It Twice").
+- `doubt-reviewer`: Adversarial verifier probing race conditions, error bounds, and silent assumptions.
+- `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.
+- `engineering-coach`: Elite staff mentor providing Socratic debugging guidance and architectural critique.
+
+### Quality gates (`guard`)
+
+Quality gates let you define automated feedback loops. Whenever the agent modifies code with `edit`
+or `write`, the guard runs your project's verification command in the background. If the command fails,
+the error output is automatically fed back into the session once the agent finishes its turn, prompting
+it to self-correct.
+
+Because verification commands vary by language and repository, configure hooks in your project's
+local `opencode.json`:
+
+#### Stack recipes
+
+##### TypeScript / JavaScript
+
+```jsonc
 {
-  "features": {
-    "guard": {
-      "hooks": [
-        {
-          "name": "typecheck",
-          "tools": ["edit", "write"],
-          "run": "npm run typecheck",
-          "pathFilter": "src/**/*.ts"
-        }
-      ]
-    },
-    "tasks": { "killOnExit": true }
-  }
+  "guard": {
+    "hooks": [
+      {
+        "name": "typecheck",
+        "tools": ["edit", "write"],
+        "pathFilter": "src/**/*.ts",
+        "run": "npm run typecheck",
+      },
+    ],
+  },
 }
 ```
 
-That gives you a typecheck after every edit (reported back to the agent when the session goes
-idle), background tasks that don't outlive the session, plus scheduling, telemetry, checkpoints
-and the buddy on their defaults. Swap `run` for whatever your project uses.
+##### Python (Ruff / Pytest)
 
-Each entry is `true`, `false`, or an object of options (which also means "on"). To turn
-something off:
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "lint",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.py",
+        "run": "ruff check .",
+      },
+    ],
+  },
+}
+```
 
-```json
-{ "features": { "buddy": false } }
+##### Rust (Cargo)
+
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "cargo-check",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.rs",
+        "run": "cargo check",
+      },
+    ],
+  },
+}
 ```
 
-| Module                          | Options                                                                                         |
-| ------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `tasks`                         | `killOnExit` bool · `stallDetection` bool · `stallThresholdMs` num · `stallCheckIntervalMs` num |
-| `sched`                         | `skipIfBusy` bool                                                                               |
-| `sandbox`                       | `net` bool                                                                                      |
-| `guard`                         | `hooks` array                                                                                   |
-| `usage`, `checkpoints`, `buddy` | —                                                                                               |
+##### Go
 
-Typos are reported at startup with a "did you mean", because a misspelled key like
-`killOnExist` would otherwise read as "not set" and quietly run the default. A bad config never
-takes the plugin down; the affected setting falls back to its default.
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "go-test",
+        "tools": ["edit", "write"],
+        "pathFilter": "**/*.go",
+        "run": "go test ./...",
+      },
+    ],
+  },
+}
+```
 
-### Quality gate options (`guard`)
+##### Generic / Make
 
-Each hook runs a command after the agent uses one of the tools it watches, and reports failures
-back to the agent. `name`, `tools` and `run` are required. Also available: `pathFilter` (glob), `mode` (`inject`,
-the default, waits for the session to be idle before reporting; `append` reports immediately),
-`debounceMs` (2000), `timeoutMs` (60000), `onSuccess` (`silent` or `notify`), and `maxDeferMs`
-(300000, how long `inject` waits for an idle session before reporting anyway).
+```jsonc
+{
+  "guard": {
+    "hooks": [
+      {
+        "name": "check",
+        "tools": ["edit", "write"],
+        "run": "make check",
+      },
+    ],
+  },
+}
+```
+
+#### Hook options
 
-### Restricting tool names
+| Field        | Default     | Description                                                                   |
+| ------------ | ----------- | ----------------------------------------------------------------------------- |
+| `name`       | _required_  | Identifier displayed in failure reports                                       |
+| `tools`      | _required_  | Tools to trigger on, e.g. `["edit", "write"]`                                 |
+| `run`        | _required_  | Shell command to execute (receives `$GUARD_TOOL` and `$GUARD_FILE` in env)    |
+| `pathFilter` | `undefined` | Optional glob pattern to limit triggers to relevant files (e.g. `**/*.py`)    |
+| `mode`       | `"inject"`  | `"inject"` waits for the session to go idle; `"append"` reports immediately   |
+| `debounceMs` | `2000`      | Debounce duration for rapid successive edits                                  |
+| `timeoutMs`  | `60000`     | Execution timeout before killing the command                                  |
+| `maxDeferMs` | `300000`    | Maximum time `"inject"` will wait for an idle session before reporting anyway |
+| `onSuccess`  | `"silent"`  | `"silent"` or `"notify"`                                                      |
+
+### Restricting and remapping tool names
 
 If your setup only accepts certain tool names, list them in `toolAllowlist`. Any tool whose
-name isn't permitted is withheld from the model rather than offered and refused, since a single
-unrecognised name can fail an entire request.
+name isn't permitted is withheld from the model rather than offered and refused:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolAllowlist": ["task_run", "task_status", "schedule_create"],
+      },
+    ],
+  ],
+}
+```
+
+`toolNames` maps this plugin's tools onto custom names you want the model to see:
 
-```json
+```jsonc
 {
-  "toolAllowlist": ["TaskCreate", "TaskList", "TaskOutput", "TaskStop", "MyExtraTool"],
-  "toolNames": { "task_run": "TaskCreate", "task_status": "TaskList" }
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "toolNames": { "task_run": "run_background_task" },
+      },
+    ],
+  ],
 }
 ```
 
-`toolNames` maps this plugin's tools onto names you allow. Keys are declared names (the table
-under [What you get](#what-you-get)); values are what the model sees.
-
-Startup tells you exactly where you stand: what was renamed, what was withheld and which of
-your allowed names are still free to use for it, and any name that collides with an opencode
-built-in (`bash`, `task`, …) or differs from one only by capitalisation — the first replaces
-that built-in, the second reads as a duplicate to anything matching case-insensitively.
-Descriptions mentioning a renamed tool are rewritten too, so the agent never gets instructions
-naming a tool it wasn't given. Permission ids keep their declared names, so existing permission
-config still applies.
-
-#### Named lists
-
-`toolAllowlist` entries can also name a bundled list, which expands to every name it permits.
-Mix and match freely — `["claude-code", "MyExtraTool"]` is a bundled list plus one of your own.
-
-`claude-code` is the tool set Claude Code registers. opencode's ids are snake_case and Claude
-Code's are PascalCase, so the two vocabularies don't overlap and these names are free to use.
-A bundled list also supplies default names for tools where it contains the same operation:
-
-| Module  | Declared          | Sent as      |
-| ------- | ----------------- | ------------ |
-| `tasks` | `task_run`        | `TaskCreate` |
-| `tasks` | `task_status`     | `TaskList`   |
-| `tasks` | `task_output`     | `TaskOutput` |
-| `tasks` | `task_kill`       | `TaskStop`   |
-| `sched` | `schedule_create` | `CronCreate` |
-| `sched` | `schedule_list`   | `CronList`   |
-| `sched` | `schedule_delete` | `CronDelete` |
-
-That's the whole table, and it stops there on purpose. Nothing in the `claude-code` set means
-"revert a session checkpoint" or "report token spend", so `checkpoints`, `usage` and
-`bash_unsandboxed` get no default name: handing them an unrelated one would tell the model the
-wrong thing about what they do. They're withheld until you choose a name yourself, and startup
-says which names are free:
-
-```json
+### Running OpenCode V2 plugins on OpenCode V1
+
+OpenCode V1 distributions cannot natively load V2 plugins (which export `{ id, setup }` or `{ id, effect }` instead of a server function). Overclock provides an embedded V2 host engine that runs V2 plugins side-by-side with V1 tools:
+
+```jsonc
 {
-  "toolAllowlist": "claude-code",
-  "toolNames": { "usage_report": "StructuredOutput" }
+  "plugin": [
+    [
+      "opencode-overclock",
+      {
+        "plugins": ["./plugins/custom-agent.ts", ["opencode-plugin-review", { "strict": true }]],
+      },
+    ],
+  ],
 }
 ```
 
-`toolNames` overrides any row above too, if a different name reads better for you. The table is
-checked against the source by a test, so the two can't drift apart.
+Overclock synthesizes a spec-compliant `PluginContext`, adapting V2 domain transforms (`agent`, `command`, `catalog`, `reference`, `skill`, `aisdk`) to live V1 config and chat hooks while keeping all V1 power tools active.
+
+Startup tells you what was renamed, what was withheld, and warns on collisions with opencode
+built-in tools. Descriptions mentioning a renamed tool are rewritten automatically.
 
 ## Notes on the TUI surface
 
 The TUI plugin sends a desktop notification (with sound) when a turn completes or the agent
 needs permission, asks a question, or errors — each individually switchable through plugin
-options. Its slash commands read the state files under `.opencode/overclock/`, so they work
+options (`notifyIdle`, `notifyPermission`, `notifyQuestion`, `notifyError`, `buddy` in `tui.json`).
+Its slash commands read the state files under `.opencode/overclock/`, so they work
 without going through the model.
 
 The buddy hatches once per install with a random species, rarity and name, persists in the
 TUI's key-value store, hides itself below 100 columns, and needs `@opentui/solid` resolvable at
 runtime. If it isn't, the buddy quietly sits out and the rest of the TUI plugin still loads.
+Switch buddy on demand via `/oc-buddy-switch` (opens an interactive species picker or rolls a fresh companion)
+or `/oc-buddy-cycle` (advances directly to the next species in rotation).
 
 ## Contributing
 
 ```
 src/
-  index.ts          entry: load config, init modules, merge hooks
+  index.ts          entry: init enabled modules, merge hooks, hybrid V1/V2 export
   tui.ts            TUI plugin (notifications + slash commands), separate export
-  types.ts          FeatureModule contract
-  config.ts         config loader
-  merge.ts          hook composition (many modules, same hook -> sequential)
-  tools.ts          gateway tool policy: alias presets, allowlists, rename/withhold
-  validate.ts       overclock.json checks + startup summary
-  lib/              state dir + json, session inject + toast
-  features/         one file per module + registry
+  core/             types, lifecycle/hook merging, tool policy, capability summary, bridge
+  platform/         host adapters: process (exec/tmux), session (busy/inject/notify), storage (state/store), probe
+  buddy/            ASCII companion state, sprites, and TUI slot integration
+  v2/               embedded V2 plugin host, synthetic context, and dynamic loader
+  features/         feature modules (tasks, sched, guard, recovery, truncator, usage, buddy)
 test/               bun test
 ```
 
@@ -197,8 +340,6 @@ Adding a feature:
 
 1. Write `src/features/<name>.ts` exporting a `FeatureModule`.
 2. Register it in `src/features/index.ts`.
-3. If it adds tools, add each one to the `claude-code` table in `src/tools.ts`. A test fails
-   otherwise, since an unmapped tool is invisible behind a whitelisting gateway.
 
 Background reading:
 [docs/opencode-plugin-surface.md](docs/opencode-plugin-surface.md) maps opencode's
@@ -243,7 +384,7 @@ somewhere else.
 ### Headless end-to-end
 
 ```sh
-timeout 90 opencode run -m anthropic/claude-sonnet-5 "Use task_run to run 'echo hi' ..." < /dev/null
+timeout 90 opencode run -m <provider>/<model> "Use task_run to run 'echo hi' ..." < /dev/null
 ```
 
 - `< /dev/null` is required; an open stdin hangs.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-overclock",
-  "version": "0.3.0",
-  "description": "Power-ups for opencode: background tasks, scheduling, sandboxed bash, tool hooks, usage telemetry, checkpoints. Modular, toggleable.",
+  "version": "0.5.0",
+  "description": "Power-ups for opencode: background tasks, cron scheduling, quality-gate hooks, usage telemetry, and companion. Modular, toggleable.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -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.