habit-hooks 0.1.0-beta.0

package/src/prompts/eslint-typescript-eslint-no-explicit-any.md

@@ -0,0 +1,3 @@
+`any` opts out of the type checker — every property access, call, and assignment becomes unchecked. The bug it hides next will be silent.
+
+Prefer a precise type. When the shape really is unknown (parsed JSON, external input), use `unknown` and narrow with a type guard at the boundary. Casting through `as Foo` only moves the problem.

package/src/prompts/eslint-typescript-eslint-no-inferrable-types.md

@@ -0,0 +1,3 @@
+`const count: number = 0` repeats what TypeScript already knows. Drop the annotation; the inferred type is identical and the declaration reads more cleanly.
+
+Keep annotations where they document an interface contract (function signatures, exported constants where the literal type would be too narrow), not where they restate the obvious.

package/src/prompts/eslint-typescript-eslint-no-non-null-assertion.md

@@ -0,0 +1,3 @@
+The `!` operator tells TypeScript "trust me, this is not null" — and at runtime nobody is checking. When the assumption breaks you get a `Cannot read properties of undefined` with no clue why.
+
+Prove the value is present: an `if`-guard with an early return, an `assert`, `??` with a sensible default, or restructure so the optional case is impossible at the call site.

package/src/prompts/jscpd-duplication.md

@@ -0,0 +1,9 @@
+Duplicated blocks are the cheapest visible sign of a missing abstraction. The right fix is rarely "extract a helper" — it's usually to name the concept that both copies are reaching for.
+
+Read both occurrences side by side and ask: (1) Are these two copies of the same idea, or two different ideas that happen to look alike? (2) If they are the same idea, what is its name? (3) Does the duplicated block belong to a domain concept that does not exist yet — a value object, a strategy, a small class?
+
+Avoid mechanical extraction. Pulling the matching lines into a function with five parameters and a couple of conditionals leaves the real shape untouched and adds a worse name on top. If extracting feels awkward, the underlying abstraction is wrong — step back and find the right one.
+
+A concrete technique: try to write one sentence that names what both copies do. If the sentence reads naturally, that sentence is the name of the abstraction you are missing. If you can only describe the block as "the code that does X, Y, and Z", the duplication is hiding two or three smaller abstractions, not one.
+
+If the two copies actually diverge in important ways and a shared abstraction would distort either side, document the decision (a short note or a test that pins both behaviours) and snooze the duplication — duplication is the lesser evil compared to a wrong abstraction.

package/src/prompts/knip-classMembers.md

@@ -0,0 +1,7 @@
+An unused class member is dead weight: either delete it or wire it up. There is no third option that does not lie to a future reader.
+
+Delete by default. If the member is part of a planned-but-unbuilt API, document that in code with `@public`/`@internal` JSDoc tags so knip can be configured to ignore it — do not leave the dead code naked.
+
+If you find yourself wanting to keep the member "just in case", that is a signal you have not committed to a direction. Pick one: delete it now, or write the test that exercises it so it stops being unused.
+
+A concrete technique: search the codebase for the method name. If the only hit is the definition itself, the method is genuinely dead. If there are hits in tests but no production caller, the test is testing the test — delete both.

package/src/prompts/knip-dependencies.md

@@ -0,0 +1,9 @@
+A `package.json` dependency with no detected import is either genuinely unused, or used through a path the tool cannot statically see (config-loaded plugins, peer requirements of another tool, dynamic `require`). The right action depends on which one — guess wrong and you either ship dead bytes or break a build.
+
+Ask first: does anything load this package by name from a config file? Common culprits — `typescript-eslint` pulled in by an ESLint flat config, `postcss` plugins loaded from `postcss.config.js`, `vite` plugins, framework adapters. These show up as "unlisted" too because knip sees them imported from a file it does not scan. The fix is to teach knip about the config (extend its `plugins` config) or list the dependency in `ignoreDependencies` with a one-line note explaining why.
+
+Otherwise the dependency is genuinely unused. Uninstall it (`pnpm remove <pkg>`), run the build and tests, and commit. Carrying unused dependencies inflates lockfiles, slows installs, and widens the supply-chain attack surface.
+
+Avoid mechanical fixes. Adding a stray `import` somewhere to "use" the package only hides the question. Blanket-ignoring all flagged deps is worse — every entry in `ignoreDependencies` should be a deliberate decision with a reason attached.
+
+A concrete technique: for each flagged package, search the repo for its name as a string (not just as an import). Hits in config files mean it is config-loaded — document it. Zero hits means it is truly unused — remove it.

package/src/prompts/knip-exports.md

@@ -0,0 +1,9 @@
+An `export` that no consumer references is either internal-by-accident or a deliberate public surface the tool does not know about. Either way the current state is misleading — the keyword tells readers "someone outside this module depends on this", and that is not true.
+
+Ask first: is this symbol part of a deliberate public API? Library entry points, framework hooks, plugins, types re-exported for downstream consumers — these are real exports knip just cannot see. The fix is configuration: add the file (or the symbol's containing entry) to `entry` in `knip.json` so the tool stops asking.
+
+Otherwise the export is internal-by-accident. Drop the `export` keyword. The symbol stays — it is still used inside its own module — it just stops pretending to be part of the module's public surface. Tests that imported it directly should reach in via the public API or move into the same module.
+
+Avoid mechanical fixes. Adding a no-op re-export from `index.ts` to satisfy knip does not address the smell; it just makes the implicit public surface look intentional. Suppressing the rule per-symbol scatters the public-API decision across the codebase instead of capturing it in one config file.
+
+A concrete technique: for each flagged export, ask "if I remove the `export` keyword, what breaks?" If nothing breaks, the export was a lie. If something outside the module breaks, you have just discovered an undocumented public dependency — write it down in `knip.json` and treat that file as a public-API surface from now on.

package/src/prompts/knip-files.md

@@ -0,0 +1,9 @@
+A file that no one imports is either an entry point the tool does not know about, or genuinely orphaned code. Pick one — leaving it in the repo as "probably used somewhere" rots into a maintenance trap.
+
+Ask first: is this file entry-point-like? CLI scripts, server entries, test setup, build hooks, framework-discovered routes — these are called by something other than `import`. If so, the fix is configuration, not deletion: add the path (or a glob covering it) to `entry` in `knip.json` so the tool can see why it exists.
+
+Otherwise the file is orphaned. Delete it. If it is a "kept for reference" or "we might need this again" file, that is a confession that nobody owns it; version control is your reference, not the working tree.
+
+Avoid mechanical fixes. Adding a one-line `import` from somewhere else just to silence knip creates a fake consumer and hides the real status of the file. Wrapping the whole file in a `knip-ignore` comment without first deciding which category it falls into preserves the ambiguity.
+
+A concrete technique: try to delete the file in a scratch branch and run the build and tests. If everything passes, the file was orphaned and you have your answer. If something breaks, you have just located the implicit entry point that needs to be made explicit in `knip.json`.

package/src/prompts/knip-types.md

@@ -0,0 +1,9 @@
+A `type` or `interface` exported with no consumer is either internal-by-accident or an undeclared public type surface. Either way the keyword lies: it tells readers "something outside this module depends on this shape", when nothing does.
+
+Ask first: is this type part of a deliberate public API? Return-types and option-bags that flow through an exported function, types re-exported from a package entry, types consumed by a downstream plugin or framework — these are real public surface knip just cannot see. The fix is configuration: add the file (or the symbol's containing entry) to `entry` in `knip.json` so the tool stops asking.
+
+Otherwise the type is internal-by-accident. Drop the `export` keyword. The type stays — it is still used inside its own module — it just stops pretending to be part of the module's public surface. If a test was importing the type directly, that usually means the test is reaching past the public API; move the test to the same module, or assert against the function's inferred return type instead.
+
+Avoid mechanical fixes. Re-exporting the type from `index.ts` to satisfy knip does not address the smell; it just makes the implicit public surface look intentional. Suppressing the rule per-symbol scatters the public-API decision across the codebase instead of capturing it in one config file.
+
+A concrete technique: for each flagged type, ask "if I remove the `export` keyword, what breaks?" If nothing breaks, the export was a lie. If something outside the module breaks, you have just discovered an undocumented public type — write it down in `knip.json` and treat that file as a public-API surface from now on.

package/src/prompts/uncoached.md

@@ -0,0 +1,3 @@
+These rules fired in your project but habit-hooks does not ship a tuned coaching prompt for them yet. The violations above are the raw output from the underlying tool (ESLint, knip, jscpd) — read them as you would read any lint message.
+
+If a particular uncoached rule fires often and you have a clear stance on how to address it, write your own prompt: drop a markdown file named after the slugified rule id (e.g. `eslint-no-console.md`) into the prompts directory configured in `habit-hooks.config`. Habit Hooks will pick it up automatically and surface it the same way it does for built-in prompts.

package/src/skills/habit-hooks-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: habit-hooks-review
+description: "Spawn a reviewer sub-agent to assess a change set against habit-hooks's coding principles. Use AFTER habit-hooks reports clean — habit-hooks catches structural smells; this catches what it cannot (correctness, tests, design, missed edge cases)."
+---
+
+# Habit Hooks Review
+
+You are reading this because `habit-hooks` reported clean and you (the implementing agent) need a second pair of eyes on the change set before declaring the work done.
+
+A green habit-hooks run is necessary, not sufficient. habit-hooks catches structural smells — oversized functions, high complexity, `any`, dead bindings, stale `TODO`s, comments standing in for unclear code. It cannot see:
+
+- Correctness bugs (logic errors, off-by-one, wrong branch taken).
+- Design issues (wrong abstraction, leaky boundaries, missing seam).
+- Test coverage gaps (a happy path test masquerading as full coverage, untested error paths).
+- Missed edge cases (empty input, concurrent calls, mid-iteration mutation).
+- Naming clarity (a name that reads fine in isolation but is wrong for the role it plays).
+- Missing abstractions that do not trip a threshold (two functions that should share a type, three call sites that should share a helper).
+
+This skill spawns a reviewer sub-agent to look for exactly those things.
+
+## How to invoke
+
+Use the `Task` tool to spawn a `general-purpose` sub-agent with the brief below. Do **not** review the change yourself first — the value of this skill is the fresh read. Include the diff scope (commit range, branch, or staged files) in the brief so the reviewer knows what to look at.
+
+## The brief
+
+Paste this verbatim into the Task tool's `prompt`, filling in the change-set scope at the top:
+
+---
+
+You are reviewing a change set against the principles below. The implementing agent has already run `habit-hooks` and it reports clean — so structural smells (function size, parameter count, complexity, file length, `any`, unused vars, etc.) are already covered. **Do not re-flag anything habit-hooks catches.** Focus on what habit-hooks cannot see.
+
+**Change set under review:** `<describe scope: commit range, branch diff, or staged files>`
+
+**Ground rules:**
+
+- PASS-when-clean is the right answer. Do not manufacture issues to look thorough.
+- If the change is small and well-shaped, say so. A two-line PASS is a valid outcome.
+- Cite `file:line` for every finding. No vague "consider revisiting the design" — point at something.
+- Assume the change was written TDD-first. If tests are missing or asymmetric (only happy paths, only the new code), say so.
+
+**Principles to review against:**
+
+- **KISS** — is there a simpler approach that does the same job?
+- **Single responsibility** — does each new function/class have one reason to change?
+- **Naming clarity** — does every name reveal intent? Can a future reader understand it in five seconds?
+- **Readability** — is the change comfortable to navigate, or does it ask the reader to hold too many ideas?
+- **No shortcuts** — flag `eslint-disable`, `@ts-ignore`, `as any`, swallowed catches, magic numbers without context. Even if the linter is happy, those are debts.
+- **Correctness** — read the logic, not just the shape. Look for off-by-one, wrong-branch, swallowed errors, race conditions, mid-iteration mutation.
+- **Edge cases** — empty input, single-element input, max/min, error paths.
+- **Test coverage** — is each new behaviour exercised? Are failure modes tested, not just happy paths?
+
+**Categorise findings:**
+
+- **Blocking** — must be fixed before merge. Correctness bugs, broken tests, gate failures, missing test for new behaviour.
+- **Worth flagging** — design or clarity issues the author should weigh. Not necessarily blocking, but worth a conversation.
+- **Nits** — small polish items. Hard cap: **two**. If you have more than two nits, drop the weakest ones.
+
+**Confirm the gate:**
+
+Run (or read the most recent output of) all four scripts: `typecheck`, `lint`, `test`, `build`. Detect the package manager from the lockfile in the project root (`pnpm-lock.yaml` → `pnpm`, `yarn.lock` → `yarn`, `bun.lock` or `bun.lockb` → `bun`, otherwise `npm`) and invoke accordingly — pnpm/yarn/bun take the script name directly (`pnpm typecheck`), npm needs `run` (`npm run typecheck`).
+
+All four must exit 0. Report each exit code in the output.
+
+**Output format (return this verbatim):**
+
+```
+## Verdict
+<PASS | CHANGES NEEDED>
+
+## Findings
+
+### Blocking
+- <file:line — one-line summary. One short paragraph of detail.>
+- (or: "None.")
+
+### Worth flagging
+- <file:line — one-line summary. One short paragraph of detail.>
+- (or: "None.")
+
+### Nits (max 2)
+- <file:line — one-line summary.>
+- (or: "None.")
+
+## Gate output
+- typecheck: exit <code>
+- lint: exit <code>
+- test: exit <code>
+- build: exit <code>
+
+## Specific calls
+<Anything that does not fit the categories above — design questions for the author, a follow-up worth scheduling, a pattern worth a CLAUDE.md note. Keep it short or omit the section entirely.>
+```
+
+---
+
+## After the reviewer returns
+
+- If **PASS**: relay the verdict and finish the task.
+- If **CHANGES NEEDED**: do not silently fix everything. Surface the findings to the user, agree which to act on, and only then implement. Blocking items must be resolved; worth-flagging items are a conversation, not an assignment.
+
+## Why this is a separate skill from `code-style-review`
+
+`code-style-review` is invoked by a human, on a file or a region, to start a discussion before refactoring. It lists problems for the human to triage and prioritise.
+
+`habit-hooks-review` is invoked by an agent, after a clean automated gate, to get a second-pass quality read on a finished change set. The shape of the output is different — verdict-driven, scoped to the diff, framed for an agent that is about to declare done.
+
+The two skills are complementary, not interchangeable. Do not use `code-style-review` as a stand-in here: it will not check the gate, will not categorise by blocking severity, and will not return a verdict.