opencode-wait-a-minute 0.0.0-stage → 1.1.0-rc.8

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "opencode-wait-a-minute",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "WAM keeps more state than it sends: deterministic task-state, context reconstruction, and evidence-backed completion for OpenCode agents.",
+  "version": "1.1.0-rc.8",
+  "main": "index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "*.js",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.js",
+    "!**/*.test.mjs",
+    "!**/bench-*.mjs"
+  ],
+  "scripts": {
+    "gate": "node scripts/release-gate.mjs",
+    "rc1": "WAM_RC1_EVIDENCE=1 node scripts/release-gate.mjs",
+    "docs:check": "node scripts/docs-check.mjs",
+    "validate": "node scripts/release-gate.mjs",
+    "production:gate": "node scripts/release-gate.mjs",
+    "release:check": "node scripts/release-gate.mjs",
+    "bench:validation": "node benchmarks/run-validation.mjs",
+    "bench:audit": "node benchmarks/validation/audit-results.mjs --build",
+    "bench:validate": "node benchmarks/validation/audit-results.mjs",
+    "benchmark": "node benchmarks/run.mjs",
+    "benchmark:real": "node benchmarks/run-real.mjs",
+    "benchmark:suite": "node benchmarks/cli.mjs",
+    "report:rc1": "node benchmarks/reports/generate-rc1.mjs",
+    "pack:test": "node scripts/verify-package.mjs",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify:version": "node scripts/verify-version-parity.mjs",
+    "verify:security": "node scripts/verify-security.mjs",
+    "verify:compat": "node scripts/check-compatibility.mjs",
+    "verify:published": "node scripts/verify-published-package.mjs",
+    "smoke": "node -e \"import('./index.js').then(m => console.log('WAM plugin loaded successfully'))\"",
+    "test": "node scripts/run-tests.mjs",
+    "test:legacy": "node --test --test-concurrency=1 tests/legacy/wait-a-minute-test.mjs",
+    "test:validation": "node --test benchmarks/validation/*.test.mjs",
+    "test:e2e:opencode": "node tests/e2e/opencode/smoke.mjs",
+    "test:e2e:package": "node scripts/package-e2e.mjs",
+    "test:e2e:migration": "node tests/e2e/migration/run.mjs",
+    "test:isolation": "node tests/isolation/run.mjs",
+    "perf:sanity": "node scripts/performance-sanity.mjs",
+    "wam:next": "node scripts/autonomous-task-runner.mjs --all"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/khnker/opencode-wait-a-minute.git"
+  },
+  "homepage": "https://github.com/khnker/opencode-wait-a-minute#readme",
+  "bugs": {
+    "url": "https://github.com/khnker/opencode-wait-a-minute/issues"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "coding-agent",
+    "task-management",
+    "verification",
+    "context-management"
+  ],
+  "license": "MIT",
+  "type": "module"
+}

package/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module**: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface**: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow, they refer only to the type-level surface).
+
+**Implementation**: what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**: leverage at the interface. The amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_: a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter**: a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage**: what callers get from depth. More capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality**: what maintainers get from depth. Change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow: interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies**, see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces**, see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/skills/design-contract/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: design-contract
+description: design system contracts, token plans, anti-slop rules, state definitions, and critique loops
+license: MIT
+compatibility: opencode, claude-code
+---
+
+# Design Contract & System Governance
+
+Enforce design system integrity and UI/UX predictability.
+
+## Core Pillars
+
+1. **Design Contracts**: Every component or view requires a documented contract in `.opencode/contracts/design.json` (or similar) BEFORE implementation. Defines intended layout, interactions, and constraints.
+2. **Token Plans**: Mandatory use of design tokens (e.g., Tailwind config, CSS variables). NO magic values.
+3. **Anti-Slop Rules**: No nested CSS overrides. No "just quick fix" styles. All components must adhere to established layout patterns.
+4. **State Definitions**: Explicit definitions of component states (loading, error, success, hover, active).
+5. **Critique Loops**: Post-implementation check against the initial design contract. If implementation drifts, it must be refactored before approval.
+
+## Critique Loop Process
+
+Before finalizing any UI task:
+
+1. **Self-Audit**: Compare implementation against design contract.
+2. **Drift Detection**: Identify layout, spacing, or styling inconsistencies.
+3. **Refactor**: Fix identified drift immediately.
+4. **Validation**: Mark as "Contract Compliant" only when drift is zero.

package/skills/design-critique/SKILL.md

@@ -0,0 +1,19 @@
+# Design Critique
+
+Evaluate an interface from a UX perspective, assessing hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring and actionable feedback.
+
+## MANDATORY PREPARATION
+
+Users start this workflow with `/critique`. Gather: what the interface is trying to accomplish.
+
+---
+
+Conduct a holistic design critique, evaluating whether the interface actually works — not just technically, but as a designed experience. Think like a design director giving feedback.
+
+## Reference Checklist
+
+- Hierarchy & Action Prioritization
+- Text Hierarchy & Readability (line length, baseline, alignment)
+- Cognitive Load (working-memory limits)
+- Interaction Design (target sizing, focus, overlay behavior)
+- Search & Findability

package/skills/design-system/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: design-system
+description: Manages UI rules, design tokens, and reference-image analysis for consistent frontend development.
+---
+
+# Design System
+
+Covers Req-24 (UI Rules), Req-25 (Tokens), Req-26 (Reference-image analysis).
+
+## UI Rules (Req-24)
+Follow the principles in `references/ui-rules.md`.
+
+## Tokens (Req-25)
+Use `references/tokens.md` for spacing, typography, colors, and shadows.
+
+## Reference-image Analysis (Req-26)
+Use `references/image-analysis.md` for analyzing and mapping reference images to UI implementation.

package/skills/design-system/references/image-analysis.md

@@ -0,0 +1,14 @@
+# Reference-image Analysis (Req-26)
+
+Based on PGraeff/frontend-design-pro-agent-skill.
+
+## Analysis Pipeline
+1. **Deconstruct Composition**: Identify grid, layout structure, and element positioning.
+2. **Extract Visual Tokens**: Map colors, typography, and spacing to current design tokens.
+3. **Identify "Craft" Details**: Notice shadows, border-radii, micro-interactions, and subtle gradients.
+4. **Map to Component Logic**: Translate visual patterns into reusable UI components.
+
+## Implementation Strategy
+- **Direct Map**: Use exact values if consistency is required.
+- **Abstract**: Map to nearest available token if conforming to existing system.
+- **Extend**: Propose new tokens if the reference image introduces a superior pattern.

package/skills/design-system/references/tokens.md

@@ -0,0 +1,32 @@
+# Design Tokens (Req-25)
+
+## Spacing Scale
+- `0`: 0px
+- `1`: 4px
+- `2`: 8px
+- `3`: 12px
+- `4`: 16px
+- `6`: 24px
+- `8`: 32px
+- `12`: 48px
+- `16`: 64px
+
+## Typography Scale
+- `xs`: 12px / Line height: 16px
+- `sm`: 14px / Line height: 20px
+- `base`: 16px / Line height: 24px
+- `lg`: 18px / Line height: 28px
+- `xl`: 20px / Line height: 28px
+- `2xl`: 24px / Line height: 32px
+- `3xl`: 30px / Line height: 36px
+
+## Semantic Colors
+- `primary`: Main brand/action color.
+- `secondary`: Supporting interface color.
+- `background`: Page base.
+- `surface`: Card/elevated elements.
+- `text-primary`: High-contrast body text.
+- `text-secondary`: Low-contrast auxiliary text.
+- `danger`: Error states.
+- `warning`: Cautionary alerts.
+- `success`: Positive outcomes.

package/skills/design-system/references/ui-rules.md

@@ -0,0 +1,14 @@
+# UI Rules (Req-24)
+
+## 1. Layout & Composition
+- **Rhythm**: Use an 8pt grid for layout and 4pt for components.
+- **Hierarchy**: Distinct visual weight for Primary vs Secondary actions.
+- **Density**: Prefer generous whitespace unless for data-heavy dashboards.
+
+## 2. Interaction
+- **Feedback**: Immediate visual state change on interaction (hover, active, focus).
+- **Affordance**: Elements must look like they can be interacted with.
+
+## 3. Accessibility
+- **Contrast**: Minimum WCAG AA compliance (4.5:1 for normal text).
+- **Focus**: Visible focus indicators for keyboard navigation.

package/skills/diagnosing-bugs/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.
+---
+
+# Diagnosing Bugs
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, read `GLOSSARY.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Redact
+
+This skill has you show commands, outputs and captured artifacts. **Redact every secret first**: write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
+
+If the redacted output is not enough to diagnose the bug, say so and ask the user.
+
+## Phase 1: Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug (one that goes red on _this_ bug), you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one, in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug: unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) that drives the UI and asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight, a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not, so keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+### Completion criterion: a tight loop that goes red
+
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** (a script path, a test invocation, a curl) that you have **already run at least once** (show the invocation and its output, redacted), and that is:
+
+- [ ] **Red-capable**: it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring"; it must be able to _catch this specific bug_.
+- [ ] **Deterministic**: same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast**: seconds, not minutes.
+- [ ] **Agent-runnable**: you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop: jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2: Reproduce + minimise
+
+Run the loop. Watch it go red as the bug appears.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described, not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut, and keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing**: removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
+
+## Phase 3: Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe: discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it; proceed with your ranking if the user is AFK.
+
+## Phase 4: Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5: Fix + regression test
+
+Write the regression test **before the fix**, but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail. If you forced the red by mutating code or a fixture, `diff` against a pristine copy to prove the mutation landed before you trust it.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6: Cleanup
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message, so the next debugger learns

package/skills/frontend-design/SKILL.md

@@ -0,0 +1,36 @@
+# Frontend Design Skills
+
+Modern UI/UX design patterns, guidelines, and frontend implementation rules to build production-grade user interfaces.
+
+## When to Activate
+
+- Designing or implementing user interfaces, pages, or components
+- Structuring layout, typography, colors, and responsive design
+- Refining visual hierarchy and interaction models
+
+## Core Principles
+
+1. **Visual Hierarchy & Flow**
+   - Establish clear page anchors and reading order (Z-pattern or F-pattern).
+   - Use proportional spacing: items related to each other should be closer together than unrelated items (Law of Proximity).
+   - Differentiate levels of information using font size, weight, and color contrast.
+
+2. **Typography System**
+   - Limit font families to a maximum of 2 (one for headings, one for body/UI).
+   - Enforce a strict typographic scale (e.g., 12px, 14px, 16px, 20px, 24px, 32px, 48px).
+   - Maintain line heights between 1.4 and 1.6 for body text, and 1.1 to 1.25 for large headings.
+
+3. **Color & Contrast**
+   - Define a single primary brand color, a clear accent, and a solid neutral scale (grays).
+   - Follow WCAG 2.1 AA requirements: minimum 4.5:1 for normal text, 3:1 for large text and UI components.
+   - Use semantic colors consistently: green for success, red for destructive/error, yellow for warnings.
+
+4. **Layout & Spacing**
+   - Rely on a 4px or 8px grid system for all padding, margins, and gaps.
+   - Avoid hardcoded component widths; prefer flexbox, grid, and fluid percentage/auto sizing.
+   - Maintain consistent padding inside cards, containers, and modals.
+
+5. **Interactions & Feedback**
+   - Provide clear hover, focus-visible, and active states for all interactive elements.
+   - Design skeleton loaders or spinners for asynchronous states to avoid layout shifts (CLS).
+   - Ensure touch targets are at least 44x44px for mobile/touch devices.

package/skills/handoff/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS (`$TMPDIR`, else `/tmp`; `%TEMP%` on Windows) - not the current workspace.
+
+Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the Skill tool with "codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `GLOSSARY.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow**, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files**: which files/modules are involved
+- **Problem**: why the current architecture is causing friction
+- **Solution**: plain English description of what would change
+- **Benefits**: explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use GLOSSARY.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `GLOSSARY.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `GLOSSARY.md`?** Add the term to `GLOSSARY.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `GLOSSARY.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.