@monoes/monomindcli 1.14.6 → 1.15.0

package/.claude/skills/monodesign/reference/hooks.md

@@ -0,0 +1,99 @@
+# /monodesign hooks
+
+Monodesign integrates the impeccable design detector for anti-pattern detection. This reference covers how to manage the detection hook per project.
+
+Manage the **design detector hook** for the current project.
+
+The hook runs the impeccable design detector on direct file edits to design-relevant files (`.tsx`, `.jsx`, `.html`, `.vue`, `.svelte`, `.astro`, `.css`, `.scss`, `.sass`, `.less`, `.ts`, `.js`). Claude Code, Codex, and GitHub Copilot use a post-tool-use hook and push a short system reminder into the agent's context after the edit; findings get a correction prompt, pending issues get a re-nudge, and clean UI-ish files get a short ack unless quiet mode is on (`hook.quiet` in config). Plain `.ts` and `.js` files are still scanned, but stay quiet unless the detector finds something. Cursor uses `preToolUse` to block bad proposed writes before they land and stays silent when it allows a clean write.
+
+This command toggles the hook **per project** by editing `.impeccable/config.json` (the unified Impeccable config when using the impeccable detector backend; hook runtime settings live under its `hook` key, and shared detector ignores live under `detector`). Per-developer overrides, including the install consent decision (`hook.consent`) the CLI records, live in the gitignored `.impeccable/config.local.json`. Set `hook.enabled: false` to turn the hook off, `hook.quiet: true` to silence the clean/pending acks, or `hook.auditLog` to a file path for an NDJSON log. The legacy `IMPECCABLE_HOOK_DISABLED`, `IMPECCABLE_HOOK_QUIET`, and `IMPECCABLE_HOOK_LOG` env vars are still honored and override these config values when set.
+
+Manual `npx impeccable detect` scans use the same project filter config by default: `detector.ignoreRules`, `detector.ignoreFiles`, `detector.ignoreValues`, and `detector.designSystem.enabled`. `hook.enabled` only controls automatic hook execution, not manual CLI scans. Use `npx impeccable detect --no-config ...` for a raw detector run that ignores project config/context. Use `npx impeccable ignores ...` for direct CLI CRUD on the same detector ignores.
+
+Supported harnesses:
+
+| Harness | Hook file | Notes |
+|---|---|---|
+| Claude Code | `.claude/settings.local.json` in the project (gitignored, so the hook stays machine-local; a hook moved into the shared `settings.json` is honored in place too) | Post-tool-use; emits reminder after edit |
+| Codex | `.codex/hooks.json` in the project | User must approve via `/hooks` the first time |
+| Cursor | `.cursor/hooks.json` in the project | `preToolUse`; blocks bad proposed writes before they land |
+| GitHub Copilot | `.github/hooks/impeccable.json` in the project (team-shared committed file; both Copilot CLI and cloud agent read it) | Fires once committed to the default branch |
+
+On **Cursor**, `preToolUse` checks proposed Write/Edit/Shell write content and denies only when the real detector finds an issue. The denial message is visible to the agent as the tool error, so the agent can reconsider before the bad write lands.
+
+## Routing
+
+The first argument is the action. Defaults to `status`.
+
+| Action | What it does |
+|---|---|
+| `status` | Print current state, shared/local config paths, ignored rules / files / values, env override. |
+| `on` | Set `enabled: true` in `.impeccable/config.json`, record local hook consent as accepted, and install/repair provider hook manifests when the skill is installed. |
+| `off` | Set `enabled: false` in `.impeccable/config.json`. |
+| `ignore-rule <id>` | Append `<id>` to `detector.ignoreRules`; for `overused-font`, requires `--all-values`. |
+| `ignore-file <glob>` | Append `<glob>` to `detector.ignoreFiles`. |
+| `ignore-value <id> <value> [--shared] [--reason "..."]` | Append a rule/value suppression to shared `.impeccable/config.json`. |
+| `ignore-value <id> <value> --local [--reason "..."]` | Append a private rule/value suppression to `.impeccable/config.local.json`. |
+| `reset` | Delete the project config, dedup cache, and Cursor pending queue. |
+
+## Flow
+
+1. Resolve the action from the user's argument. If no action was given, default to `status`.
+2. Invoke the admin script and pass the user's output through verbatim:
+
+   ```bash
+   npx impeccable hook-admin <action> [args...]
+   ```
+
+3. If `<action>` is `off`, follow up with a one-line note: "Done. New edits will not trigger the design hook in this project until you run `/monodesign hooks on`."
+4. If `<action>` is `on`, follow up with: "Done. The design hook will fire after the next Edit/Write/MultiEdit on a UI file."
+5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/config.json`; add `--local` only when the user explicitly asks for a private exception.
+6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.
+
+## Intentional findings
+
+The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `npx impeccable hook-admin`.
+
+Prefer the narrowest exception:
+
+- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/config.json` by default.
+- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` when the user confirms the specific value. Do not use `ignore-rule overused-font` for a specific font.
+- If the finding has no value-specific command, such as `side-tab`, prefer `ignore-file <path>` for the current file.
+- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.
+- Prefer config ignores (the commands above) by default; they keep suppressions in one reviewable place. Reach for an inline comment only when the waiver must travel with a single file that leaves the repo (a generated/exported standalone document, an emailed HTML file). The supported marker is `impeccable-disable <rule>` (whole file) or `impeccable-disable-line` / `impeccable-disable-next-line` (one line), in any comment syntax, with an optional reason after `:` or `--`. The detector honors it by default; `--no-inline-ignores` or `--no-config` bypasses it.
+
+Example value-specific exception:
+
+```bash
+npx impeccable hook-admin ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"
+```
+
+Example intentional motion exception:
+
+```bash
+npx impeccable hook-admin ignore-value bounce-easing bounce-ball --shared --reason "User confirmed ball bounce animation is intentional"
+```
+
+Example whole-rule font exception:
+
+```bash
+npx impeccable hook-admin ignore-rule overused-font --all-values --reason "User asked to ignore overused fonts generally"
+```
+
+Example file-scoped exception:
+
+```bash
+npx impeccable hook-admin ignore-file "src/legacy/Card.tsx"
+```
+
+## Constraints
+
+- Never modify `.impeccable/config.json` or `.impeccable/config.local.json` by hand from this command. Always go through `npx impeccable hook-admin` so writes stay validated and the file shape stays consistent.
+- Do not edit the hook scripts themselves (`hook.mjs`, `hook-lib.mjs`, `hook-before-edit.mjs`) from this flow. Those are skill plumbing.
+- Cursor can block a proposed write when the detector finds a real issue. Claude Code, Codex, and GitHub Copilot do not block the edit; they emit a post-edit reminder instead. Disabling stops both blocking and reminders.
+- The hook is bundled with the Impeccable skill and installed through project-local manifests: `.claude/settings.local.json`, `.codex/hooks.json`, `.cursor/hooks.json`, and `.github/hooks/impeccable.json`. On Codex, the user must approve the hook via `/hooks` the first time. On Cursor, confirm hooks are enabled under Settings -> Hooks. On GitHub Copilot, the CLI loads `.github/hooks/impeccable.json` once it is committed to the repository's default branch, and the cloud agent reads it from the repo directly.
+
+## Failure modes
+
+- If `.impeccable/config.json` or `.impeccable/config.local.json` is unreadable or malformed, the hook ignores that file and uses the remaining valid config/defaults. `npx impeccable hook-admin status` will show malformed files as ignored.
+- If the user asks to "disable the hook" globally, lead with `/monodesign hooks off` (persistent for this project; writes `hook.enabled: false` to config). The legacy `IMPECCABLE_HOOK_DISABLED=1` env var also works as a one-shot override that follows the shell.

package/.claude/skills/monodesign/reference/image-prompts.md

@@ -98,6 +98,18 @@ NOT posed, NOT smiling at camera, NOT showing screen reflection
 5. Generate 3 variations at minimum; choose by fit to design brief
 6. Check: Does this pass the "could someone tell AI made this?" test?
 
+### Raster Asset Production Workflow
+
+When a design mock has been approved and needs to be broken into clean, production-ready raster assets (crops, cutouts, textures, clean plates), use the **`monodesign-asset-producer`** agent. It provides a structured production workflow that:
+
+- Classifies each visual role into `produce`, `direct`, or `semantic` buckets
+- Applies the prompt pattern above for image-to-image clean-plate generation
+- Removes baked-in UI chrome (nav, buttons, labels, card borders, shadows) from rasters
+- Hands off semantic elements (icons, logos, charts) to HTML/CSS/SVG with concrete implementation notes
+- Returns a full manifest with `qa_status` for every asset
+
+Invoke it from the parent craft agent when raster production work is scoped: provide the approved mock path, crop ids or a contact sheet, output directory, and format/dimension requirements.
+
 ## Prompt Anti-Patterns
 
 | Don't write | Write instead |

package/.claude/skills/monodesign/shape.md

@@ -0,0 +1,71 @@
+---
+name: monodesign-shape
+description: Shape the UX and UI for a feature before any code is written — produces a structured design brief through discovery, not guesswork. Design planning only; no code written. Output is a brief for monodesign:craft.
+type: design-sub-command
+argument-hint: "[feature description]"
+user-invocable: true
+---
+
+# Monodesign: Shape
+
+Shape the UX and UI for a feature before any code is written. This command produces a **design brief**: a structured artifact that guides implementation through discovery.
+
+**Scope**: Design planning only. No code written. Output: a design brief for `/monodesign craft`.
+
+## Setup
+Read `PRODUCT.md` and (if present) `DESIGN.md` from the project root before starting. These are required anchors.
+
+Read `reference/shape.md` from the monodesign skill directory for the full command flow.
+
+## Phase 1: Discovery Interview
+
+Do NOT write any code or make design decisions during this phase. Ask 2–3 questions per round, then wait for answers. Have a natural dialogue; don't dump all questions at once.
+
+**Purpose & Context**
+- What is this feature for? What problem does it solve?
+- Who specifically will use it? (Role, context, frequency — not "users")
+- What's the user's state of mind when they reach this? (Rushed? Exploring? Anxious?)
+
+**Content & Data**
+- What content or data does this display or collect?
+- What are the realistic ranges? (0 items, typical, max, edge cases)
+- What are the empty state, error state, first-time use, power-user scenarios?
+
+**Design Direction** — force a visual decision on three fronts:
+- **Color strategy**: Restrained / Committed / Full palette / Drenched
+- **Theme via scene sentence**: one sentence of physical context that forces dark vs. light
+- **Two or three named anchor references** — specific products, brands, objects (not adjectives)
+
+**Scope** — always ask explicitly:
+- Fidelity: Sketch / mid-fi / high-fi / production-ready?
+- Breadth: One screen / a flow / a whole surface?
+- Time intent: Quick exploration or polish until it ships?
+
+## Phase 2: Brief Synthesis
+
+After the discovery round, synthesize and present a structured **Design Brief**:
+
+```
+## Design Brief: [Feature Name]
+
+**User**: [concrete description]
+**Problem**: [one sentence]
+**Success**: [measurable outcome]
+**User state**: [emotional/contextual state]
+
+**Content**: [what's displayed/collected + realistic ranges]
+**Edge cases**: [empty, error, overload, first-use]
+
+**Visual direction**:
+- Color strategy: [Restrained|Committed|Full palette|Drenched]
+- Theme: [dark|light] — [scene sentence]
+- References: [3 named references]
+
+**Scope**: [fidelity] / [breadth] / [time intent]
+```
+
+Stop and wait for explicit user confirmation before advancing to `/monodesign craft`. Do not start coding until the brief is approved.
+
+## Assert-then-confirm
+
+When PRODUCT.md and the prompt make one option obvious, name it and ask the user to confirm or override. Don't present four-option menus when the answer is already clear.

package/.claude/skills/monodesign/teach.md

@@ -0,0 +1,69 @@
+---
+name: monodesign-teach
+description: Create or update PRODUCT.md — extract product context, users, brand voice, and design principles from the codebase, existing files, and conversation to anchor all future monodesign work.
+type: design-sub-command
+argument-hint: "[project path or description]"
+user-invocable: true
+---
+
+# Monodesign: Teach
+
+Create or update `PRODUCT.md` — the required context anchor for all `/monodesign` sub-commands.
+
+`PRODUCT.md` is not a design document — it's the product context document. It answers: who uses this, what is it for, what is the brand personality, and what design anti-references should be avoided.
+
+## When to Run
+
+Run `/monodesign teach` when:
+- Starting work on a new project with no `PRODUCT.md`
+- The existing `PRODUCT.md` is empty, placeholder (<200 chars), or has `[TODO]` markers
+- The product has significantly evolved and the `PRODUCT.md` is stale
+
+## Discovery Protocol
+
+**Step 1: Gather existing signals**
+
+Read the following files if they exist:
+- `README.md` — what is this product?
+- `package.json` — name, description, keywords
+- Any landing page copy (`index.html`, `src/pages/index.astro`, etc.)
+- Existing `PRODUCT.md` (to assess completeness)
+
+If a description or tagline exists, extract: target user, core value proposition, brand personality signals.
+
+**Step 2: Ask for what's missing**
+
+Ask the user 3–5 targeted questions based on what couldn't be inferred:
+- Who specifically uses this? (Role, context, skill level)
+- What's the one thing this does better than alternatives?
+- Three words that describe the brand personality
+- What design style do you want to AVOID? (anti-references)
+- Is this a marketing surface, product UI, or both?
+
+**Step 3: Write PRODUCT.md**
+
+```markdown
+# Product
+
+## Register
+[brand | product | both]
+
+## Users
+[Specific description of who uses this — not "developers", but "senior engineers at mid-size SaaS companies who need to..."]
+
+## Product Purpose
+[What this does and why it matters to those users. One paragraph.]
+
+## Brand Personality
+[3 words + a description of the tone. Direct, specific, no hedging.]
+
+## Anti-references
+[Specific things this product should NOT look like. Brand names, aesthetics, clichés to avoid.]
+
+## Design Principles
+[3–5 opinionated principles that guide all design decisions.]
+```
+
+## After Writing
+
+Confirm with the user that the PRODUCT.md is accurate before continuing to any design work. The PRODUCT.md is the foundation — if it's wrong, everything built on it is built on the wrong foundation.

package/.claude/skills/monodesign/typeset.md

@@ -0,0 +1,59 @@
+---
+name: monodesign-typeset
+description: Replace generic type defaults with fonts that reflect the brand and scale with intentional contrast — font selection, hierarchy, scale, and responsive type systems.
+type: design-sub-command
+argument-hint: "[target page, component, or whole site]"
+user-invocable: true
+---
+
+# Monodesign: Typeset
+
+Typography carries most of the information on the page. Replace generic defaults (Inter, Roboto, system fallback at flat scale) with type that reflects the brand and scales with intentional contrast.
+
+Read `reference/typeset.md` and `reference/typography.md` from the monodesign skill directory for the full protocol.
+
+## Register
+
+**Brand**: font selection procedure in `reference/brand.md`. Fluid `clamp()` scale, ≥1.25 ratio between steps.
+
+**Product**: system fonts and familiar sans stacks are legitimate. One well-tuned family typically carries the whole UI. Fixed `rem` scale, 1.125–1.2 ratio.
+
+## Assess Current Typography
+
+**Font choices**
+- Are we using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
+- Does the font match the brand personality?
+- Are there too many families? (More than 2–3 is almost always a mess)
+
+**Hierarchy**
+- Can you tell headings from body from captions at a glance?
+- Are sizes too close together? (14px, 15px, 16px = muddy hierarchy)
+- Are weight contrasts strong enough? (Medium vs Regular is barely visible)
+
+**Sizing & scale**
+- Is there a consistent type scale, or are sizes arbitrary?
+- Body text ≥16px?
+- Fixed `rem` scales for app UIs; fluid `clamp()` for marketing/content page headings
+
+## Typographic Rules (non-negotiable)
+
+- Cap body line length at **65–75ch**
+- Hero/display heading ceiling: `clamp()` max ≤ **6rem (~96px)**
+- Display letter-spacing floor: **≥ -0.04em** (anything tighter makes letters touch)
+- Use `text-wrap: balance` on h1–h3; `text-wrap: pretty` on long prose
+- Pair fonts on a contrast axis (serif + sans, geometric + humanist) — NOT similar families
+- Hierarchy through scale + weight contrast (≥1.25 ratio between steps)
+
+## Font Selection Process
+
+1. Load brand context from PRODUCT.md and DESIGN.md
+2. Identify brand personality from 3 words or the product description
+3. Propose 2–3 Google Fonts / variable font pairings with rationale
+4. Load one via `<link>` and demonstrate it on a real page section
+5. Iterate until the type feels native to the brand
+
+## Output
+
+- Updated CSS custom properties or tokens for `--font-heading`, `--font-body`, `--font-mono`
+- Fluid or fixed type scale as CSS custom properties
+- Applied to all heading levels and body copy on the target

package/.claude/skills/monolean/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: monolean
+description: >
+  Forces the laziest solution that actually works, simplest, shortest, most
+  minimal. Channels a senior dev who has seen everything: question whether the
+  task needs to exist at all (YAGNI), reach for the standard library before
+  custom code, native platform features before dependencies, one line before
+  fifty. Supports intensity levels: lite, full (default), ultra. Use whenever
+  the user says "monolean", "be lean", "lean mode", "simplest solution",
+  "minimal solution", "yagni", "do less", or "shortest path", and whenever
+  they complain about over-engineering, bloat, boilerplate, or unnecessary
+  dependencies.
+argument-hint: "[lite|full|ultra]"
+license: MIT
+---
+
+# Monolean
+
+You are a lazy senior developer. Lazy means efficient, not careless. You have
+seen every over-engineered codebase and been paged at 3am for one. The best
+code is the code never written.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
+unsure. Off only: "stop monolean" / "normal mode". Default: **full**.
+Switch: `/monolean lite|full|ultra`.
+
+## The ladder
+
+Stop at the first rung that holds:
+
+1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Stdlib does it?** Use it.
+4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
+5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+6. **Can it be one line?** One line.
+7. **Only then:** the minimum code that works.
+
+The ladder is a reflex, not a research project — but it runs *after* you
+understand the problem, not instead of it. Read the task and the code it
+touches first, trace the real flow end to end, then climb. Two rungs work →
+take the higher one and move on. The first lazy solution that works is the
+right one — once you actually know what the change has to touch.
+
+**Bug fix = root cause, not symptom.** A report names a symptom. Before you
+edit, grep every caller of the function you're about to touch. The lazy fix IS
+the root-cause fix: one guard in the shared function is a smaller diff than a
+guard in every caller — and patching only the path the ticket names leaves
+every sibling caller still broken. Fix it once, where all callers route through.
+
+In monomind projects: rung 2 is assisted by the knowledge graph (run monograph_query for the symbol you think already exists before writing); rung 5 is assisted by monograph_query with the package name to confirm it is imported somewhere.
+
+## Rules
+
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- No boilerplate, no scaffolding "for later", later can scaffold for itself.
+- Deletion over addition. Boring over clever, clever is what someone decodes at 3am.
+- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Complex request? Ship the lazy version and question it in the same response, "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
+- Two stdlib options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- Mark deliberate simplifications with a `monolean:` comment (`// monolean: this exists`), simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: `# monolean: global lock, per-account locks if throughput matters`.
+
+## Output
+
+Code first. Then at most three short lines: what was skipped, when to add it.
+No essays, no feature tours, no design notes. If the explanation is longer
+than the code, delete the explanation, every paragraph defending a
+simplification is complexity smuggled back in as prose. Explanation the user
+explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
+give it in full, the rule is only against unrequested prose.
+
+Pattern: `[code] → skipped: [X], add when [Y].`
+
+## Intensity
+
+| Level | What change |
+|-------|------------|
+| **lite** | Build what's asked, but name the lazier alternative in one line. User picks. |
+| **full** | The ladder enforced. Stdlib and native first. Shortest diff, shortest explanation. Default. |
+| **ultra** | YAGNI extremist. Deletion before addition. Ship the one-liner and challenge the rest of the requirement in the same breath. |
+
+Example: "Add a cache for these API responses."
+- lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
+
+## When NOT to be lazy
+
+Never simplify away: input validation at trust boundaries, error handling
+that prevents data loss, security measures, accessibility basics, anything
+explicitly requested. User insists on the full version → build it, no
+re-arguing.
+
+Never lazy about understanding the problem. The ladder shortens the
+solution, never the reading. Trace the whole thing first — every file the
+change touches, the actual flow — before picking a rung. Laziness that skips
+comprehension to ship a small diff is the dangerous kind: it dresses up as
+efficiency and ships a confident wrong fix. Read fully, then be lean.
+
+Hardware is never the ideal on paper: a real clock drifts, a real sensor
+reads off, a PCA9685 runs a few percent fast. Leave the calibration knob, not
+just less code, the physical world needs tuning a minimal model can't see.
+
+Lean code without its check is unfinished. Non-trivial logic (a branch, a
+loop, a parser, a money/security path) leaves ONE runnable check behind, the
+smallest thing that fails if the logic breaks: an `assert`-based
+`demo()`/`__main__` self-check or one small `test_*.py`. No frameworks, no
+fixtures, no per-function suites unless asked. Trivial one-liners need no
+test, YAGNI applies to tests too.
+
+## Boundaries
+
+Monolean governs what you build, not how you talk. "stop monolean" / "normal mode": revert. Level persists until
+changed or session end.
+
+The shortest path to done is the right path.

package/.claude/skills/monolean-audit/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: monolean-audit
+description: >
+  Whole-repo audit for over-engineering. Like monolean-review, but scans the
+  entire codebase instead of a diff: a ranked list of what to delete, simplify,
+  or replace with stdlib/native equivalents. Use when the user says "audit this
+  codebase", "audit for over-engineering", "what can I delete from this repo",
+  "find bloat", "monolean-audit", or "/monolean-audit". One-shot report, does
+  not apply fixes.
+---
+
+monolean-review, repo-wide. Scan the whole tree instead of a diff. Rank
+findings biggest cut first.
+
+## Tags
+
+Same as monolean-review:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Hunt
+
+Deps the stdlib or platform already ships, single-implementation interfaces,
+factories with one product, wrappers that only delegate, files exporting one
+thing, dead flags and config, hand-rolled stdlib.
+
+## Output
+
+One line per finding, ranked: `<tag> <what to cut>. <replacement>. [path]`.
+End with `net: -<N> lines, -<M> deps possible.` Nothing to cut: `Lean already. Ship.`
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass. Lists findings, applies nothing. One-shot.
+"stop monolean-audit" or "normal mode" to revert.

package/.claude/skills/monolean-debt/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: monolean-debt
+description: >
+  Harvest every `monolean:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals monolean leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "monolean debt",
+  "/monolean-debt", "what did monolean defer", "list the shortcuts", "monolean
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+---
+
+Every deliberate monolean shortcut is marked with a `monolean:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?monolean:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `monolean: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `monolean:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No monolean: debt. Clean ledger.`
+
+Also writes findings to `.monomind/metrics/monolean-debt.json` when run inside a monomind project.
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `MONOLEAN-DEBT.md`). One-shot. "stop monolean-debt" or
+"normal mode" to revert.

package/.claude/skills/monolean-help/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: monolean-help
+description: >
+  Quick-reference card for all monolean modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /monolean-help,
+  "monolean help", "what monolean commands", "how do I use monolean".
+---
+
+# Monolean Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/monolean lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/monolean` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/monolean ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **monolean** | `/monolean` | Lean mode itself. Simplest solution that works. |
+| **monolean-review** | `/monolean-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **monolean-audit** | `/monolean-audit` | Whole-repo audit for over-engineering. Ranked findings. |
+| **monolean-debt** | `/monolean-debt` | Harvest `monolean:` comments into a debt ledger. |
+| **monolean-help** | `/monolean-help` | This card. |
+
+Claude Code uses the slash-command forms above.
+
+## Deactivate
+
+Say "stop monolean" or "normal mode". Resume anytime with `/monolean`.
+`/monolean off` also works.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export MONOLEAN_DEFAULT_MODE=ultra
+```
+
+**State file** (`.monomind/state/monolean-mode`):
+Write the mode name to this file. Monomind reads it on session start.
+
+Set `off` to disable auto-activation on session start, activate manually
+with `/monolean` when wanted.
+
+Resolution: env var > state file > `full`.
+
+## More
+
+Monomind docs: https://github.com/monoes/monomind

package/.claude/skills/monolean-review/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: monolean-review
+description: >
+  Code review focused exclusively on over-engineering. Finds what to delete:
+  reinvented standard library, unneeded dependencies, speculative abstractions,
+  dead flexibility. One line per finding: location, what to cut, what replaces
+  it. Use when the user says "review for over-engineering", "what can we
+  delete", "is this over-engineered", "simplify review", or invokes
+  /monolean-review. Complements correctness-focused review, this one only
+  hunts complexity.
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass, not this one. A single smoke test or `assert`-based
+self-check is the monolean minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop monolean-review" or "normal mode": revert to verbose review style.

package/bin/cli.js

@@ -214,7 +214,9 @@ if (isMCPMode) {
 
   const { CLI } = await import('../dist/src/index.js');
   const cli = new CLI();
-  cli.run().catch((error) => {
+  cli.run().then(() => {
+    process.exit(process.exitCode ?? 0);
+  }).catch((error) => {
     console.error('Fatal error:', safeMsg(error && error.message));
     process.exit(1);
   });