@ikon85/agent-workflow-kit 0.10.0

package/.claude/skills/spec-self-critique/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: spec-self-critique
+description: "Use AFTER writing or editing a spec (a `SPEC.md`/`PLAN.md` or any spec/design doc), BEFORE asking the user to review — runs a 12-point structural Self-Critique checklist, fixes issues inline, and emits a visible summary. Enriches each check from a project layer if one is present. Triggers right after a spec has been written. NOT for reviewing finished code/diffs (code-review) — this pass runs on the spec text itself."
+---
+
+# Spec Self-Critique
+
+A portable, structural self-review pass over a freshly written spec/plan. The **generic 12-point skeleton** below ships as-is; a **project layer** (if present) enriches each point with project-specific incidents, grep patterns, conventions, and extra sub-checks.
+
+## When to invoke
+
+- After a spec was written/edited (a `SPEC.md` / `PLAN.md`, or a spec/design doc), BEFORE the user-review gate.
+
+## Step 0 — Project-layer probe
+
+First, check whether a project layer exists: from the project root, look for `docs/agents/skills/spec-self-critique.md`.
+
+- **Present** → **full pass**: run the 12 generic checks AND apply the per-point enrichment that file defines (incidents, grep patterns, extra sub-checks).
+- **Absent** → **base pass**: run the 12 generic checks only, then add this one-line warning to the summary:
+  > ⚠ No project layer found (`docs/agents/skills/spec-self-critique.md`) — only the generic base checks ran. `/setup-workflow` creates the layer; it fills in project-specific content via `/retro`.
+
+> **Routing — keep this skeleton clean.** Project-specific checks, incidents, and grep patterns belong in the project layer (`docs/agents/skills/spec-self-critique.md`), **NOT here**. `/retro` appends new project-specific lore to the project layer, never into this generic skeleton.
+
+## Altitude — a portable kit concept
+
+The generic skeleton recognizes two spec altitudes: a **Feature-PRD** (the
+default — every point above and below assumes this) and a **Program-PRD**
+(marked `<!-- prd: program -->`, produced by the kit's `scale-check` →
+`grill-with-docs` → `to-prd` program route — a native anchor over a
+multi-wave `## Wellenplan`). This is a **portable kit concept**, not a
+project-specific rule, so it stays **in this generic skeleton** — the
+"project-specific → project layer" routing rule above is about *this
+project's* incidents/grep patterns, not about a kit-wide spec shape the
+skill itself already knows.
+
+Two points read differently at Program-Altitude — both get a dedicated
+fixture in `scenarios.md`:
+
+- **Point 3 (Scope)** at `prd: program`: scope is not "small enough for one
+  plan" — it is "each wave holds 2–7 slices; the program splits via its wave
+  plan, the PRD itself is never split."
+- **Point 12 (Vertical-slice completeness)** at `prd: program`: reads against
+  **Wellenplan rows**, not a slice/PR table — each wave is an outcome
+  cut/tracer, never a layer cut ("a backend wave" is the anti-pattern); an
+  enabler wave names the half it cuts off and the outcome wave that closes it.
+
+Every other point runs unchanged at either altitude.
+
+## How to invoke
+
+Read the most recently written/edited spec in full. Walk the 12-point checklist (points 1–12; **8b/8c are sub-checks of point 8**, not main points). Per point:
+
+1. Decide: does the spec trigger this rule?
+2. If yes: run the check.
+3. If violated: fix the spec inline (Edit tool, not "TODO later").
+4. Note the correction for the summary.
+
+End with a visible summary in the chat:
+
+```
+Self-Critique complete — <N> corrections:
+- Point <X>: <short description>
+- ...
+```
+
+or, if none were needed: `Self-Critique complete — no corrections needed.` (append the Step-0 layer-absent warning if it applied). THEN ask the user-review question.
+
+## The 12-point checklist
+
+**1. Placeholder scan + empirical re-check**
+Scan for `TBD` / `TODO` / "später" / "fill in details" / vague requirements → fix inline. Plus, when applicable:
+- **Cited counts** ("24 call-sites: 6 start, 8 succeed, …") → re-verify each empirically (`grep`); recon from the brainstorming phase can be stale, and wrong numbers mislead the effort estimate.
+- **Folder move / rename** → broaden the caller-audit grep (search the path-segment without a `from …`-anchor, to catch mocks, dynamic imports, type-only imports) AND require a typecheck-backstop step right after the move (path-depth breaks inside the moved files aren't found by a caller grep).
+- **Cited prior diagnosis** (issue body, investigation, memory snapshot, earlier plan) → verify each core claim empirically before finalizing. Such artifacts are hypotheses, not validated facts; drift compounds if left unchecked.
+- **Risk mitigation** → it must name a concretely checkable **output string**, not just an action ("rowCount is 2307" is checkable; "rowCount > 1000" is a claim about a claim).
+Skip only if none of these apply.
+
+**2. Internal consistency**
+Do sections contradict each other? Does the architecture match the feature description? Do numbers/orders agree between tables and prose?
+
+**3. Scope check**
+Small enough for **one** implementation plan, or must it split into sub-specs?
+**At Program-Altitude** (`prd: program`) this reads differently — see
+"Altitude" above: each wave holds 2–7 slices, the program splits via its wave
+plan, and the PRD itself is never split.
+
+**4. Ambiguity check**
+Could a requirement be read two ways? If so, pick one interpretation and make it explicit.
+
+**5. State transitions**
+*Trigger:* the spec mentions "Live", "SSE", "WebSocket", "Polling", "EventSource", "Realtime", "Stream", or incoming updates.
+*Check:* are all transitions played through — `idle → running → awaiting_decision → succeeded | failed` — plus `mid-flight reload`, `multi-tab parallel`, `connection-loss + reconnect`, `aborted`?
+
+**6. Convention scope**
+*Trigger:* the spec introduces a new pattern, convention, single-entry broker, wrapper, or consistency layer.
+*Check:* is it explicitly scoped — applied app-wide vs only touched surfaces? Does the spec require a follow-up item for the untouched surfaces (in the spec body, not retroactively)?
+
+**7. User walk-through**
+*Trigger:* the spec has UI stages, wizards, or multi-step user interactions.
+*Check:* are the sub-steps per UI stage walked through — what does the user see at each stage — not just the data model?
+
+**8. Project-convention check**
+*Trigger:* always.
+*How:* iterate your project's documented conventions. Default location: from the project root, `docs/conventions/*.md`. For each convention file that carries a `## Self-Critique-Check` block (format: **Trigger / Check / Korrektur**):
+1. Evaluate its Trigger against the current spec.
+2. On match: run its Check. On violation: fix the spec inline + note it.
+3. A convention with no such block → skip it non-blocking + collect a warning ("convention `<file>` is missing a `## Self-Critique-Check` block").
+No conventions directory / no blocks (e.g. a fresh project) → **soft skip** (non-blocking). Emit collected warnings at the end of the pass.
+
+**8b. Marker-wording check**
+*Trigger:* a convention mandates a header marker comment.
+*Check:* the spec's marker must be copied **verbatim** from the convention, not paraphrased. Open the convention, compare the marker block 1:1, fix inline on any drift (drift makes the convention worthless as the single source of truth).
+
+**8c. Structurally-trivial post-invariant**
+*Trigger:* the spec has aggregation functions with post-invariants.
+*Check:* for each post-invariant, can it ever fire under the current code path? Play the path through (all branches, all math ranges). If it is structurally impossible to violate under the current code, drop it or replace it with a property test (a property fires on every regression; a structurally-true post never does).
+
+**9. Primitive recon (DRY)**
+*Trigger:* the spec introduces a new UI primitive, hook, component, helper, repo function, or service — OR substantially touches (≥30 LOC) an existing file.
+*Check:* did you `grep`/`ls` for an existing primitive/helper with overlapping responsibility (including in callers/pages, not just component dirs)? If one exists → switch the spec to reuse it. If a pattern is replicated 3+× → require a helper-extraction acceptance-criterion.
+
+**10. User-action feedback**
+*Trigger:* the spec describes a user action (click, submit, import, bulk op, setup run) that triggers a ≥2-step process.
+*Check:* does the spec document, per sub-step, what the user sees on screen — progress, retry/throttle visibility (esp. external APIs or long waits), mode-switch visibility (e.g. bulk → per-item fallback), and a "why is this counter stalled" hint for per-resource paths?
+
+**11. Live-verify bug-plausibility**
+*Trigger:* the spec has a live-verify block with a bug-variant + an expected property failure.
+*Check:* play the bug-variant through — does it actually change the target property (e.g. does it break the asserted ordering/monotonicity)? Is only one direction sharp? If the variant does NOT violate the property, pick a variant that does and fix the spec inline (a wrong variant yields a passing live-verify that catches no real regression).
+
+**12. Vertical-slice completeness**
+*Trigger:* the spec/PRD has a slice/phase table or splits into multiple PRs.
+*Check:*
+- (a) each *user-facing* slice = a tracer bullet "`<user action> → <visible result>`", **not** a layer name ("config UI", "backend resolver");
+- (b) each byte-neutral/infra slice names its **omitted half** + the **closing follow-up slice** (otherwise the connecting path falls between two slices);
+- (c) the first outcome slice after ≥1 prep slice is traced against the code with a concrete value (`grep`/Read), not trusted as "config-driven".
+*Correction:* reword/split a layer-only slice; pull in a new slice for an uncovered half.
+**At Program-Altitude** (`prd: program`), apply (a)–(c) analogously to
+**Wellenplan rows** instead of a slice table — see "Altitude" above: each wave
+is an outcome cut/tracer, never a layer cut, and an enabler wave names both
+the half it omits and the outcome wave that closes it.
+
+**Gate home.** This skill runs **automatically as the mandatory last step of `to-prd`** (on the Draft-PRD) — the visible two-line summary is required **before** the user-review question. The **slice-completeness gate (point 12)** additionally sits in `to-issues`. The skill stays **standalone-callable** for manual spec/PLAN reviews.
+
+## Anti-patterns of this skill
+
+- **"Skipped self-critique because the spec is small"** — it runs on mini-specs too. Cost: 2–3 min; payoff: structural bugs caught in the spec phase.
+- **"Made corrections silently inline, no summary"** — the visible summary is part of acceptance. A silent pass is indistinguishable from a skipped one.
+- **"Improvised what a convention would say"** — if a convention file has no `## Self-Critique-Check` block, skip it non-blocking + collect a warning. Do not invent the rule.
+
+## Verification fixtures
+
+See `scenarios.md` in this skill dir for project-neutral fixtures (one per check) — walk them when refactoring the checklist. If a project layer is present, it may carry richer, project-specific scenarios.

package/.claude/skills/spec-self-critique/scenarios.md

@@ -0,0 +1,82 @@
+# Verification fixtures — spec-self-critique (generic)
+
+**Fixtures only — no new rules here.** Each fragment is a synthetic, project-neutral spec snippet that violates **exactly one** check. When the skill works, it should trigger the named point and name it in the summary. Walk these when refactoring the checklist. New *project-specific* checks/scenarios go in the project layer (`docs/agents/skills/spec-self-critique.md`), never here.
+
+## Point 1 — placeholder / unverified count
+> "Rename `oldUtil` → `newUtil` across the 9 call-sites and update imports."
+
+Violates 1 (cited count not re-verified; rename = caller-audit + typecheck-backstop). Expected: *"Punkt 1: '9 call-sites' nicht empirisch belegt — grep + breiter Caller-Audit + Typecheck-Backstop nach dem Move ergänzt."*
+
+## Point 2 — internal consistency
+> "Section A: the cache TTL is 60s. Section B's diagram labels the same cache 600s."
+
+Violates 2. Expected: *"Punkt 2: widersprüchliche TTL (60s vs 600s) — vereinheitlicht."*
+
+## Point 3 — scope
+> "This spec covers: new auth provider, a billing rewrite, a dashboard redesign, and a data migration."
+
+Violates 3. Expected: *"Punkt 3: zu groß für einen Plan — in Sub-Specs zerlegen."*
+
+## Point 3 (Program-Altitude) — a wave outgrows the band
+> "`<!-- prd: program -->` Program-PRD. Wellenplan: Welle 1 covers 9 slices
+> across two subsystems; Welle 2 covers 3 slices."
+
+Violates 3 at Program-Altitude (a wave over the 2–7 slice band needs
+splitting into two waves; the PRD itself stays unsplit). Expected: *"Punkt 3
+(Programm-Altitude): Welle 1 mit 9 Slices sprengt den 2–7-Rahmen — in zwei
+Wellen aufgeteilt; das PRD selbst bleibt ungesplittet."*
+
+## Point 4 — ambiguity
+> "When the request fails, retry it a few times before giving up."
+
+Violates 4. Expected: *"Punkt 4: 'a few times' mehrdeutig — auf konkrete Zahl + Backoff festgelegt."*
+
+## Point 5 — state transitions
+> "New live progress indicator: on start a spinner appears, on finish a green check."
+
+Violates 5 (only `running → succeeded`). Expected: *"Punkt 5: Live-Feature, nur Erfolgs-Pfad — failed / reload / multi-tab / connection-loss / aborted ergänzt."*
+
+## Point 6 — convention scope
+> "Introduce a `withRetry()` wrapper. Apply it in `serviceA.fetch()` and `serviceB.fetch()`."
+
+Violates 6 (no app-wide-vs-touched scope, no follow-up). Expected: *"Punkt 6: Pattern-Scope nicht erklärt — explizit nur diese 2 + Followup für den Rest."*
+
+## Point 7 — user walk-through
+> "New multi-step onboarding wizard at `/onboarding`. Data model: a 3-field form posted to `/api/onboard`."
+
+Violates 7 (only data model). Expected: *"Punkt 7: kein User-Walk-Through der Wizard-Stufen — pro Stufe ergänzt, was der User sieht."*
+
+## Point 8 — project convention (+ 8b marker, 8c trivial post)
+> "Refactor an aggregation module. Pre-invariant: `typeof rows[0]?.id === 'string'` (already guaranteed by the typed signature). Post-invariant: `out.length === rows.length` where the body is `for (const r of rows) out.push(...)`."
+
+Violates 8c (post structurally guaranteed by the loop) + 8b-style trivial pre. Expected: *"Punkt 8c: Post strukturell durch den Loop garantiert — gestrichen / Property-Test; triviale Pre entfernt."* (With a project layer present, point 8 also iterates that project's `## Self-Critique-Check` convention blocks.)
+
+## Point 9 — primitive recon (DRY)
+> "Build a new `FilterableList` component with sort + filter."
+
+Violates 9 (no recon for an existing list/table primitive). Expected: *"Punkt 9: neues Primitiv ohne DRY-Recon — auf Wiederverwendung des Bestehenden geprüft/umgestellt."*
+
+## Point 10 — user-action feedback
+> "A 'Rebuild caches' button kicks off a 4-stage backend job (~2 min). On error: a toast."
+
+Violates 10 (no per-step feedback). Expected: *"Punkt 10: ≥2-Schritt-Prozess ohne Sub-Step-Feedback — Schritt-Labels / Progress / Retry- bzw. Modus-Sichtbarkeit ergänzt."*
+
+## Point 11 — live-verify bug-plausibility
+> "Live-verify for percentile indices. Bug-variant: change `p80 = 0.8*n` to `0.6*n`. Expect the ordering check `p10 < p50 < p80 < p90` to fire."
+
+Violates 11 (`0.5 < 0.6 < 0.9` stays monotone → property does NOT fire). Expected: *"Punkt 11: Variante erhält die Monotonie — Property feuert nicht; korrekte Variante (z.B. 0.8→0.95, bricht p80>p90) gewählt."*
+
+## Point 12 — vertical-slice completeness
+> "Slices: 1) Config UI · 2) Backend resolver · 3) Wire-up."
+
+Violates 12 (layer names, no tracer-bullet, no traced outcome slice). Expected: *"Punkt 12: Layer-Namen statt Tracer-Bullets — als '<Aktion> → <sichtbares Ergebnis>' umformuliert; erste Outcome-Slice gegen Code getrace't."*
+
+## Point 12 (Program-Altitude) — layer-cut waves
+> "`<!-- prd: program -->` Program-PRD. Wellenplan: Welle 3 — 'Backend-Migration'. Welle 4 — 'Frontend-Rollout'."
+
+Violates 12 at Program-Altitude (layer-cut waves, not outcome tracers; no
+enabler/closing pairing named). Expected: *"Punkt 12 (Programm-Altitude):
+'Backend-Migration'/'Frontend-Rollout' sind Layer-Schnitte, keine
+Outcome-Tracer — Welle 3 als Enabler benannt (abgeschnittene Hälfte:
+sichtbares Frontend-Verhalten) mit Welle 4 als schließender Outcome-Welle,
+oder zu echten Outcome-Wellen umgeschnitten."*

package/.claude/skills/tdd/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+**First, mark the ticket active on the board.** When a ticket was provided (you're on a `feat/<#>-`/`fix/<#>-` branch), run once at TDD pickup:
+
+<!-- mirror-xform:start codex-board-sync-command -->
+```
+python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/sync-board-status.py"
+```
+<!-- mirror-xform:end -->
+
+It parses the issue # from the current branch and moves the board item to the profile's in-progress status (`fields.status.roles.inProgress`; only from the idea/triaged/spec roles, idempotent). No ticket / no parseable branch → it's a silent no-op, so this is safe to run unconditionally. This closes the gap where the SessionStart sync already ran on `main` before the worktree existed, leaving the board stale.
+
+When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+[ ] Wave slice: a flipped/new assumption affecting an unbuilt sibling issue → log it to ANNAHMEN.md (worktree root; wrapup Step 0c reads it)
+```

package/.claude/skills/tdd/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+This skill is adapted from **Matt Pocock's skills**
+(https://github.com/mattpocock/skills), `skills/engineering/tdd` @ d574778, Copyright (c) 2026 Matt Pocock,
+used under the MIT License. Locally adapted (fork-and-own); see PROVENANCE.md.
+
+```
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/.claude/skills/tdd/deep-modules.md

@@ -0,0 +1,33 @@
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/.claude/skills/tdd/interface-design.md

@@ -0,0 +1,31 @@
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup

package/.claude/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/.claude/skills/tdd/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic

package/.claude/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```