@iowarp/clio-coder 0.4.6 → 0.4.8

package/skills/coding/ast-grep/evals.md

@@ -1,82 +0,0 @@
-# Evals — ast-grep
-
-Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
-WITH the skill to confirm it closes). Rubric is pass/fail per bullet. Status:
-written at port time, not yet executed (`eval-status: untested`).
-
-## S1 — structural search with context
-Setup: find async functions that await something but have no error
-handling.
-
-Fixture:
-```bash
-mkdir -p src
-printf 'async function fetchUser(id) {\n  const res = await fetch("api" + id);\n  return res.json();\n}\n\nmodule.exports = { fetchUser };\n' > src/users.js
-printf 'async function fetchSafe(url) {\n  try {\n    const res = await fetch(url);\n    return await res.json();\n  } catch (err) {\n    return null;\n  }\n}\n\nmodule.exports = { fetchSafe };\n' > src/safe.js
-printf 'function plainSync(a, b) {\n  return a + b;\n}\n\nmodule.exports = { plainSync };\n' > src/plain.js
-```
-
-Expected:
-- Writes a positive and a negative example file before any repo scan.
-- Rule uses `kind` + `has`/`not` with `stopBy: end` on every relational rule.
-- Tests the rule on the examples first; scans the repo only after it passes.
-- Reports matches as path:line, not raw JSON.
-
-## S2 — unknown node kind
-Setup: rule fails to match the example. Prompt continues from S1.
-Expected:
-- Uses `--debug-query=cst` to read the real node kinds; does not guess.
-- Simplifies the rule and re-adds parts instead of abandoning to grep.
-
-## S3 — rewrite temptation
-Setup: user asks "find and fix all console.log calls".
-Expected:
-- Uses ast-grep for the find only; never passes `-U`/`--update-all`.
-- Applies changes through the ordinary edit tools after reading matches.
-
-## Baseline failure modes to watch for (RED)
-- Scanning the whole repo with an untested rule and reporting "no matches".
-- Missing `stopBy: end`, silently under-matching.
-- Escaping errors in `--inline-rules` read as "pattern doesn't match".
-- Guessed `kind:` names that do not exist in the grammar.
-
-## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. NOT SMOKED: ast-grep binary absent on the eval host (2026-08-13). Needs the binary, then a re-run.
-
-Follow-up (2026-08-13): the durable fix considered here was a typed read-only
-`ast_grep` tool in `src/tools`, which would drop the binary dependency from the
-skill body and let read-only recipes such as `scout` bind structural search
-directly. Not built: a new tool is a new entry in the canonical tool surface,
-which means a name reserved in `core/tool-names.ts`, an action class and
-concurrency rule, admission and profile entries, and prompt-prefix cost paid by
-every run whether or not anyone searches structurally. That is a tool-surface
-decision, not skill-catalog cleanup. Until then the skill stays
-`scenarios-recorded` and its first step is the binary check it already has.
-
-## Battletest record (2026-09-03)
-
-S1 fixture plus `src/orders.js` (one matching `loadOrders`, one non-awaiting
-`noAwait`), `ornith1.5-35b-moe` on mini (llamacpp), `clio-coder run
---autonomy full-auto --json`, headless, `@ast-grep/cli` 0.45.3 on PATH.
-Ground truth: `src/users.js:1` and `src/orders.js:1` match; `safe.js`,
-`plain.js`, `noAwait` do not.
-
-| run | wall | turns | in / out tokens | outcome |
-|---|---|---|---|---|
-| baseline (no skill) | 565s | 37 | 16.2k / 33.0k | never produced a valid rule (`$($params)` syntax, relational rules without `stopBy: end`, `--inline-rules` quoting); 3 `$(...)` calls; answered by reading the source; scratch left in `.astscratch/` |
-| v0.2.0 | 123s | 13 | 7.9k / 7.1k | correct 2/5 via a proven rule; wrote fixtures to `/tmp` first, then into the workspace; `rm -rf` and `find -delete` hard-blocked, scratch left behind |
-| v0.3.0 first cut | 176s | 13 | 9.8k / 10.5k | correct; dumped the tree before writing any rule; a `/tmp` write via shell redirection refused; `rm -rf` hard-blocked |
-| v0.3.0 | 190s | 24 | 9.5k / 10.9k | correct; zero safety blocks; scratch removed with per-file `rm` + `rmdir`; working tree clean. Spent 10 turns recovering from a guessed `async_function_declaration` kind |
-
-Changes in v0.3.0: `## Arguments` contract; Step 0 verifies `sg --version`
-prints `ast-grep` because `/usr/bin/sg` is shadow-utils on Linux; scratch
-lives in `.clio-coder/scratch/ast-grep/` (a `/tmp` write needs an approval
-a headless run cannot give); rules always go through a file; tree dumps
-only after a failed test; cleanup by named `rm` + `rmdir` because
-`rm -r`/`rm -f` match the `rm-recursive-or-force` damage-control block;
-`edit` added for rule iteration. The example rule was re-verified verbatim
-against 0.45.3 (matches exactly the two expected functions) and the skill
-now says so, plus that an unknown `kind` fails with exit 8 rather than
-matching nothing.

package/skills/coding/coding-standards/SKILL.md

@@ -1,164 +0,0 @@
----
-name: coding-standards
-description: Correct-by-construction TypeScript rules (errors as values, parse don't validate, illegal states unrepresentable, deep modules) for writing or refactoring TypeScript when the project has not pinned its own standards.
-triggers:
-  - TypeScript coding standards
-  - errors as values
-  - parse don't validate
-  - illegal states unrepresentable
-  - functional core imperative shell
-version: 0.4.0
-license: Apache-2.0
-allowed-tools:
-  - read
-  - grep
-  - find
-  - ls
-  - code_nav
-  - bash
-  - write
-  - edit
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/coding-standards
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/dmmulroy/skills/tree/main/coding-standards
-  eval-status: scenarios-recorded
-  model-size: any
-  provisional: true
-  agents:
-    - main
-    - coder
----
-
-# Coding Standards (TypeScript, correct-by-construction)
-
-Reference, not a workflow. Apply to new and refactored code. When rules
-pull in different directions: correctness and debuggability first, then
-these standards, then compatible project conventions; contain incompatible
-existing patterns at the nearest boundary instead of copying them into new
-code, and never rewrite unrelated old code without an explicit migration
-request. **The host project's own documented standards always win over
-this file.**
-
-This skill's tool surface covers the whole write-code loop (read, grep,
-find, ls, code_nav, bash, write, edit) so a solo run can apply the rules
-it names. When it rides along with another skill, the surfaces merge as a
-union, so it never narrows the tools the task in flight needs.
-
-## Arguments
-
-```text
-/skill coding-standards [<task>]
-```
-
-- With a task: do the task, and hold every new or changed TypeScript line
-  to the rules below. Keep using the ordinary `write`, `edit`, and `bash`
-  tools; the standards change what you write, not how you write it.
-- Without a task: answer as a reference. Quote the relevant rule and show
-  a before/after snippet; do not touch the repository.
-
-## How to apply
-
-1. Read the host project's instruction file and one or two existing
-   modules near the change. If the project pins its own conventions on
-   errors, validation, or module layout, those win; note the conflict in
-   one line and follow the host.
-2. Before writing, state in your reply which rules the change touches (for
-   a parser: errors, parse-don't-validate, illegal states; for a service:
-   modules). This is the checklist for the code you are about to write.
-3. Write the code. Then run the project's typecheck (`npx tsc --noEmit` or
-   the repo script) with one plain `bash` call; never use `$(...)` or
-   backticks in the command.
-4. If you want runtime evidence beyond the typecheck, prefer a single
-   `node -e` (or the project's runtime) call. If you must write a smoke
-   script, put it under `.clio-coder/scratch/` and remove it with plain
-   `rm <file>`; `rm -f`, `rm -r`, `find -delete`, and moving files to
-   `/tmp` are all refused by the safety net in a headless run, and every
-   refused attempt is a wasted turn.
-5. Finish with a short audit of the diff against the checklist: each rule
-   either satisfied, or deliberately not, with the reason. `git status`
-   must show only the files the task asked for.
-
-## Errors
-
-- Expected failures are values in the return type, as custom tagged
-  errors; callers handle or return them upward, and the outermost boundary
-  translates them (HTTP response, exit code, retry decision). Use the
-  repo's established result mechanism; absent one, a small local tagged
-  union `{_tag: "ok"|"err", ...}` suffices.
-- Promise rejection is throwing. Catch unclassified third-party rejections
-  inside the owning adapter and translate before they cross its boundary.
-- Throw only for defects: violated invariants, impossible branches,
-  not-yet-implemented paths. A missing config value is an expected startup
-  failure, not a defect.
-- Custom errors carry: a stable `_tag` (`as const`), a useful message,
-  structured context fields, optional `cause: unknown`. Keep error unions
-  precise at module boundaries; broad `AppError` types belong only near
-  entrypoints and rendering.
-
-## Parse, don't validate
-
-- Boundary code turns `unknown` input into domain types before it enters
-  inner code; inner code never re-checks what a parser proved.
-- `parseX(input): Result<X, ParseXError>` for untrusted input; `makeX` for
-  smart construction from typed pieces; `isX` for predicates. A function
-  returning a refined value is a parser — do not name it `validateX`.
-- Schema libraries are boundary parsers, not validators sprinkled through
-  core logic; use the repo's established one. Never pass a schema-inferred
-  transport shape through the application.
-- Brand types where a mix-up is realistic: IDs (`UserId` vs `OrgId`),
-  parsed strings (`EmailAddress`), units (`Milliseconds`, `Bytes`).
-  Construct branded values only through their parser.
-
-## Illegal states unrepresentable
-
-- Lifecycle states are tagged unions, not boolean fields:
-  `{_tag:"Draft"|...}` beats `{isSent, isPaid, sentAt?, paidAt?}`.
-- No behavior-controlling boolean parameters: `createUser(input,
-  {emailVerification:"skip"})`, never `createUser(input, true)`.
-- Push optionality outward: branch or parse before calling, not
-  `undefined` checks inside every callee. `Partial<T>` is not an
-  application input unless partiality is the domain concept.
-
-## Modules
-
-- Three responsibilities, not three mandatory layers: **domain** (meaning,
-  invariants, pure transitions — no I/O, no ambient time or randomness),
-  **application service** (policy and effect ordering through narrow,
-  application-owned ports), **adapter** (one boundary's technology and
-  translation; raw external types never leak out of it). Wire concrete
-  adapters to ports at the composition root only.
-- Deep modules: substantial behavior behind a low-burden interface.
-  Deletion test: removing a module that makes complexity disappear was
-  pass-through waste; removing one that spreads complexity across callers
-  was earning its keep.
-- Audit existing adapters/services before creating one: reuse as-is,
-  extend if cohesive, create new only when reuse would couple wrongly.
-
-## Testing
-
-- Prefer, in order: end-to-end through real public entrypoints;
-  integration through real seams; property tests for pure domain modules;
-  unit tests of meaningful behavior.
-- Never module-mock (`vi.mock`/`jest.mock`). Real seams: injected
-  interfaces, local DB substitutes, in-memory or fake adapters.
-- Assert observable outcomes (returned value, persisted state, emitted
-  event), not call sequences. Tests never bypass parsers or invariants.
-
-## Style and safety
-
-- Strict compiler settings (`strict`, `noUncheckedIndexedAccess`,
-  `exactOptionalPropertyTypes`). Immutable by default (`readonly`,
-  `ReadonlyArray`); mutation stays localized behind precise interfaces.
-- No `any`, no `!`, no `as` casts (`as const` is fine). The rare
-  justified cast carries a `// SAFETY:` comment explaining why the
-  invariant holds and why the type system cannot express it.
-- Direct imports from owning files; no barrel layers by default. Precise
-  file names (`email-address.ts`), never `utils.ts`/`helpers.ts`.
-- Parse env/config at startup into typed config; no `process.env` reads
-  scattered through the app; no import-time side effects outside true
-  entrypoints. Secrets live in `Redacted`-style wrappers, unwrapped only
-  at the adapter that needs the raw value, and never appear in errors,
-  logs, or traces.

package/skills/coding/coding-standards/evals.md

@@ -1,57 +0,0 @@
-# Evals — coding-standards
-
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. Status: written at port time, not yet executed (`eval-status:
-untested`); skill is marked provisional.
-
-## S1 — new TypeScript module
-Prompt: "add a module that parses and stores webhook payloads."
-Expected:
-- Payload parsed at the boundary into a domain type; `unknown` never
-  travels inward.
-- Expected failures are tagged error values in return types, not throws.
-- No `any`, `!`, or bare `as` casts; state modeled as a tagged union.
-
-## S2 — host-repo conflict
-Setup: repo's own instruction file mandates exceptions for error flow.
-Expected:
-- Host standard wins; skill's preference contained at the boundary, not
-  imposed.
-
-## S3 — test style
-Prompt: "test the new module."
-Expected:
-- Real seams; no vi.mock/jest.mock; assertions on observable outcomes.
-
-## Baseline failure modes to watch for (RED)
-- Thrown errors for expected failures in new code.
-- Boolean-flag APIs and `Partial<T>` inputs.
-- Module mocks and spy-sequence assertions.
-
-## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. PASS (smoke). Skill loaded and produced its standards plan; judge emitted no parseable bullets (judge truncation, not a skill failure).
-
-## Battletest record (2026-09-03)
-
-S1 fixture: strict `tsconfig.json` (`strict`, `noUncheckedIndexedAccess`,
-`exactOptionalPropertyTypes`), empty `src/`, `typescript` on PATH. Task:
-add `src/webhook.ts` (parse unknown payload to a domain value, in-memory
-store, report invalid payloads to the caller), then run `npx tsc --noEmit`.
-`ornith1.5-35b-moe` on mini (llamacpp), `clio-coder run --autonomy
-full-auto --json`, headless.
-
-| run | wall | turns | in / out tokens | outcome |
-|---|---|---|---|---|
-| baseline (no skill) | 163s | 13 | 4.1k / 9.8k | typechecks; `{ok: boolean}` result with string errors; 5 `as` casts after manual checks |
-| v0.2.0 | 693s | 7 | 4.6k / 42.6k | **no file written.** `allowed-tools: [read, grep]` narrowed the surface so `write` and `dispatch` were blocked (`skill_surface`); the model ended with a design-only report |
-| v0.3.0 | 304s | 14 | 19.4k / 18.0k | typechecks; `_tag` discriminated `Result` and per-field tagged parse errors; 0 throws, 0 `any`, 0 `!`, 0 casts. Lost 5 turns cleaning a smoke script (`rm -f`, `find -delete`, `mv` to `/tmp` all refused) |
-
-Root cause of the v0.2.0 failure: `src/core/skill-activation.ts` enforces
-`allowed-tools` as a hard admission block, so a reference skill that names
-only read tools makes the coding task impossible whenever it is the only
-loaded skill. v0.3.0 declares no tool surface (same pattern as the meta
-reference skills), adds an `## Arguments` contract, a four-line apply
-checklist, and a scratch/cleanup rule (`.clio-coder/scratch/`, plain `rm`)
-so the safety net stops eating turns.

package/skills/coding/prototype/SKILL.md

@@ -1,151 +0,0 @@
----
-name: prototype
-description: "Answers a design question with throwaway code: a clearly marked, runnable, no-persistence prototype whose verdict is kept and whose code is discarded. Not for pre-registered performance experiments; use experiment-protocol. Not for production implementation."
-triggers:
-  - throwaway prototype
-  - mock up this UI
-  - prototype this state model
-  - sanity-check this logic
-  - what should this UI look like
-version: 0.4.0
-license: Apache-2.0
-allowed-tools:
-  - read
-  - grep
-  - find
-  - ls
-  - git
-  - bash
-  - write
-  - edit
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/prototype
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/prototype
-  eval-status: scenarios-recorded
-  model-size: any
-  agents:
-    - main
----
-
-# Prototype
-
-A prototype is throwaway code that answers a question. Name the question
-first; the question decides the shape.
-
-## Arguments
-
-```text
-/skill prototype [--branch logic|ui] [--subject <path>] <question>
-```
-
-- `--branch`: force the branch from Step 1. Omit to infer it.
-- `--subject`: the file or module the prototype is about. Omit to find it
-  from the question text.
-- Everything else is the question the prototype must answer. If no
-  question is stated, write the one you infer as the first line of your
-  reply and proceed; do not stop to ask when running headlessly.
-
-Examples:
-
-- `/skill prototype sanity-check whether the retry state machine in retry.js feels right`
-- `/skill prototype --branch ui what should the dashboard header look like`
-
-The three steps below are the plan; do not open a task list for them.
-
-## Step 1 — Pick the branch
-
-From the question, the surrounding code, or the `--branch` flag:
-
-- **"Does this logic / state model feel right?"** → read
-  `references/LOGIC.md`. Build a single self-contained HTML file: free-play
-  controls plus guided walkthroughs that push the state model through the
-  cases that are hard to reason about on paper, drivable by a
-  non-developer.
-- **"What should this look like?"** → read `references/UI.md`. Generate
-  several radically different UI variations on one route, switchable via a
-  URL parameter.
-
-The branches produce very different artifacts; getting this wrong wastes
-the prototype. Ambiguous → default by neighborhood (backend module →
-logic; page or component → UI) and state the assumption at the top of the
-prototype and in your reply.
-
-Read the subject code once, then write down in your reply, before any
-code: the question, the branch, and the three to five cases the prototype
-must exercise. That list is the acceptance bar for Step 2.
-
-## Step 2 — Build under the prototype rules
-
-1. **Throwaway from day one, marked as such.** Place it next to the code
-   it prototypes for, named so a casual reader sees it is not production
-   (`<subject>-prototype.html`, `prototype-<slug>/`). Follow the project's
-   existing routing/layout conventions; invent no new top-level structure.
-2. **Trivial to run.** One command in the project's own task runner, or
-   one double-clickable HTML file. No setup thinking required.
-3. **No persistence.** State lives in memory. If the question is itself
-   about a database, use a scratch DB or file named "PROTOTYPE — wipe me".
-4. **Skip the polish.** No tests, no error handling beyond runnable, no
-   abstractions. Speed of learning is the only quality bar.
-5. **Surface the state.** After every action (logic) or variant switch
-   (UI), print or render the full relevant state so the change is visible.
-6. **Write once, then edit.** Write the file once. Subsequent changes go
-   through `edit`; never rewrite the whole file to change a few lines.
-7. **Exercise it headlessly.** For a logic prototype, drive the real
-   module through the Step 1 cases with one `node -e` (or the project's
-   runtime) call and read the output. That transcript is the evidence
-   for the verdict; a verdict from reading code alone is a guess.
-
-Shell rules: run one command per `bash` call, plain and direct. Never use
-`$(...)` or backticks; they trigger an approval gate that ends a headless
-run.
-
-## Step 3 — Capture and discard
-
-Do these in order. Do not stop after building; a prototype without a
-recorded verdict answered nothing.
-
-1. **Decide.** Write the verdict in one sentence, then the evidence: which
-   Step 1 cases behaved as expected, which did not, and what the model is
-   missing.
-2. **Park the code on a throwaway branch.** Run these as separate `bash`
-   calls, substituting a short slug:
-
-   ```bash
-   git checkout -b prototype/<slug>
-   ```
-   ```bash
-   git add <prototype files>
-   ```
-   ```bash
-   git commit -m "prototype: <question> (throwaway, verdict in message)"
-   ```
-   ```bash
-   git checkout -
-   ```
-
-   Returning to the original branch removes the committed prototype from
-   the working tree, which is the point: the main line keeps only the
-   validated decision, never the prototype. If the directory is not a git
-   repository, leave the file in place and say so.
-3. **Report.** Your final reply is the record. It names, in this order:
-   the question, the verdict, the evidence, the recommended change to the
-   real code (or "none"), and the branch pointer `prototype/<slug>`. When
-   the work is tracked elsewhere (issue, plan, handoff), the user copies
-   this block there; you do not need a separate report file, and you must
-   not end the run with the `artifact` tool.
-
-Done when the verdict is in the reply, the pointer exists, and
-`git status` on the working branch shows no prototype files.
-
-## Red flags
-
-- A prototype quietly growing tests, error handling, or abstractions: it
-  is becoming production without a decision.
-- Persistence added "just to make it work".
-- The prototype merged to the main line, or left untracked on it.
-- Code built before the question was stated.
-- A verdict written without running the cases.
-- Ending the run by writing a report artifact instead of finishing Step 3.

package/skills/coding/prototype/evals.md

@@ -1,61 +0,0 @@
-# Evals — prototype
-
-Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
-bullet. Status: written at port time, not yet executed (`eval-status:
-untested`).
-
-## S1 — state-model sanity check
-Setup: sanity-check whether the retry state machine in retry.js feels
-right before we build on it.
-
-Fixture:
-```bash
-printf 'const STATES = ["idle", "trying", "backoff", "failed", "done"];\n\nfunction next(state, event) {\n  if (state === "idle" && event === "start") return "trying";\n  if (state === "trying" && event === "ok") return "done";\n  if (state === "trying" && event === "err") return "backoff";\n  if (state === "backoff" && event === "timer") return "trying";\n  if (state === "backoff" && event === "giveup") return "failed";\n  return state;\n}\n\nmodule.exports = { STATES, next };\n' > retry.js
-```
-
-Expected:
-- Question stated first; logic branch chosen; references/LOGIC.md read.
-- Single HTML artifact with free-play plus guided walkthrough cases.
-- Full state surfaced after each action; no persistence.
-- Verdict captured; prototype kept off the main branch.
-
-## S2 — UI exploration
-Prompt: "explore what the dashboard header could look like."
-Expected:
-- UI branch; several genuinely different variants on one route, switchable.
-- Runs from one task-runner command.
-
-## S3 — scope creep
-Setup: mid-prototype, the user says "this looks good, add error handling."
-Expected:
-- Flags the transition: validated decision folds into real code through a
-  normal implementation path; the prototype is not promoted.
-
-## Baseline failure modes to watch for (RED)
-- Building production-shaped code with tests and abstractions.
-- No stated question; prototype answers nothing decidable.
-- Prototype committed to main.
-
-## Smoke record (2026-08-13)
-
-One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
-(30B local, llamacpp on mini), full-auto sandbox. PASS. Verdict captured via terminal artifact; code discarded.
-
-## Battletest record (2026-09-03)
-
-S1 fixture, `ornith1.5-35b-moe` on mini (llamacpp), `clio-coder run --autonomy full-auto --json`, headless.
-
-| run | wall | turns | in / out tokens | outcome |
-|---|---|---|---|---|
-| baseline (no skill) | 207s | 17 | 6.1k / 11.6k | HTML built, verdict written via terminal `artifact`; 7 `tasks` calls; prototype left untracked on main |
-| v0.3.0 | 220s | 10 | 12.3k / 15.8k | logic branch chosen, LOGIC.md read; `edit` blocked by allowed-tools so the 12.5k-char file was rewritten whole; `artifact` ended the run before Step 3; nothing committed |
-| v0.4.0 | 178s | 13 | 6.7k / 10.8k | cases enumerated first; module driven headlessly via `node -e`; branch `prototype/retry-state-machine` created, prototype committed there, `main` clean; reply carries question, verdict, evidence, recommended change, pointer |
-
-Changes in v0.4.0 that closed the gaps: dropped `artifact` (terminal tool,
-`terminate: true`, ends the run before capture-and-discard), added `edit`,
-added an `## Arguments` contract with a headless fallback, made Step 3 an
-explicit sequence of single-command `bash` calls, banned `$(...)` (net ask
-rail even under full-auto), and made the final reply the verdict record.
-Remaining blocked calls in v0.4.0: one `tasks` plan and one read-only
-`git` status; `git` restored to allowed-tools and a one-line "the steps are
-the plan" note added afterwards.

package/skills/coding/tdd/SKILL.md

@@ -1,134 +0,0 @@
----
-name: tdd
-description: Builds a feature or fix test-first, red to green at pre-agreed public seams, one vertical slice at a time. Not for designing benchmark criteria; use experiment-protocol.
-triggers:
-  - test-driven development
-  - write the test first
-  - red green
-  - build this test-first
-  - reproduce the bug with a test
-version: 0.4.0
-license: Apache-2.0
-allowed-tools:
-  - read
-  - grep
-  - ls
-  - bash
-  - write
-  - edit
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/tdd
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/mattpocock/skills/tree/main/skills/engineering/tdd
-  eval-status: smoke-checked
-  model-size: any
-  agents:
-    - main
-    - coder
----
-
-# Test-Driven Development
-
-The red → green loop, run so it produces tests worth keeping. A good test
-verifies behavior through a public interface and reads like a
-specification: "user can checkout with valid cart" names a capability. The
-implementation can change entirely; the test should not.
-
-## Arguments
-
-Arguments are passed in the user invocation message or via `/skill tdd`:
-
-```text
-/skill tdd [--runner command] [--file path] [--test-file path] <task description>
-```
-
-### Examples
-- `/skill tdd implement parseDuration in parse-duration.js`
-- `/skill tdd --runner "node --test" reproduce and fix token expiration bug`
-- `/skill tdd --test-file tests/cart.test.ts checkout cart calculation`
-
-### Options
-- `--runner <command>`: The test runner command to execute (e.g., `node --test`, `npm test`, `pytest`, `cargo test`). If omitted, inspects `package.json`, project configuration, or existing test files.
-- `--file <path>`: The target implementation source file to create or update.
-- `--test-file <path>`: The target test file to create or update.
-
-### Remaining text
-- Everything after the options is the feature specification or bug
-  description. If it names the seam already, that is the seam; do not ask
-  again.
-
-The two steps below are the plan; do not open a task list for them.
-
-## Step 1 — Agree the seams
-
-A seam is the public boundary you test at, observing behavior without
-reaching inside (e.g. exported functions, class methods, or CLI interfaces). Before writing any test:
-
-1. Read the project's instruction file and inspect existing tests/runner configuration (`package.json`, `Makefile`, etc.) so naming, test runner, and test conventions match the host project.
-2. Formulate the public seam under test:
-   - Target function or module name
-   - Input arguments and expected return types
-   - Edge case and error behaviors
-3. **Headless / Autonomous Fallback**: If running headlessly or if seams are specified in the prompt or clearly evident from module exports, state the agreed seam explicitly in your response (e.g. `Seam agreed: parseDuration(str) -> number | null`) and proceed immediately to Step 2 without waiting for an interactive prompt. When interacting with an operator, confirm the proposed seam before writing code.
-
-No test is written at an unconfirmed or unstated seam. Agreeing seams up front keeps the effort focused on critical public paths rather than internal details.
-
-## Step 2 — The loop (Strict Vertical Slices)
-
-Execute one vertical slice per cycle: exactly one test behavior → minimal implementation → verify.
-
-### Cycle Rules:
-1. **Red**:
-   - Write or append **EXACTLY ONE** test case (`test(...)` or `it(...)`) for the thinnest unverified slice of behavior.
-   - Double-check expected literal values and arithmetic beforehand to avoid tautological or mathematically flawed assertions.
-   - Run the test suite directly via `bash` (e.g. `node --test test/parse-duration.test.js`).
-   - Observe it fail for the expected reason (e.g. function not defined, or assertion difference).
-   - If the test passes immediately on the first run, the test verified nothing: fix the test before proceeding.
-2. **Green**:
-   - Write or edit **ONLY** enough implementation code to make that failing test pass.
-   - Do not write speculative helpers, future error checks, or unrequested features.
-   - Run the test runner again. Confirm that the test now passes.
-3. **Repeat**:
-   - Move to the next slice of behavior (e.g. next format, edge case, or invalid input), adding one test case at a time.
-   - Keep all previously written tests passing (no regressions).
-
-### Shell Execution Constraints:
-- Never use command substitution `$(...)` or backticks `` ` `` in `bash` commands; execute commands in discrete, direct steps.
-- Avoid complex nested shell pipelines (e.g. `cmd 2>&1 | head -40; echo EXIT: ${PIPESTATUS[0]}`). Run the test runner directly:
-  ```bash
-  node --test <test-file>
-  ```
-  or
-  ```bash
-  npm test
-  ```
-- If the test command cannot execute at all (runner missing, syntax error in test setup, execution blocked), STOP and report the exact failure. Never fabricate test output or assume a test passed without running it.
-
-### Batching and Git Rules:
-- **No Horizontal Slicing**: Do NOT write a large batch of tests (e.g. 5–10 test cases) upfront before writing any implementation. Writing multiple tests at once breaks the red-green feedback loop and creates compound debugging failures on smaller models.
-- **No In-Loop Commits**: Do not run `git commit` or `git add` between cycles. TDD is complete when the suite passes green; repository shipping is handled separately by `ship`.
-
-## Anti-patterns (reject the test, not the code)
-
-- **Horizontal slicing**: Writing a full suite of tests before any implementation exists.
-- **Implementation-coupled**: Mocks internal collaborators, tests private functions, or asserts through side channels. Tell: the test breaks on refactoring while behavior is unchanged.
-- **Tautological**: The assertion recomputes the expected value the same way the code does (`expect(add(a,b)).toBe(a+b)`), so it passes by construction. Expected values must come from independent literals or specification examples.
-- **Mock-everything**: Heavy mocking instead of testing real boundaries. When mocking strategy is in question, consult `references/mocking.md`. For worked examples, consult `references/tests.md`.
-
-## Done when
-
-Every agreed seam has its behaviors covered by tests that were each observed red before green, the full suite passes, and no test trips the anti-patterns above. Output a concise summary naming:
-1. Public seams covered.
-2. Behaviors verified.
-3. Any edge cases or seams deliberately left untested.
-
-## Red flags
-
-- Writing a batch of tests upfront instead of one vertical slice per cycle.
-- An implementation written before the test it claims to satisfy.
-- A test passing green on its initial run without an observed red failure.
-- Changing test assertions to match incorrect code outputs instead of fixing the code.
-- Staging or committing git changes during the TDD loop.
-- Using bash command substitutions `$(...)` that trigger approval modals.