geneseed 4.9.4 → 4.14.0

package/src/skills/_self-improvement.md

@@ -1,10 +1,23 @@
 ## Self-improvement
 
 <!-- LEAN:begin -->
+This {{SKILL}} keeps its own notes in `{{DIR_NOTEBOOK}}/skill-notes/<name>.md`,
+`<name>` being this {{SKILL}}'s name. When that file exists, read it before the
+first step — where it disagrees with this file, the notes win. They are yours to
+write, and no rebuild touches them.
+
 Close each run with one beat of reflection on the {{SKILL}} itself:
 - A step misled, a needed step was missing, or the trigger fired wrongly — that
-  is a flaw in this file. Propose the exact edit (trigger, procedure, or
-  done-when) and apply it with the user's assent ({{LAW:one-intent-one-act}}).
+  is a flaw in this file. Write the exact correction (trigger, procedure, or
+  done-when) into the notes file, with the user's assent ({{LAW:one-intent-one-act}}), as one line:
+  `- [skill|general] <correction> — seen: <what happened, against what you expected> (<date>)`.
+  `seen:` is the evidence the correction is later judged by; `general` marks one
+  that would fix other {{SKILLS}} too. Never
+  edit this file: it is a rendered copy, a rebuild overwrites it, and the doctor
+  reports the edit as drift. `geneseed diff` carries the notes back to the source.
+- Keep the notes sharp: amend or delete a line before adding one — a line with no
+  `seen:`, or whose `seen:` no longer happens, goes first — and prune past about
+  twenty lines.
 - A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
   clears {{DOCTRINE:persist-insight}}'s bar: it would change how a future session behaves, and a
   fresh read of the repo would not re-derive it. Update an existing memory over
@@ -13,7 +26,11 @@ Close each run with one beat of reflection on the {{SKILL}} itself:
   runs end here.
 <!-- LEAN:else -->
 One beat of reflection on this {{SKILL}}: a step that misled, a missing step, or a
-wrong trigger is a flaw in this file — propose the exact edit and apply it with the
-user's assent ({{LAW:one-intent-one-act}}). A lesson that is not about this file goes to {{MEMORY}} only
-if it clears {{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
+wrong trigger is a flaw in this file — write the exact correction, with the user's
+assent ({{LAW:one-intent-one-act}}), into `{{DIR_NOTEBOOK}}/skill-notes/<name>.md` (`<name>` is this {{SKILL}}'s
+name) as `- [skill|general] <correction> — seen: <what happened vs expected> (<date>)`,
+never into this rendered file, which a rebuild overwrites. Read that notes
+file before the first step when it exists; it wins where it disagrees. Keep it short.
+A lesson that is not about this file goes to {{MEMORY}} only if it clears
+{{DOCTRINE:persist-insight}}'s bar. Nothing learned — move on.
 <!-- LEAN:end -->

package/src/skills/brainstorm/builder-check.md

@@ -1,5 +1,7 @@
 # {{SKILL}}: brainstorm — builder check
 
+{{CREDIT:superpowers:skills/brainstorming/builder-check-prompt.md}}
+
 The spec's author cannot read it cold: a re-read inherits the framing that wrote it. So a
 fresh reader does.
 

package/src/skills/brainstorm.md

@@ -3,6 +3,12 @@
 > {{DESC_BRAINSTORM}}
 <!-- aliases: grill-me -->
 
+{{CREDIT:superpowers:skills/brainstorming/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/productivity/grilling/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/productivity/to-questionnaire/SKILL.md}}
+
 **Trigger:** a new feature, behaviour change, or project arrives without a design, or the
 user says "brainstorm", "interview me" or "grill me". Also when goal, scope or success
 criteria are unstated ("let's design this", "clarify this first", "stress-test this plan"),
@@ -23,8 +29,11 @@ the design is skipped.
    libraries) the user wants to own. Existing work decides by default
    ({{DOCTRINE:respect-conventions}}); a choice you take goes in the ledger as **your
    call**, never as agreed. Stop when each is unambiguous. Facts are yours to find (read
-   the code, dispatch a subagent), never the user's. A decision someone else owns gets a drafted
-   `questionnaire-<slug>.md` for them — ask the user only who and what they need back.
+   the code, dispatch a subagent), never the user's; a pending lookup holds back only the
+   questions that depend on it. A decision someone else owns gets a drafted
+   `questionnaire-<slug>.md` for them — ask the user only who and what they need back. Most
+   important first (async gets one pass), one idea per question with an empty answer stub
+   under it, and say "I don't know" is a useful answer.
 3. **Ledger the decisions.** Name every KEY DECISION the answers imply or leave open —
    direction chosen, trade-offs accepted, load-bearing constraints, assumptions,
    non-goals. Surface each silent assumption as a decision to ratify, not a settled

package/src/skills/codebase-design.md

@@ -3,6 +3,10 @@
 > {{DESC_CODEBASE_DESIGN}}
 <!-- aliases: domain-modeling -->
 
+{{CREDIT:mattpocock-skills:skills/engineering/codebase-design/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/engineering/domain-modeling/SKILL.md}}
+
 **Trigger:** the user asks "where should the seam go", how to make a module testable through
 its interface, or for a glossary term or ADR. Also designing or reshaping a module's interface,
 a design talk that keeps stumbling over ambiguous terms, or another {{SKILL}} needing this vocabulary.
@@ -12,7 +16,8 @@ a design talk that keeps stumbling over ambiguous terms, or another {{SKILL}} ne
    `GLOSSARY-MAP.md` means several contexts — find the one in play) and the
    area's ADRs in `docs/adr/`; use their terms verbatim in code, tests, prose.
    When the user says how something works, check the code agrees; surface any
-   contradiction.
+   contradiction. An ADR is settled: a proposal that contradicts one says so,
+   and why the friction justifies reopening it — never silently.
 2. Use this vocabulary exactly — **module** (anything with an interface and an
    implementation, any scale), **interface** (all a caller must know: types,
    invariants, ordering, error modes, performance), **depth** (behaviour per
@@ -21,7 +26,10 @@ a design talk that keeps stumbling over ambiguous terms, or another {{SKILL}} ne
    "component", "service", "API", "boundary".
 3. Aim for **deep modules** — much behaviour behind a small interface: callers
    get leverage, maintainers get locality. To find what to deepen, start from
-   `git log` hot spots — what keeps changing.
+   `git log` hot spots — what keeps changing. Design a new or reshaped interface
+   twice before choosing: 2–3 radically different shapes (in parallel subagents
+   where the host runs them), compared on depth, locality and seam placement;
+   recommend one — a hybrid if parts combine — never a menu.
 4. Seams sparingly: the interface is the test surface. Internal seams for the
    module's own tests are fine but never exposed; a test that must reach past
    the interface means the wrong shape. One adapter is a hypothesis; a second

package/src/skills/daydream/VENDOR.md

@@ -5,14 +5,14 @@ skill. It rides along in the rendered bundle and is exempt from Geneseed's autho
 gates (token, dead-link, hermeticity, skill counts) — it is listed in the
 generator's `VENDORED_SKILL_DIRS`.
 
-- **Upstream:** https://github.com/glebis/claude-skills/tree/main/daydream
-- **Commit:** f47170dee300dd3d5da2a1c3c708986faeea3d5a
-- **Author:** Gleb Kalinin
-- **License:** MIT (declared in `.claude-plugin/plugin.json`). The text is in `LICENSE`,
-  copied from upstream's root `LICENSE` as added in 93677f479f40ab43520883e7a6c954b755ab39ef
-  (the pinned commit predates the file; its copyright line covers 2025-2026).
+- **Upstream key:** daydream (repo, pinned commit, author and licence: `src/upstreams.json`)
+- **Credit:** {{CREDIT:daydream:daydream}}
 - **Inspired by:** Gwern's [LLM Daydreaming](https://gwern.net/ai-daydreaming)
 
+The licence (MIT, declared upstream in `.claude-plugin/plugin.json`) is in `LICENSE`, copied
+from upstream's root `LICENSE` as added in 93677f479f40ab43520883e7a6c954b755ab39ef (the
+pinned commit predates the file; its copyright line covers 2025-2026).
+
 ## Geneseed adaptation
 
 Vault resolution is adapted to read the harness's `geneseed-wiki.jsonc` knowledge-base
@@ -32,7 +32,7 @@ does not tell the model where a skill lives.
 
 To update, re-copy the upstream folder, re-apply the geneseed-wiki.jsonc adaptation, the
 frontmatter and the placeholder paths in `SKILL.md` / `instructions.md`, and
-bump the commit above.
+bump the `daydream` entry's `commit` in `src/upstreams.json`.
 
 `SKILL.md`'s frontmatter also carries `disable-model-invocation: true`, which upstream lacks: the
 skill is user-only (`/daydream`), so its description stays out of the model's always-on catalogue —

package/src/skills/debug.md

@@ -3,6 +3,10 @@
 > {{DESC_DEBUG}}
 <!-- aliases: ci-fix -->
 
+{{CREDIT:superpowers:skills/systematic-debugging/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/engineering/diagnosing-bugs/SKILL.md}}
+
 **Trigger:** a test fails, code crashes or prints a stack trace, or returns the wrong result — load this FIRST. Load it before reading code or investigating, not only before proposing a fix. Also when a CI run, pipeline job or pre-merge check is red ("CI is failing", "fix the build") — then start with the CI branch.
 
 **No fix without a root cause.** A change you cannot tie to a cause you understand is
@@ -12,7 +16,7 @@ The pressure to skip straight to a patch is highest exactly when this rule matte
 faster than thrashing; do not trade it away under pressure.
 
 ## Procedure
-1. **Build one command that goes red on *this* bug** before reading code for a theory. It asserts the user's exact symptom (not "didn't crash"), gives the same verdict every run, takes seconds and runs unattended; run it and show the output. Read the error and stack trace in full. For a flaky bug, raise the reproduction rate until it is debuggable. If you cannot build it, say so, list what you tried and ask for access or a captured artifact — no command, no hypothesis. Read `GLOSSARY.md` (or `CONTEXT.md`) and the ADRs in the area for the domain's vocabulary.
+1. **Build one command that goes red on *this* bug** before reading code for a theory. It asserts the user's exact symptom (not "didn't crash"), gives the same verdict every run, takes seconds and runs unattended; run it and show the output. If you forced the red by mutating code or a fixture, `diff` against a pristine copy to prove the mutation landed, then revert it. Read the error and stack trace in full. For a flaky bug, raise the reproduction rate until it is debuggable. If you cannot build it, say so, list what you tried and ask for access or a captured artifact — no command, no hypothesis. Read `GLOSSARY.md` (or `CONTEXT.md`) and the ADRs in the area for the domain's vocabulary.
 2. **Minimise, then isolate.** Cut inputs and steps one at a time until every remaining element is load-bearing. Then binary-search the cause — the code path, or for a regression the commit range with `git bisect` (the [git-history {{SKILL}}](git-history.md) carries the method). Change one variable at a time. Find the nearest working twin (a passing sibling test, the last green commit, the same call elsewhere) and list every difference, however small. For a bad value deep in the stack, trace it back caller by caller to where it was born, and fix there. In a multi-layer system (CI → build → sign, API → service → DB), instrument each boundary once to see *which* layer breaks before investigating inside it. For a performance regression, take a baseline measurement and bisect; don't log.
 3. **Rank 3–5 falsifiable hypotheses** ("if X is the cause, changing Y removes the bug") — list them in your reply, then test the top one without waiting. Cite the evidence for each as `file:line` or the exact log line. Proceed only on one that explains ALL the evidence — else gather more evidence, don't guess.
 4. Apply the smallest fix that addresses the root cause, not the symptom; resist fixing things the evidence doesn't implicate ({{LAW:one-intent-one-act}}). One change at a time — no bundled "while I'm here" edits.
@@ -24,6 +28,6 @@ faster than thrashing; do not trade it away under pressure.
 **CI branch (a red run)** → read [debug/ci.md](debug/ci.md) and follow it.
 
 ## Done when
-- The failure is reproduced by a command that went red on it, root-caused, fixed at the cause, and that command passes with no new breakage; every tagged probe is gone.
+- The failure is reproduced by a command that went red on it, root-caused, fixed at the cause, and that command passes with no new breakage; every tagged probe is gone, and the step-1 repro is deleted or kept as the regression test.
 
 <!-- INCLUDE: skills/_self-improvement.md -->

package/src/skills/develop.md

@@ -2,6 +2,8 @@
 
 > {{DESC_DEVELOP}}
 
+{{CREDIT:mattpocock-skills:skills/engineering/tdd/SKILL.md}}
+
 **Trigger:** implementing a feature, fixing a bug, or changing code behaviour in a
 repo that has (or should have) a test suite — before writing implementation code.
 Covers both the test-first cycle (red → green → refactor) and the cover-alongside
@@ -31,7 +33,7 @@ case where the seam is only known once the change is made.
      change ({{DOCTRINE:cover-and-verify}}), then break the implementation on purpose once to
      see the test go red before trusting it.
 4. Write the minimum code that makes it pass; add nothing the test doesn't demand.
-5. Run the *affected* tests and read the output ({{LAW:verify-before-asserting}}); on failure fix the
+5. Run the *affected* tests, and the typecheck where the project has one, and read the output ({{LAW:verify-before-asserting}}); on failure fix the
    cause, never mask it ({{LAW:cure-the-cause}}). Dispatch the
    [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage,
    or when the blast radius is unclear.
@@ -48,7 +50,9 @@ case where the seam is only known once the change is made.
 ## Anti-patterns — name the one you catch
 - **Implementation-coupled** — mocks an internal collaborator, tests a private method,
   or checks through a side channel (querying the database instead of the interface).
-  The tell: it breaks on a refactor that changed no behaviour.
+  The tell: it breaks on a refactor that changed no behaviour. Mock only at system
+  boundaries — external APIs, time, randomness, sometimes the database or filesystem —
+  passed in rather than built inside; never a module you control.
 - **Tautological** — the expected value is recomputed the way the code computes it, so
   the test passes by construction and can never disagree with the code.
 - **Horizontal slicing** — all the tests first, then all the code: the tests pin an

package/src/skills/geneseed-code-review.md

@@ -2,6 +2,10 @@
 
 > {{DESC_CODE_REVIEW}}
 
+{{CREDIT:mattpocock-skills:skills/engineering/code-review/SKILL.md}}
+
+{{CREDIT:superpowers:skills/requesting-code-review/code-reviewer.md}}
+
 **Trigger:** reviewing changes before merge, or the user asks for a review — including "roast my code": same passes, findings unsoftened. Critiquing the user's own ask or plan is [roast-me](roast-me.md).
 
 ## Procedure
@@ -22,8 +26,8 @@
    kept apart, one axis's findings never mask the other's.
 5. Pass 1 — correctness: logic errors, edge cases, error handling, race
    conditions. Verify suspect behaviour by running tests, not by assuming.
-6. Pass 2 — quality: after `REVIEW.md`, the repo's documented standards (`CODING_STANDARDS.md`,
-   `CONTRIBUTING.md`) override. Then, as judgement calls and skipping what tooling enforces:
+6. Pass 2 — quality: after `REVIEW.md`, the repo's documented standards override: search the repo for every file that states how code
+   is written (`CODING_STANDARDS.md`, `CONTRIBUTING.md`, style or conventions docs), not one fixed path. Then, as judgement calls and skipping what tooling enforces:
    mysterious name, duplication, feature envy, data clumps, primitive obsession, repeated switches, shotgun surgery, divergent change, speculative generality, message chains, middle man, refused bequest, dead code, units that do too much.
 7. Pass 3 — spec fidelity: flag anything asked for but missing, present but never
    asked for, or implemented wrong — quoting the spec line for each. Where the spec is silent,

package/src/skills/git-history.md

@@ -3,6 +3,8 @@
 > {{DESC_GIT_HISTORY}}
 <!-- aliases: git-archaeology, git-rescue -->
 
+{{CREDIT:mattpocock-skills-frozen:skills/engineering/resolving-merge-conflicts/SKILL.md}}
+
 **Trigger:** something must be learned *from* the git history, or it needs repair.
 Learn: when a regression came in, who last touched a line and why, where a symbol or
 string entered. Repair: lost commits, a rebase/merge/reset gone wrong, a detached HEAD, a

package/src/skills/handoff.md

@@ -2,6 +2,8 @@
 
 > {{DESC_HANDOFF}}
 
+{{CREDIT:mattpocock-skills:skills/productivity/handoff/SKILL.md}}
+
 **Trigger:** the context window is filling, a session is ending mid-task, or work is passing to another agent or developer.
 
 ## Procedure
@@ -9,7 +11,7 @@
 2. Record open decisions, dead ends already ruled out, blockers, and any irreversible changes already made ({{DOCTRINE:plan-before-acting}}) — so the next agent neither re-derives nor repeats them.
 3. Promote any durable fact or correction learned this session into {{MEMORY}} (§5), not just the worklog.
 4. Point to the live artifacts: branch name, changed files, how to run the tests, and where any failure reproduces. Link specs, plans, ADRs, issues and commits by path or URL — never copy them in.
-5. Put a one-line "resume here" pointer at the top so a fresh context picks up in a single read ({{DOCTRINE:context-economy}}), and list the {{SKILL}}s the next agent should load.
+5. Put a one-line "resume here" pointer at the top so a fresh context picks up in a single read ({{DOCTRINE:context-economy}}), and list the {{SKILL}}s the next agent should load. When the user names what the next session is for, write toward that focus.
 6. Redact keys, passwords and PII ({{LAW:sealed-secrets}}).
 7. Verify it: re-read the worklog as a cold reader ({{LAW:verify-before-asserting}}) — goal, progress, next step, and blockers must be answerable from it alone. Fix what isn't.
 

package/src/skills/learn-mode.md

@@ -4,6 +4,8 @@
 
 <!-- invocation: user -->
 
+{{CREDIT:vibe-wise:skills/learn/behavior.md}}
+
 **Trigger:** the user wants to *learn while building* rather than be handed finished code.
 Phrases: "learn mode", "turn on learning", "I want to understand what we build", "let me design it,
 you write it". Also "pause learning" / "resume learning" / "stop learn mode". To be taught a
@@ -11,8 +13,7 @@ topic outside a build, use the [teach {{SKILL}}](teach.md); to have knowledge te
 [quiz {{SKILL}}](quiz.md).
 
 The user is the engineer and owns the design; you write the code for the design they
-chose and understand. Learning and the user's control outrank build speed. The idea comes
-from [VibeWise](https://github.com/nykooi1/vibe-wise) (MIT); this is a rewrite, not a copy.
+chose and understand. Learning and the user's control outrank build speed.
 
 ## State — `.geneseed/learn.md`
 

package/src/skills/parallel-agents.md

@@ -2,6 +2,10 @@
 
 > {{DESC_PARALLEL_AGENTS}}
 
+{{CREDIT:superpowers:skills/subagent-driven-development/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/engineering/implement-spec/SKILL.md}}
+
 **Trigger:** two or more independent subtasks with no shared state or ordering between them — and a tool that can run subagents. The units run side by side and never see each other's work; when one agent must build on what the previous one produced, that is a relay — use [pipeline](pipeline.md).
 
 ## Procedure
@@ -10,7 +14,7 @@
 3. Dispatch each unit to its own subagent in one batch, each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (no commit/push — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
 4. Keep the main context lean: collect each subagent's distilled result, not its working transcript.
 5. Converge: compare each unit's changed files against its write set and against its siblings' — an edit outside the set, a file two units touched, or a file in a batch's set that never changed is a conflict you resolve before anything else — apply the shared-file rows yourself, then verify the combined outcome. A conflict or ambiguity between the plan, the findings and the code is yours to decide: decide it, record `Ruling: <choice> — <why> — <cost if wrong>` in the worklog, and continue. Stop only for what {{LAW:echo-the-intent}}, {{LAW:deletion-is-deliberate}} or {{DOCTRINE:consent-before-push}} names; every ruling goes in the final report ({{DOCTRINE:declare-the-judgment-calls}}).
-6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once. When the plan names a `Spec:`, every slice reads it once; the spec outranks the plan where they conflict. Record BASE before dispatch; before re-running the proof, confirm the branch descends from BASE and the diff is non-empty — an empty diff is a failure, not a clean result. Never diff against `HEAD~1`.
+6. **A plan with blocking edges.** To build a [plan](plan.md) file's slices — each with its `Blocked by:` line — in one run, dispatch every unblocked slice on its own branch off one integration branch, merge each into it as it returns (each merge is a commit — {{DOCTRINE:consent-before-push}} stays with you), and recompute the unblocked set from the plan after every merge — newly freed slices go out at once. When the plan names a `Spec:`, every slice reads it once; the spec outranks the plan where they conflict. Each slice branches off the integration tip at its own dispatch (its BASE) and merges the current tip back into its branch before returning, so a conflict with a sibling resolves on the slice's branch; before re-running the proof, confirm the branch descends from BASE and the diff is non-empty — an empty diff is a failure, not a clean result. Never diff against `HEAD~1`. When the plan is exhausted, review the integration branch whole with [geneseed-code-review](geneseed-code-review.md) before reporting.
 
 ## Done when
 - Independent units ran concurrently, each returned a distilled result, and the reconciled outcome is verified.

package/src/skills/pipeline.md

@@ -2,6 +2,8 @@
 
 > {{DESC_PIPELINE}}
 
+{{CREDIT:superpowers:skills/subagent-driven-development/SKILL.md}}
+
 **Trigger:** [foreman mode](../modes/foreman.md) routes a triaged *substantial* task here; also directly invocable without that mode whenever the user asks to "run a pipeline" for a development, documentation, research, or review task. The crew is a relay, not a fan-out: its agents take turns in one worktree, each handed what the previous one produced — for independent subtasks run side by side, use [parallel-agents](parallel-agents.md).
 
 ## What it is

package/src/skills/plan.md

@@ -2,6 +2,10 @@
 
 > {{DESC_PLAN}}
 
+{{CREDIT:superpowers:skills/writing-plans/SKILL.md}}
+
+{{CREDIT:mattpocock-skills:skills/engineering/to-tickets/SKILL.md}}
+
 **Trigger:** a task with more than a couple of steps, or touching several files
 ({{DOCTRINE:plan-before-acting}}).
 
@@ -16,10 +20,13 @@
    which the work can be verified and reviewed. Cut the steps as **vertical slices** —
    thin end-to-end pieces, each green and verifiable on its own, never one horizontal
    layer at a time — and give each a `Blocked by:` line naming the slices it waits on
-   (`none` when it can start now). Sequence a wide refactor as expand → migrate
+   (`none` when it can start now). Size each slice to finish in one fresh context. When the
+   code fights the change, the first slice is a prefactor, behaviour unchanged, that makes
+   the change easy. Sequence a wide refactor as expand → migrate
    callers in batches → contract, so every slice leaves the build green. A step records
    decisions, not code: the files, the exact signatures and the spec's values, the test
-   that proves it, and the check command. Write a body only for an algorithm those leave
+   that proves it (through an existing seam, as high as possible; a new seam is a decision,
+   named as one), and the check command. Write a body only for an algorithm those leave
    open; a plan longer than the code it describes has written the code, and "TBD",
    "handle edge cases" or "add tests" decide nothing. The file's first line names the
    task or branch, then `Spec: <path>` when a spec exists — the spec outranks the plan

package/src/skills/prototype.md

@@ -2,6 +2,8 @@
 
 > {{DESC_PROTOTYPE}}
 
+{{CREDIT:mattpocock-skills:skills/engineering/prototype/SKILL.md}}
+
 **Trigger:** a design question needs a runnable answer — "does this state
 model feel right?" or "what should this look like?" — before committing to a
 real implementation.
@@ -18,14 +20,16 @@ real implementation.
    state the assumption.
 2. Throwaway from day one, and marked as such: place it near the code it
    prototypes for, but name it so a casual reader sees it is not production.
-   No persistence (state lives in memory), no tests, no error handling beyond
+   No persistence (state lives in memory) and no real mutations (a variant that must
+   write hits a stub), no tests, no error handling beyond
    what makes it runnable, no abstractions ({{DOCTRINE:smallest-viable-diff}}).
 3. One command to run, using the project's existing task runner — the user
    must be able to start it without thinking.
 4. Surface the full relevant state after every action or variant switch, so
    the user sees exactly what changed.
 5. When the question is answered: fold the validated decision (and a logic
-   prototype's pure module) into the real code, record the verdict and the
+   prototype's pure module) into the real code (a winning UI variant is rewritten to production standard, never
+   promoted as-is), record the verdict and the
    question it settled (issue comment, ADR, or commit message), park the prototype on a throwaway branch, and keep the
    main branch clean of prototype code.
 

package/src/skills/react/a11y.md

@@ -0,0 +1,33 @@
+# {{SKILL}}: react — accessibility
+
+{{CREDIT:everything-claude-code:skills/frontend-a11y/SKILL.md}}
+
+Accessibility for React components: what to write, and what the reviewer will refuse.
+
+## Semantic HTML first
+- A clickable thing is a `<button>` (an action) or an `<a href>` (navigation). `<div onClick>` is not keyboard-reachable and has no role; do not add `role` and `tabIndex` to make it one.
+- One `<main>`, landmarks (`<nav>`, `<header>`, `<footer>`), headings in order without skipped levels.
+- `<img>` always has `alt`: a description for content, `alt=""` for decoration. An icon-only button has `aria-label`.
+
+## Forms
+- Every input has a label: `<label htmlFor={id}>` with `useId()` for the id, or `aria-label` when the label is visual only.
+- Required fields carry `required` (or `aria-required`), not only a red asterisk.
+- An error is linked with `aria-describedby`, flags the field `aria-invalid="true"`, and is announced (`role="alert"` on the message). Never signal an error by colour alone.
+- Use a real `<form>` with `onSubmit` so Enter submits; inputs have a `name`.
+
+## Dynamic content
+- A status that changes without focus moving (saved, loading, results count) sits in an `aria-live="polite"` region that is present before its text changes.
+- A disclosure (accordion, dropdown) toggles `aria-expanded` on its trigger and points `aria-controls` at the panel.
+
+## Keyboard and focus
+- Every interaction works with Tab, Shift+Tab, Enter, Space and Escape. A custom widget (menu, listbox, tabs) follows the WAI-ARIA Authoring Practices pattern for it, arrow keys included; prefer the project's component library over hand-rolling one.
+- A modal moves focus into itself on open, traps it, closes on Escape and returns focus to the trigger on close. The native `<dialog>` with `showModal()` does most of this.
+- On a client-side route change, move focus to the new page's heading or main region.
+- Never remove the focus outline without a visible replacement (`:focus-visible`).
+
+## Motion
+Respect `prefers-reduced-motion`: disable or shorten non-essential animation under it.
+
+## Checking
+- `eslint-plugin-jsx-a11y` in the lint config.
+- `jest-axe` in component tests for interactive components (react-testing skill). jsdom has no layout, so contrast and focus-visible need a real browser check.

package/src/skills/react/vite.md

@@ -0,0 +1,35 @@
+# {{SKILL}}: react — Vite
+
+{{CREDIT:everything-claude-code:skills/vite-patterns/SKILL.md}}
+
+Configuration, environment variables and build failures for a React app on Vite. Check the Vite major in `package.json` before reaching for an option; config keys move between majors.
+
+## Config
+- One `vite.config.ts` (or `.js`) with `defineConfig`. React support is `@vitejs/plugin-react` or `@vitejs/plugin-react-swc`; keep whichever the project has.
+- Path aliases are declared twice: `resolve.alias` in the Vite config and `paths` in `tsconfig.json` / `jsconfig.json` (or the `vite-tsconfig-paths` plugin reads the second). Jest needs a third copy in `moduleNameMapper` (react-testing skill).
+- Dev API calls go through `server.proxy` (`'/api': { target: 'http://localhost:8080', changeOrigin: true }`), not a hard-coded backend URL in the code.
+
+## Environment variables
+- Client code reads `import.meta.env.VITE_*`. Only `VITE_`-prefixed variables reach the bundle, and they are inlined at build time: changing one means rebuilding, and every value is public.
+- `process.env` does not exist in client code; do not add a polyfill to make it work.
+- `.env.local` and `.env.*.local` stay out of git. A per-environment value that must change without a rebuild comes from a runtime config file (`/config.json`) fetched at start, not from `VITE_*`.
+- TypeScript: declare the variables in `src/vite-env.d.ts` (`interface ImportMetaEnv { readonly VITE_API_URL: string }`).
+
+## Type and lint checks
+`vite build` transpiles but never type-checks. Keep `tsc --noEmit` (or `tsc -b`) in the build script or CI, and ESLint with `eslint-plugin-react-hooks` (`rules-of-hooks`, `exhaustive-deps`) and `eslint-plugin-jsx-a11y`.
+
+## Build failures
+Run the project's own `build` script, read the first error, fix only that, rebuild. One error at a time.
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Invalid hook call` | Two copies of React | `npm ls react` must show one; dedupe with `overrides` in `package.json` |
+| `Element type is invalid ... got: undefined` | Default vs named import mismatch | Match the import to the component's export |
+| `Cannot find module 'react'` types (TS) | `@types/react` missing or a different major than `react` | Install the matching `@types/react` and `@types/react-dom` |
+| `Failed to resolve import "@/..."` | Alias in tsconfig but not in Vite | Add it to `resolve.alias` or use `vite-tsconfig-paths` |
+| `require is not defined` / CJS-only dependency errors | CommonJS dependency in the ESM pipeline | Add it to `optimizeDeps.include`; prefer an ESM build of the library |
+| Works in `vite dev`, broken after `vite build` | Dev serves unbundled modules | Reproduce with `vite build && vite preview`, not dev |
+| Blank page or 404 on assets after deploy | App served from a sub-path | Set `base` to that path |
+| Old chunk 404 after a deploy | Browser holds the previous `index.html` | Serve `index.html` with `Cache-Control: no-cache`; hashed assets can stay immutable |
+
+Never silence a build or type error with `// @ts-ignore`, `any` or a disabled lint rule; fix the cause or stop and report it.

package/src/skills/react/webpack.md

@@ -0,0 +1,40 @@
+# {{SKILL}}: react — webpack
+
+Configuration, client-side routing, environment variables and build failures for a React app on webpack. Check the webpack major in `package.json` first: webpack 5 removed the Node core-module polyfills and the `process` global that 4 shipped, and most config questions turn on that.
+
+## Config
+- The config is `webpack.config.*`, often split into `common`/`dev`/`prod` files joined with `webpack-merge`; edit the file the setting belongs to, not the merged result. Read the `build` and `start` scripts to see which file each loads.
+- JSX and TypeScript go through `babel-loader` (`@babel/preset-react` with `runtime: 'automatic'`, `@babel/preset-typescript`), `ts-loader` or `swc-loader`; keep whichever the project has. A loader rule's `test` must match `.jsx`/`.tsx`, and `resolve.extensions` must list them.
+- Path aliases are declared twice: `resolve.alias` in the webpack config and `paths` in `tsconfig.json` / `jsconfig.json` (or `tsconfig-paths-webpack-plugin` reads the second). Jest needs a third copy in `moduleNameMapper` (react-testing skill).
+
+## Client-side routing
+- With `BrowserRouter` (or any history-API router), the dev server needs `devServer.historyApiFallback: true`, or a refresh on `/users/42` is a 404. The production server needs the same fallback to `index.html`; that is server config, not webpack.
+- Set `output.publicPath` to `'/'` (or the deploy sub-path). A relative public path makes chunks load from `/users/main.js` on a nested route.
+- Split per route with `React.lazy(() => import('./pages/Users'))`; webpack turns each dynamic `import()` into its own chunk. Do not add an entry point per route to a single-page app.
+- Dev API calls go through `devServer.proxy`, not a hard-coded backend URL in the code.
+
+## Environment variables
+- `process.env.X` in client code is not read at runtime: `DefinePlugin`, `EnvironmentPlugin` or `dotenv-webpack` replaces it with a literal at build time. Changing one means rebuilding, and every value is public. `mode` sets `process.env.NODE_ENV`.
+- On webpack 5 an undefined `process.env.X` is `process is not defined` at runtime. Define the variable; do not add a `process` polyfill through `ProvidePlugin`.
+- `.env.local` stays out of git. A per-environment value that must change without a rebuild comes from a runtime config file (`/config.json`) fetched at start.
+
+## Type and lint checks
+`babel-loader`, `swc-loader` and `ts-loader` with `transpileOnly` never type-check. Keep `tsc --noEmit` in the build script or CI (or `fork-ts-checker-webpack-plugin`), and ESLint with `eslint-plugin-react-hooks` and `eslint-plugin-jsx-a11y`.
+
+## Build failures
+Run the project's own `build` script, read the first error, fix only that, rebuild. One error at a time.
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Invalid hook call` | Two copies of React | `npm ls react` must show one; dedupe with `overrides`, or `resolve.alias` `react` to one path for a linked package. Module Federation: `shared: { react: { singleton: true }, 'react-dom': { singleton: true } }` |
+| `Module not found: Can't resolve '@/...'` | Alias in tsconfig but not in webpack | Add it to `resolve.alias` |
+| `Can't resolve './Button'` for a `.tsx` file | Extension not resolved | Add `.tsx`/`.jsx` to `resolve.extensions` |
+| `Module parse failed: Unexpected token` on JSX | No loader matched the file | Widen the rule's `test`, or narrow an `exclude` that drops the folder |
+| `BREAKING CHANGE: webpack < 5 used to include polyfills` | A dependency imports a Node core module | Prefer a browser build of the dependency; otherwise `resolve.fallback` with a named polyfill package |
+| `process is not defined` | `process.env.X` not defined at build time | Add it to `DefinePlugin` / `EnvironmentPlugin` |
+| 404 on refresh of a deep link | No history fallback | `devServer.historyApiFallback: true`, and the same fallback on the production server |
+| Blank page on a nested route, chunk 404s | Relative `output.publicPath` | Set `output.publicPath: '/'` or the deploy sub-path |
+| Works with `start`, broken after `build` | Dev and production configs differ | Build with `mode: 'production'` and serve `dist/` with a static server to reproduce |
+| `ChunkLoadError` after a deploy | Browser holds the previous `index.html` | `[contenthash]` in chunk names, and serve `index.html` with `Cache-Control: no-cache` |
+
+Never silence a build or type error with `// @ts-ignore`, `any` or a disabled lint rule; fix the cause or stop and report it.

package/src/skills/react-testing.md

@@ -0,0 +1,68 @@
+# {{SKILL}}: react-testing
+
+> {{DESC_REACT_TESTING}}
+
+{{CREDIT:everything-claude-code:skills/react-testing/SKILL.md}}
+
+**Trigger:** writing or fixing tests for React components, hooks or pages in a Vite or webpack project tested with Jest and React Testing Library, in TypeScript or JavaScript; or getting Jest to run at all against bundler-shaped code. React-specific; core test discipline lives in the develop skill. End-to-end flows across pages belong to the project's browser tests (Playwright, Cypress), not here.
+
+Target stack: Jest, `@testing-library/react`, `@testing-library/user-event`, `@testing-library/jest-dom`, MSW for network mocks, `jest-axe`.
+
+## What a test does
+Render the component with the providers it has in production, act through `userEvent` the way a user would, assert what the user sees or what leaves the component (a callback called, a request sent). Never assert on internal state, hook calls, props passed to children, or render counts. Never mock React.
+
+## Queries, in this order
+1. `getByRole(..., { name })`, `getByLabelText`: what assistive technology sees. A test that cannot find the button by role has found an accessibility bug.
+2. `getByText`, `getByDisplayValue`, `getByAltText`.
+3. `getByTestId`: last resort.
+
+`getBy*` throws when missing; `queryBy*` returns `null` (assert absence); `findBy*` waits (things that appear after async work). No `container.querySelector`.
+
+## Interaction and async
+```tsx
+test('saves the email', async () => {
+  const user = userEvent.setup();
+  const onSave = jest.fn();
+  render(<EmailForm onSave={onSave} />);
+
+  await user.type(screen.getByLabelText('Email'), 'a@example.com');
+  await user.click(screen.getByRole('button', { name: /save/i }));
+
+  expect(onSave).toHaveBeenCalledWith('a@example.com');
+});
+```
+- `userEvent.setup()` once per test, every call awaited. `fireEvent` only for an event `userEvent` cannot produce.
+- Wait with `findBy*` or `waitFor`; never `setTimeout` or a sleep. With `jest.useFakeTimers()`, pass `userEvent.setup({ advanceTimers: jest.advanceTimersByTime })`.
+- An `act(...)` warning is a real bug (an update after the test ended or an unawaited promise); fix it, do not silence `console.error`.
+
+## Network with MSW
+Mock at the network layer, so the fetch client and the server-state library run as in production. Start the server in the setup file with `onUnhandledRequest: 'error'`, `resetHandlers()` after each test, override per test with `server.use(...)`. Each test covers the error and empty responses, not only success.
+
+## Providers
+One `renderWithProviders` in a test-utils file wraps the router (`MemoryRouter`), the store and the query client. Create a fresh query client per test with `retry: false`, so cache and retries never leak between tests. Hooks: `renderHook` from `@testing-library/react`, with the same wrapper.
+
+## Accessibility
+`expect(await axe(container)).toHaveNoViolations()` (`jest-axe`) on every interactive component. jsdom has no layout: contrast and focus visibility need a browser.
+
+## Jest beside the bundler
+The bundler and Jest resolve code differently; each gap is configured once in `jest.config.*`. Rows marked Vite or webpack apply only to that bundler:
+
+| Gap | Fix |
+|---|---|
+| No DOM | `testEnvironment: 'jsdom'` with `jest-environment-jsdom` installed; with MSW 2 use `jest-fixed-jsdom`, which keeps Node's `fetch` globals |
+| JSX / TS not transformed | `babel-jest` with `@babel/preset-env`, `@babel/preset-react` (`runtime: 'automatic'`), `@babel/preset-typescript`; or `ts-jest` / `@swc/jest`, whichever the project has |
+| Vite: `import.meta.env` is a syntax error | Read env in one module (`src/config/env.ts`) and replace it in tests via `moduleNameMapper` or `jest.mock`; do not scatter `import.meta.env` |
+| Path aliases (`@/...`) | Mirror the bundler's `resolve.alias` in `moduleNameMapper` |
+| webpack: `process.env.X` is `undefined` in tests | Jest does not run `DefinePlugin`; set the values in a `setupFiles` module |
+| webpack: `require.context is not a function` | Jest has no `require.context`; import the modules explicitly, or mock the module that calls it |
+| CSS and asset imports | `identity-obj-proxy` for CSS modules, a file stub for images and SVG |
+| ESM-only package in `node_modules` | Let it through `transformIgnorePatterns: ['node_modules/(?!(pkg-a|pkg-b)/)']` |
+| `toBeInTheDocument` undefined | `import '@testing-library/jest-dom'` in a `setupFilesAfterEnv` file |
+
+## Snapshots
+No snapshots of rendered components: they break on every markup change and get approved unread. Snapshot only a pure data serialiser.
+
+## Done when
+- The new tests fail without the change and pass with it; the project's test script passes, read from real output; no `act` warning, no unhandled MSW request, no skipped test left behind.
+
+<!-- INCLUDE: skills/_self-improvement.md -->