litclaude-ai 0.3.7 → 0.3.8

package/plugins/litclaude/skills/programming/SKILL.md

@@ -10,22 +10,61 @@ Go, shell glue, plugin manifests, and test harnesses. It is the Claude-native
 port of LitClaude programming discipline: strong types, small units, explicit
 boundaries, and tests that prove behavior before code is accepted.
 
-## Phase 0: Language Gate
-
-Before editing, identify the language and the project-local conventions. Prefer
-the repository's existing tools over introducing a new stack. If the task spans
-multiple languages, write down the boundary between them before coding.
-
-- JavaScript/TypeScript: keep ESM when the package is ESM, use `node:test` or
-  the repo's configured runner, avoid `any`, `as` narrowing, and hidden globals.
-- Python: prefer typed dataclasses/Pydantic boundaries, `pathlib`, explicit
-  exception types, and deterministic scripts.
-- Rust: prefer typed errors, exhaustive matches, `?`, and no `unwrap` outside
-  tests or tiny `main` wrappers.
-- Go: use `context.Context` at I/O boundaries, typed errors, no unchecked
-  `err`, and focused packages.
-- Shell: quote variables, use `set -euo pipefail` in scripts, and make cleanup
-  explicit.
+This SKILL.md is an index. The hard per-language rules live under `references/`.
+Treat it as a routing table: read the matching language reference **before**
+writing a single line of code, then apply the shared philosophy on top.
+
+---
+
+## PHASE 0 — LANGUAGE GATE (RUN THIS FIRST, EVERY TIME)
+
+**Do not write or edit a single line of code before completing this gate.**
+
+1. **Identify the language** from the file extension or the user's request.
+2. **Stop** and read the matching reference set with the `Read` tool:
+
+   | File / Language | Mandatory reading |
+   |---|---|
+   | `.py`, `.pyi`, "Python" | `references/python/README.md` + every file under `references/python/` the README routes you to |
+   | `.rs`, `Cargo.toml`, "Rust" | `references/rust/README.md` + every file under `references/rust/` the README routes you to. **If the change touches `unsafe`, `*mut`, `*const`, `MaybeUninit`, FFI, `unsafe impl Send/Sync`, or a custom lock-free primitive, ALSO read `references/rust-ub/README.md` and every file under `references/rust-ub/`.** |
+   | `.ts`, `.tsx`, `.mts`, `.cts`, "TypeScript" | `references/typescript/README.md` + every file under `references/typescript/` the README routes you to |
+   | `.go`, `go.mod`, `go.sum`, `.golangci.yml`, `*.proto` next to a Go module, "Go" / "Golang" | `references/go/README.md` + every file under `references/go/` the README routes you to |
+
+3. Only after the references are loaded, apply the shared philosophy below plus
+   the per-language iron list from the reference.
+
+Prefer the repository's existing tools over introducing a new stack. If the task
+spans multiple languages, write the boundary between them down before coding.
+**No exceptions for "small" or "one-off" code** — disposable scripts (`uv run`
++ PEP 723, `rust-script`, `bun run`, `go run` + `//go:build ignore`) cost
+nothing to write with full discipline, so they get the full treatment too.
+
+---
+
+## Shared philosophy
+
+These are not style preferences. They are the axioms every recipe in
+`references/` derives from.
+
+1. **The type system is your proof system.** Make illegal states unrepresentable.
+   The type checker is the cheapest test you will ever run. If a bug can be
+   expressed as a type error, express it as a type error.
+2. **Parse, don't validate.** Untrusted input crosses a boundary exactly once;
+   there it is parsed into a typed value. Inside the boundary, code receives
+   typed values and never re-validates. The boundary owns trust; the interior
+   owns logic.
+3. **One name = one concept.** A `UserId` is not a `string`; `Seconds` is not
+   `Milliseconds`. Use a branded primitive for every distinct semantic unit so
+   the compiler refuses to let two units mix.
+4. **Exhaustive variant matching, always.** Discriminated unions and enums are
+   matched exhaustively with a never-reached guard. `if`/`elif`/`else` to
+   discriminate a tagged variant is forbidden — it silently swallows new cases.
+5. **Trust framework guarantees; validate only at boundaries.** No null checks
+   for values the type system already proves non-null. No `try`/`catch` around
+   code that cannot raise. No escape hatch papering over a contract you should
+   have encoded in types.
+6. **Test-driven, with the right shape of test.** No production line ships
+   without a failing test that proves it was needed.
 
 ## Parse, don't validate
 
@@ -41,38 +80,217 @@ Examples:
 - Environment variables are read at the edge and converted into explicit paths,
   booleans, or enums.
 
-## TDD DISCIPLINE
+---
+
+## TDD DISCIPLINE — NON-NEGOTIABLE
+
+For production behavior, follow red -> green -> refactor. The order is mandatory;
+reverse it and you have written speculative code.
+
+1. **Red.** Add a failing test that names the missing behavior and *fails for the
+   right reason* — not a typo, not an import error. A test that fails because the
+   function does not exist yet is the right reason; a missing import is not.
+2. **Green.** Write the smallest change that passes that test. Resist adding the
+   second case until the first passes — the second case is the next red.
+3. **Refactor.** Simplify with the tests still green. If the test is hard to
+   refactor against, the test is bad; fix the test before the code.
+
+### The test pyramid
+
+Every feature ships with all three rungs, sized in this proportion:
+
+| Rung | Count | Purpose | Speed budget |
+|---|---|---|---|
+| **Unit** | many | Pure-function correctness for every meaningful input class (happy + edges + boundaries + error paths) | < 10 ms each |
+| **Integration** | some | The real adapter against the real downstream (file system, plugin manifest, CLI, DB, queue, HTTP). Never a unit test pretending to be integration. | < 1 s each |
+| **E2E scenario** | few | One narrative per user-visible outcome: tmux transcript, HTTP status/body, browser screenshot, desktop automation log. Asserts the observable outcome, not internal state. | seconds, on CI |
+
+Tests alone are not completion proof when the change affects user workflows.
+Pair green tests with one real scenario artifact. If a user-facing feature has
+zero E2E coverage, it is undone even when every unit test passes.
+
+### Given / When / Then is mandatory
+
+Every test is structured by three blocks:
 
-For production behavior, use red -> green -> refactor.
+```
+Given: the exact fixture and preconditions
+When:  the single action under test
+Then:  one observable outcome AND only that outcome
+```
 
-1. Red: add a failing test that names the missing behavior and fails for the
-   right reason.
-2. Green: write the smallest change that passes that test.
-3. Refactor: simplify with the tests still green.
+One `When` per test. Multiple `When`s = multiple tests. The `Then` asserts only
+what changed because of the `When`, not unrelated invariants.
 
-Tests should follow Given / When / Then:
+### Mock priority ladder — less mock, the better
 
-- Given: exact fixture and preconditions.
-- When: one action.
-- Then: one observable outcome or one assertion class.
+Mocks are a last resort, not a default. Walk down this ladder and stop at the
+first rung that works:
+
+1. **Real object** — when constructable in under 1 ms (most domain types, pure
+   functions, value objects).
+2. **In-memory fake** — a real implementation of the interface backed by a
+   map/slice for stores, caches, queues. The fake has its OWN test proving it
+   behaves like the real one.
+3. **Sandbox / container** — real Postgres, real Redis, real S3-compatible, via
+   the project's container harness. Slow but truthful.
+4. **Wire-level fake** — fake at the HTTP wire, not at the SDK.
+5. **Mock** — only when 1–4 are genuinely infeasible (clock, randomness,
+   external SaaS with no sandbox). Mock the narrowest seam, never a whole
+   service. A mock that returns whatever the test wants is a tautology.
+
+**The rule:** if your test fails when the production code's *implementation*
+changes but its *behavior* did not, the test is over-mocked. Delete the mock and
+assert on observable outputs.
+
+### Prompt and skill tests follow the same rule
 
 For prompt and skill text, assert on behavior-bearing rules and structure, not
 on fragile full-string snapshots. A good prompt test checks that a required
-decision, tool boundary, or safety rule is present.
+decision, tool boundary, or safety rule is present — never that an exact
+sentence survives verbatim.
 
-## Test Shape
+---
 
-Use the fastest truthful surface:
+## Cross-language iron list
 
-- Unit tests for pure parsing and decision logic.
-- Integration tests for file-system state, plugin manifests, and CLI behavior.
-- Manual QA for the user-facing surface: tmux transcript, HTTP status/body,
-  browser screenshot, or desktop automation log.
+Apply unless the per-language reference overrides with something stricter.
 
-Tests alone are not completion proof when the change affects user workflows.
-Pair green tests with one real scenario artifact.
+| Rule | Python | Rust | TypeScript | Go |
+|---|---|---|---|---|
+| Immutable by default | `@dataclass(frozen=True, slots=True)` / Pydantic `frozen=True` | every binding is `let` unless mutation is the documented purpose | every field is `readonly`; arrays are `readonly T[]` | value types, unexported fields, no mutation methods unless mutation is the purpose |
+| Branded primitives | `UserId = NewType("UserId", int)` | `struct UserId(u64);` newtype tuple | `type UserId = Brand<string, "UserId">` | `type UserID string` + smart constructor with unexported field |
+| Exhaustive variant matching | `match` + `assert_never` | `match` (compiler-enforced) | `switch` + `assertNever` | sealed interface + type switch + exhaustiveness linter |
+| No untyped escape hatches | no `Any` in public sigs, no `cast`, no `# type: ignore` | no `unwrap`/`expect` outside `main`/tests, no `as` for narrowing | no `any`, no `as` (except `as const`, `satisfies`), no `!`, no `@ts-ignore` | no bare `any` in domain sigs; no `_ = err`; no unexplained lint suppression |
+| No bare error strings | typed exception dataclass | `thiserror` enum (lib) or `anyhow` + `.context(...)` (app) | `Error` subclass with typed fields | sentinel + typed error struct; wrap with `%w`; check via `errors.Is/As` |
+| Boundary catch only | catch the exact exception; broad catch only in `main()` with re-raise | `?` everywhere; never `panic!` in library code | `catch` narrows with `instanceof` then re-throws/converts; no empty catch | every `(T, error)` checked; `panic` only in `main`/tests |
+| Resources via RAII / ownership | `with` / `async with` | `Drop` impl or RAII guard | `using` / `await using` | `defer x.Close()` immediately after acquisition |
+| Async runtime choice | `anyio` (never bare `asyncio`) | `tokio` | platform-native async with `AbortSignal` cancellation | `context.Context` first param + `errgroup`; `-race` on every test |
+| Modern HTTP client | typed HTTP/2 client with brotli + zstd | `reqwest` with rustls | `ky` / `undici` — never bare `fetch` in prod | stdlib `net/http.Client` with tuned `Transport` + retry/backoff |
+| No parameter mutation | params are inputs; produce a new value | `&mut` only when mutation is documented | parameters never reassigned | value receivers unless mutation is the purpose |
+| No helpers for one-off | inline a 3-line operation until the second caller | same | same | same |
+
+---
+
+## Canonical libraries by domain
+
+Use these unless the project's manifest explicitly picks something else. A bare
+default constructor (no timeouts, no pool tuning, no schema) is a bug — see the
+per-language reference for production defaults.
+
+| Domain | Python | Rust | TypeScript | Go |
+|---|---|---|---|---|
+| Boundary parse | Pydantic v2 | `serde` + `#[derive(Deserialize)]` | Zod | smart constructors + request validator |
+| Internal value object | frozen dataclass | newtype tuple struct | `readonly` type alias | struct with unexported fields + constructor |
+| Error types | typed exception dataclass | `thiserror` (lib) + `anyhow` (app) | `Error` subclass + Result | sentinel + typed error struct + `%w` wrap |
+| Web framework | FastAPI | axum | Hono | gin / chi / connect-go |
+| DB access | SQLAlchemy 2.x async | `sqlx` (compile-time checked) | Drizzle | sqlc + pgx + migrations |
+| CLI | typer + rich | clap (derive) | commander | cobra + slog |
+| Logging | structlog | tracing | pino | stdlib `log/slog` |
+| Testing | pytest | nextest + proptest + insta | bun test / vitest | stdlib `testing` + container harness |
+| Config from env | pydantic-settings | figment / config | zod + `process.env` | struct-tag env parser |
+
+## Modern toolchain
+
+| Tool category | Python | Rust | TypeScript | Go |
+|---|---|---|---|---|
+| Project manager | uv | cargo + nextest + deny | Bun (pnpm if Node is forced) | go modules + `go work` |
+| Type checker | strict pyright/basedpyright | rustc `-D warnings` + clippy pedantic | `tsc --noEmit` with the strict flag set | go compiler + strict golangci-lint + nil-deref static analysis |
+| Linter + formatter | ruff | clippy + rustfmt | Biome | gofumpt + goimports + golangci-lint |
+| Test runner | pytest | nextest | bun test / vitest | `go test -race -shuffle=on -count=1` |
+| Soundness gate | (n/a) | nightly miri with strict provenance | (n/a) | `-race` + leak detector |
+
+CI-gate one-liners — the command a pre-commit hook or CI lane runs:
+
+- Python: `ruff check . && basedpyright && pytest`
+- Rust: `cargo clippy -- -D warnings && cargo nextest run && cargo +nightly miri test`
+- TypeScript: `bunx biome check . && bunx tsc --noEmit && bun test`
+- Go: `gofumpt -l . && golangci-lint run ./... && go test -race -shuffle=on -count=1 ./...`
+
+A `tsconfig.json` with `"strict": true` alone is not strict — the reference
+enumerates the additional flags. The same holds for `pyproject.toml` and
+`Cargo.toml`: the references carry the canonical full configuration.
+
+---
+
+## THE 250 PURE LOC CEILING (NON-NEGOTIABLE)
+
+Treat 250 non-comment, non-blank lines in a source file as a hard design
+warning. A file past this line is telling you the module does more than one
+thing, that cohesive units got fused "to save a file", and that every future
+reader pays a tax to find what they need.
+
+### Why 250
+
+At 250 pure LOC a file still fits in one screen at a readable font. A reviewer
+can hold the whole thing in working memory and spot a cross-cutting bug. The
+number is the cognitive ceiling of a single reviewer who has not memorized the
+file.
+
+### Measuring pure LOC
+
+```bash
+# Quick (line-comment + blank exclusion):
+awk '!/^[[:space:]]*$/ && !/^[[:space:]]*(\/\/|#|--)/' <file> | wc -l
+
+# Authoritative (handles block comments):
+cloc --by-file <file>   # the "code" column is the number that matters
+```
 
-## Type and Error Discipline
+### Required behavior
+
+- **Creating a file that will exceed 250 pure LOC:** split it before the first
+  commit. Carve by responsibility, one cohesive unit per file. Use a barrel
+  (`__init__.py`, `mod.rs`, `index.ts`) for re-exports only, never for logic.
+- **Editing a file already over 250 pure LOC when your edit adds lines:**
+  refactor the unit you are touching into its own file *before* adding the new
+  lines. The split is part of THIS task, not a follow-up nobody does.
+- **Reading a file over 250 pure LOC while implementing a feature:** surface the
+  smell in your reply, propose a concrete split (which functions go where, one
+  line each), and ask whether to split now. Do not silently keep going.
+
+### Forbidden escapes
+
+- Counting comments and blanks toward the budget. Pure LOC means code lines.
+- Splitting by token count (`module_part_a`, `service-2`). Split by what each
+  file does and name it after the concept it owns.
+- Catch-all dumps (`utils`, `helpers`, `common`, `shared`). They relocate the
+  smell, not remove it.
+- "It's a test file with many cases." Split by subject-under-test or behavior
+  cluster, one file per cohesive group.
+- "230 LOC, close enough." A 230-LOC file about to grow is already over the
+  line. Split now; do not race to the ceiling.
+
+### Before / after split example
+
+Before — `user_service.py`, ~412 pure LOC, doing too much:
+
+```python
+class UserRepository: ...   # ~90 LOC of DB access
+class UserValidator: ...    # ~60 LOC of boundary parse + rules
+class PasswordHasher: ...   # ~40 LOC of hashing wrapper
+class EmailSender: ...      # ~50 LOC of HTTP client
+class UserService: ...      # ~130 LOC orchestrating the four above
+```
+
+After — split by responsibility, every file under the ceiling:
+
+```
+src/myapp/users/
+├── __init__.py     # barrel: re-exports UserService only   (~5 LOC)
+├── repository.py   # UserRepository                        (~95 LOC)
+├── validator.py    # UserValidator                         (~65 LOC)
+├── password.py     # PasswordHasher                        (~45 LOC)
+├── notifier.py     # EmailSender (named for the role)      (~55 LOC)
+└── service.py      # UserService (thin orchestrator)       (~135 LOC)
+```
+
+Each file owns one concept. The barrel exposes the only public name. The
+reviewer never scrolls through password hashing to understand mail retry policy.
+
+---
+
+## Type and error discipline
 
 - Make illegal states difficult to represent.
 - Use semantic names for IDs, paths, versions, plugin keys, and command names.
@@ -82,25 +300,138 @@ Pair green tests with one real scenario artifact.
 - Avoid defensive code that checks impossibilities. If a case is possible, name
   it and test it. If it is impossible, encode that in parsing or types.
 
-## 250 LOC Ceiling
-
-Treat 250 non-comment lines in a source file as a design warning. If a touched
-file is already too large and the change adds logic, split the cohesive unit you
-are modifying before adding more. Keep orchestrators thin, parsing isolated,
-and command implementations focused.
-
-## Resource and State Hygiene
+## Resource and state hygiene
 
 Every spawned process, tmux session, temp directory, port, browser context, or
 container needs a cleanup receipt. Register cleanup when the resource is
 created, not after the test passes. A leftover process means the work is not
 done.
 
-## Claude Code Adaptation
+---
+
+## MANDATORY POST-WRITE SELF-REVIEW LOOP
+
+This runs every time you finish writing or substantively editing code, before
+you claim the task is done.
+
+### Step 1 — measure
+
+For every file you created or modified, run the pure-LOC count above.
+
+### Step 2 — interpret
+
+| Pure LOC | Verdict | Required action |
+|---|---|---|
+| ≤ 200 | Healthy | continue |
+| 200–250 | Warning band | state the fact explicitly and propose a split if the next edit adds lines |
+| > 250 | Defect | do not commit; refactor into smaller cohesive units now, in this same task |
+
+### Step 3 — architectural self-review (always, even at 80 LOC)
+
+Answer these in your reply before declaring done:
+
+1. **Single responsibility?** Can you name what the file owns in one noun
+   phrase? If the answer needs "and", split.
+2. **Boundary purity?** Did you parse untrusted input into a typed value, or
+   pass an untyped blob past the boundary?
+3. **Variant discrimination?** Any non-exhaustive branch on a tagged type?
+4. **Escape hatches?** Any untyped cast, suppression, or `unwrap`/`!` outside
+   `main`/tests?
+5. **Defensive layer?** Any guard for a value the type system already proves?
+6. **Helpers for one-off?** Any abstraction with a single caller that will never
+   get a second?
+7. **Tests?** Is the new behavior locked by a test that fails if you revert it?
+
+If any answer fails, fix it before declaring done.
+
+### Step 4 — hand off to the recovery skills
+
+- The file you just wrote (or an adjacent one) is over 250 pure LOC, or step 3
+  surfaced more than two issues: **load the `refactor` skill** and run its
+  safe-refactor protocol (codemap, plan, characterization tests, edits with
+  tests after each step). Do not improvise a structural change under pressure.
+- You inherited code with AI-generated patterns (broad catches, redundant null
+  checks, vague TODOs, oversized modules, dead helpers): **load the
+  `remove-ai-slops` skill** to do a categorized cleanup with regression tests
+  pinned first.
+
+These are the recovery path for the defects this loop is designed to catch, not
+optional cosmetics.
+
+---
+
+## Per-language jump table
+
+Stop. Read the matching reference fully before writing code.
+
+### Python (`.py`, `.pyi`)
+
+Read `references/python/README.md` first, then load on demand:
+
+| Need | Load |
+|---|---|
+| Strict pyproject / type checker / ruff config | `references/python/pyproject-strict.md` |
+| Type patterns (`NewType`, `Final`, `Protocol`) | `references/python/type-patterns.md` |
+| Data modeling (Pydantic vs dataclass vs TypedDict) | `references/python/data-modeling.md` |
+| Error handling (typed exceptions, exhaustive match) | `references/python/error-handling.md` |
+| Async with anyio | `references/python/async-anyio.md` |
+| FastAPI + async DB stack | `references/python/fastapi-stack.md` |
+| Canonical library defaults | `references/python/libraries.md` |
+| Disposable PEP 723 scripts | `references/python/one-liners.md` |
+
+### Rust (`.rs`, `Cargo.toml`)
+
+Read `references/rust/README.md` first, then load on demand:
+
+| Need | Load |
+|---|---|
+| Strict `Cargo.toml` lints + profile | `references/rust/cargo-strict.md` |
+| Type-state and newtype patterns | `references/rust/type-state.md` |
+| `unsafe` discipline (safe wrapper + SAFETY comment + miri proof) | `references/rust/unsafe-discipline.md` |
+| Async with tokio | `references/rust/async-tokio.md` |
+| Concurrency primitives | `references/rust/concurrency.md` |
+| axum HTTP stack | `references/rust/axum-stack.md` |
+| Canonical library defaults | `references/rust/libraries.md` |
+| Any `unsafe` / FFI / `MaybeUninit` / lock-free work | `references/rust-ub/` (full directory) |
+
+### TypeScript (`.ts`, `.tsx`, `.mts`, `.cts`)
+
+Read `references/typescript/README.md` first, then load on demand:
+
+| Need | Load |
+|---|---|
+| Strict tsconfig + Biome config | `references/typescript/tsconfig-strict.md` |
+| Type patterns (branded types, `satisfies`, `assertNever`) | `references/typescript/type-patterns.md` |
+| Data modeling (type vs interface vs Zod, parse-don't-validate) | `references/typescript/data-modeling.md` |
+| Error handling (Result, typed errors, AbortSignal timeouts) | `references/typescript/error-handling.md` |
+| Bootstrapping a new project | `references/typescript/bootstrap.md` |
+| Hono backend stack | `references/typescript/backend-hono.md` |
+
+### Go (`.go`, `go.mod`, `go.sum`, `.golangci.yml`, `*.proto`)
+
+Read `references/go/README.md` first, then load on demand:
+
+| Need | Load |
+|---|---|
+| Library defaults (gin vs chi, sqlc, slog) | `references/go/libraries.md` |
+| Canonical strict `.golangci.yml` | `references/go/golangci-strict.md` |
+| Project layout, CI, `go.mod` template | `references/go/bootstrap.md` |
+| Type patterns (named types, smart constructors, sealed interfaces) | `references/go/type-patterns.md` |
+| Error handling (`errors.Is/As`, `%w` wrapping, no panic) | `references/go/error-handling.md` |
+| Concurrency (`context.Context`, `errgroup`, `-race`) | `references/go/concurrency.md` |
+| HTTP backend stack | `references/go/backend-stack.md` |
+| Testing (Given/When/Then, table-driven, fakes-over-mocks) | `references/go/testing.md` |
+
+---
+
+## Claude Code adaptation
+
+Prefer Claude Code's available tools and project conventions. If a private
+reference instruction names a tool from another agent runtime, translate the
+principle instead of copying the tool name. For example, goal tools become
+conditional `get_goal` / `create_goal` / `update_goal` guidance only when
+exposed; workflow isolation uses `Workflow`, `EnterWorktree`, or an explicit
+`claude --worktree ...` operator path when that is the available Claude surface.
 
-Prefer Claude Code's available tools and project conventions. If a Private reference
-instruction names a Codex-only tool, translate the principle instead of copying
-the tool name. For example, goal tools become conditional `get_goal` /
-`create_goal` / `update_goal` guidance only when exposed; workflow isolation
-uses `Workflow`, `EnterWorktree`, or an explicit `claude --worktree ...`
-operator path when that is the available Claude surface.
+The references contain the recipes. Read them before writing code, and re-read
+them when the model drifts. The post-write self-review loop is non-negotiable.