geneseed 4.10.0 → 4.15.1

package/src/agents/skeptic.md

@@ -39,11 +39,4 @@ independently.)*
   contract above. Never mechanical proof — this seat runs no commands, so the
   suite and lint results come from the reviewer or tester, not from here.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/spring-boot-engineer.md

@@ -37,12 +37,4 @@ Implements Spring Boot 4 / Java 21+ features, following the spring-boot, spring-
 - Files changed, a one-line summary, and the test command with its result.
 - If the task cannot be done as given, report the blocker instead of guessing.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
-
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/spring-reviewer.md

@@ -38,12 +38,4 @@ Spring-specific review only. Generic correctness, naming and structure belong to
 - Findings as Conventional Comments, `label (decoration): file:line — problem — suggested fix`, most serious first; then a **Set aside:** list (or `none`) and a one-line verdict: any blocking → block, any if-minor and nothing blocking → fix-then-ship, otherwise ship.
 - Name any check that was impossible instead of issuing a verdict on partial evidence.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
-
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/spring-security.md

@@ -39,12 +39,4 @@ Spring Security 7 audit only. The generic audit (injection, secrets, dependencie
 - Findings by severity (critical, high, medium, low), each with `file:line`, the risk and a fix; then a one-line verdict.
 - Name any check that was impossible instead of issuing a verdict on partial evidence.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
-
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/steward.md

@@ -26,11 +26,4 @@
 - A long-term verdict: the structural benefits and risks, the debt this incurs or retires, how reversible it is, and a one-line keep-it-healthy recommendation with the trade-off it accepts.
 - If the change is too small or too reversible to carry long-term stakes, say so and stand down — inflating stakes to justify the seat is its own kind of debt.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/tester.md

@@ -48,11 +48,4 @@ independently.)*
   On failure, findings go back to the developer seat; when the fresh
   developer fails too, the pipeline stops and reports instead of looping again.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/user-advocate.md

@@ -39,11 +39,4 @@ independently.)*
 - **Delivers:** the consumer's verdict, same shape as its own output contract
   above.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/agents/visionary.md

@@ -26,11 +26,4 @@
 - The bold case: the transformative upside in a line, what the motion could become if pushed, the capability it would unlock, and the single bet it depends on. No timid hedging.
 - If the motion genuinely has no bigger version — the ambitious form is just the same thing, larger — say so; a forced 10× pitch is timidity wearing a costume.
 
-## Self-improvement
-
-If this spec misled you — an input you needed but were not given, a boundary
-that proved wrong, a step you could not execute — end your report with one line:
-`spec-feedback: <what failed — the one-line fix>`. Omit it when there is no
-friction. The caller weighs the feedback, folds a real flaw back into this file
-with the user's assent, and records it to {{MEMORY}} only if it clears
-{{DOCTRINE:persist-insight}}'s bar — most reports carry no feedback at all.
+<!-- INCLUDE: agents/_self-improvement.md -->

package/src/doctrines/comms.md

@@ -70,3 +70,24 @@ interfaces first. Genuine forks only, never naming or formatting; trivial work o
 Where {{LAW:echo-the-intent}} checks the goal before, this exposes the choices made during —
 never a call it says to ask about.
 <!-- LEAN:end -->
+
+### {{DOCTRINE:simplified-technical-english}} Simplified Technical English
+<!-- LEAN:begin -->
+Write every prose reply and report in ASD-STE100 Simplified Technical English, the
+controlled language of aerospace maintenance: a tired reader, or one reading a second
+language, gets one meaning on the first read. Code, commands, paths, identifiers and quoted
+output stay as they are. One topic per sentence: at most 20 words in an instruction, 25 in
+a description, six sentences per paragraph. Write an instruction in the imperative, one
+action per sentence, condition first (`If the test fails, read the log.`); a warning comes
+before its step. Use the active voice and simple tenses, no -ing forms, no dropped
+articles. Use one word per meaning, every time: `use`, not `utilize`; `stop`, not
+`terminate`. Project names are technical names and stay. Keep noun clusters to three words.
+In another language, answer in it ({{ONT_CONDUCT}}) and keep these sentence rules; the
+theme keeps its voice, and this rule governs the sentences that carry the content.
+<!-- LEAN:else -->
+Write every prose reply and report in ASD-STE100 Simplified Technical English; code,
+commands, paths and quoted output stay as they are. One topic per sentence: 20 words at
+most in an instruction, 25 in a description. Instructions: imperative, one action each,
+condition first. Active voice, no -ing forms, no dropped articles, one word per meaning
+(`use`, not `utilize`). In another language, keep it and these rules.
+<!-- LEAN:end -->

package/src/kits/react/rules.md

@@ -0,0 +1,13 @@
+### React kit
+
+Applies to React 18 or 19 apps built with Vite or webpack, in TypeScript or JavaScript, tested with Jest and React Testing Library. Read `package.json` first and use only the APIs its React major provides.
+
+- Function components and hooks only. No new class components, except an error boundary where the project has no library for it.
+- Hooks at the top level only. Never disable `react-hooks/rules-of-hooks` or `react-hooks/exhaustive-deps` to make a warning go away.
+- Derive values during render; never copy props or state into state through an effect. Every effect that subscribes cleans up.
+- Server data goes through the project's server-state library, with loading, error and empty states.
+- Keep each folder's language: TypeScript stays typed, with no `any` or `@ts-ignore` to get green; JavaScript stays JavaScript.
+- Env values the bundler inlines (`import.meta.env.VITE_*`, webpack `DefinePlugin`) are public. No secret there, and no session token in `localStorage`.
+- Interactive elements are native (`<button>`, `<a href>`, `<input>` with a label) and keyboard-reachable.
+- Tests query by role or label and act with `userEvent`; the network is mocked with MSW, not by mocking the fetch client.
+- Match the project's existing styling, state library and CI before introducing another.

package/src/kits/react.json

@@ -0,0 +1,18 @@
+{
+  "description": "React on Vite or webpack, in TypeScript or JavaScript, tested with Jest and Testing Library: components, hooks, state, data fetching, accessibility, build and test failures, review.",
+  "skills": ["react", "react-testing"],
+  "agents": ["react-engineer", "react-reviewer"],
+  "rules": "kits/react/rules.md",
+  "rulesWordBudget": 300,
+  "banned": ["ReactDOM.render(", "findDOMNode", "enzyme", "react-test-renderer", "@testing-library/react-hooks"],
+  "catalogue": {
+    "skills": [
+      "| [react]({{DIR_SKILLS}}/react.md) | building or changing React components, hooks, state or data fetching in a Vite or webpack app; bundler config, client-side routing, env variables and build failures; accessibility |",
+      "| [react-testing]({{DIR_SKILLS}}/react-testing.md) | writing or fixing React tests with Jest and Testing Library, MSW network mocks, jest-axe; making Jest run against a Vite or webpack project |"
+    ],
+    "agents": [
+      "| [react-engineer]({{DIR_AGENTS}}/react-engineer.md) | a React component, page, hook or form must be implemented, or a broken Vite or webpack build or Jest run made green |",
+      "| [react-reviewer]({{DIR_AGENTS}}/react-reviewer.md) | a React change needs a framework-aware review: hooks, state, data fetching, accessibility, React security, tests |"
+    ]
+  }
+}

package/src/licenses/everything-claude-code.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Affaan Mustafa
+
+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/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.md

@@ -7,6 +7,8 @@
 
 {{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"),
@@ -27,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

@@ -16,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
@@ -25,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/debug.md

@@ -28,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

@@ -33,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.
@@ -50,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/handoff.md

@@ -11,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/parallel-agents.md

@@ -4,6 +4,8 @@
 
 {{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
@@ -12,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/plan.md

@@ -20,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

@@ -20,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 -->