@pi-in-go/pigpen-dev-skills 0.1.0

package/CREDITS.md

@@ -0,0 +1,43 @@
+# Credits
+
+The Skills in this Package are adaptations of public Skills. The adaptation
+work (condensing, adding a mutation gate, removing the author's private workflow
+references) is by **Michael Kinsy**, MIT. Each adapted file names its source at
+the top and keeps the upstream license.
+
+## mattpocock/skills
+
+**Matt Pocock**, https://github.com/mattpocock/skills, MIT
+(Copyright (c) 2026 Matt Pocock; license at
+[`upstream/mattpocock-skills/LICENSE`](upstream/mattpocock-skills/LICENSE)).
+
+Adapted from the `engineering` and `productivity` Skills at commit
+`d81f3a183412e71a5b1e84ca21bc1a35eea03a60`:
+
+| Skill here | Upstream Skill | What changed |
+|---|---|---|
+| `pigpen-tdd` | `engineering/tdd` | Condensed; explicit test-first mode; mutation gate; independent-oracle rule. |
+| `pigpen-diagnosing-bugs` | `engineering/diagnosing-bugs` | Condensed; loop preference list kept; regression test must be able to fail. |
+| `pigpen-handoff` | `productivity/handoff` | Index-not-store rule for what goes inline. |
+| `pigpen-research` | `engineering/research` | Claim records (value, source, basis, reasoning); where findings go; no background agent required. |
+| `pigpen-grilling` | `productivity/grilling` | One question at a time instead of rounds. |
+| `pigpen-prototype` | `engineering/prototype` | Condensed; `LOGIC.md` and `UI.md` kept close to the source. |
+| `pigpen-code-review` | `engineering/code-review` | Standards and spec axes only; subagents optional. |
+
+The unmodified upstream files are kept in [`upstream/mattpocock-skills/`](upstream/mattpocock-skills)
+(renamed from `SKILL.md` so they are not loaded as Skills). They are the current
+files at the commit above. The adaptations were made from an earlier revision, whose
+commit was not recorded, so the diff between an upstream file and its adaptation also
+contains upstream changes made since.
+
+## mitsuhiko/agent-stuff
+
+**Armin Ronacher** (GitHub: mitsuhiko), https://github.com/mitsuhiko/agent-stuff,
+Apache License 2.0 (license at
+[`upstream/mitsuhiko-agent-stuff/LICENSE`](upstream/mitsuhiko-agent-stuff/LICENSE)).
+
+`pigpen-commit` is adapted from `skills/commit/SKILL.md` at commit
+`0865c849befd2021490679f96a8dee58c84ac857`. As Apache-2.0 section 4(b) requires,
+the modified file states that it was changed: the body of the commit message is
+strongly encouraged rather than optional, and the format rules were tightened. The
+original is in [`upstream/mitsuhiko-agent-stuff/commit.md`](upstream/mitsuhiko-agent-stuff/commit.md).

package/LICENSE

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

@@ -0,0 +1,34 @@
+# dev-skills
+
+Eight general Skills for software work, as one PiG Package. They are adaptations of
+public Skills (see [CREDITS.md](CREDITS.md)); the names carry a `pigpen-` prefix.
+
+| Skill | Use it when |
+|---|---|
+| `pigpen-tdd` | you want test-first work: seams, independent oracles, red before green, and a mutation gate. |
+| `pigpen-diagnosing-bugs` | something is broken, failing or slow: build a fast pass/fail loop first, then localize, then fix and prove. |
+| `pigpen-handoff` | a session ends and another must continue: an index document in the OS temp directory, not the repository. |
+| `pigpen-research` | a question needs primary sources, with claims recorded as value, source, basis and reasoning. |
+| `pigpen-grilling` | you want a plan stress-tested: one question at a time, each with a recommended answer. |
+| `pigpen-prototype` | a design question needs throwaway code: a logic prototype or several UI variants. |
+| `pigpen-code-review` | review a diff against standards and against its spec. User-invoked only. |
+| `pigpen-commit` | write a Conventional Commits message with a descriptive body. |
+
+Skills are text only: no scripts, no network, nothing runs by itself.
+
+## Install
+
+```sh
+pig install ./components/dev-skills
+```
+
+`pig package validate ./components/dev-skills` validates the Package. The Skills expand
+as `/skill:pigpen-tdd` and so on, and the model can load them by name.
+
+## Not in this Package
+
+The author's other Skills tie into a private workflow (spec management, planning,
+ticketing, glossaries) or wrap third-party CLIs, and are not included. If you want
+Matt Pocock's originals, install them from https://github.com/mattpocock/skills.
+
+MIT. © Michael Kinsy for the adaptations; upstream licenses in `upstream/`.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pi-in-go/pigpen-dev-skills",
+  "version": "0.1.0",
+  "description": "General software-development Skills adapted from public sources: TDD with a mutation gate, diagnosing bugs, handoff, research, grilling, prototyping, code review and commit messages",
+  "keywords": [
+    "pig-package",
+    "skills",
+    "tdd",
+    "debugging",
+    "code-review",
+    "pigpen",
+    "skill"
+  ],
+  "license": "MIT",
+  "author": "Michael Kinsy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichaelKinsy/pigpen.git",
+    "directory": "components/dev-skills"
+  },
+  "homepage": "https://github.com/MichaelKinsy/pigpen/tree/main/components/dev-skills#readme",
+  "bugs": {
+    "url": "https://github.com/MichaelKinsy/pigpen/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills",
+    "upstream",
+    "README.md",
+    "LICENSE",
+    "CREDITS.md",
+    "provenance.json"
+  ],
+  "pi": {
+    "skills": [
+      "skills/pigpen-code-review",
+      "skills/pigpen-commit",
+      "skills/pigpen-diagnosing-bugs",
+      "skills/pigpen-grilling",
+      "skills/pigpen-handoff",
+      "skills/pigpen-prototype",
+      "skills/pigpen-research",
+      "skills/pigpen-tdd"
+    ]
+  }
+}

package/provenance.json

@@ -0,0 +1,28 @@
+{
+  "origin": "ported",
+  "authors": ["Michael Kinsy"],
+  "license": "MIT",
+  "licenseFile": "LICENSE",
+  "upstreams": [
+    {
+      "name": "mattpocock/skills",
+      "authors": ["Matt Pocock"],
+      "url": "https://github.com/mattpocock/skills",
+      "revision": "d81f3a183412e71a5b1e84ca21bc1a35eea03a60",
+      "path": "upstream/mattpocock-skills",
+      "license": "MIT",
+      "licenseFile": "upstream/mattpocock-skills/LICENSE",
+      "attributionFile": "CREDITS.md"
+    },
+    {
+      "name": "mitsuhiko/agent-stuff",
+      "authors": ["Armin Ronacher"],
+      "url": "https://github.com/mitsuhiko/agent-stuff",
+      "revision": "0865c849befd2021490679f96a8dee58c84ac857",
+      "path": "upstream/mitsuhiko-agent-stuff",
+      "license": "Apache-2.0",
+      "licenseFile": "upstream/mitsuhiko-agent-stuff/LICENSE",
+      "attributionFile": "CREDITS.md"
+    }
+  ]
+}

package/skills/pigpen-code-review/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: pigpen-code-review
+description: Review the diff since a fixed point along two axes, standards and spec, and report them side by side.
+disable-model-invocation: true
+---
+
+Adapted from Matt Pocock's `code-review` skill (MIT); see the Package's CREDITS.md.
+
+Review the diff between `HEAD` and a fixed point the user names. This is a
+user-selected evaluation after the change works. Read the evidence that it works (run
+output, test results, a manual check) before reviewing. If there is none, report that
+gap instead of substituting a broad automated suite. Focused commands may verify a
+concrete finding.
+
+## 1. Pin the fixed point
+
+A commit, branch, tag, or the main branch. If the user named none, ask. Capture the
+diff once with `git diff <fixed-point>...HEAD` (three-dot, against the merge-base) and
+the commit list with `git log <fixed-point>..HEAD --oneline`. Confirm the ref resolves
+and the diff is non-empty before going further.
+
+## 2. Find the spec
+
+In order: issue references in the commit messages; a path the user passed; a spec
+under `docs/`, `specs/`, or a scratch directory matching the branch. If none exists,
+the spec axis reports "no spec available" rather than inventing one.
+
+## 3. Run the axes
+
+If subagents are available, run the two axes as parallel subagents so they do not
+pollute each other's context; otherwise run them one after the other.
+
+- **Standards**: does the code follow this repository's documented standards
+  (contributing guide, agent instructions, lint and style rules)? Each finding is a
+  judgement call labelled as such, never a hard violation, and anything tooling
+  already enforces is skipped.
+- **Spec**: does the diff faithfully implement the originating issue or spec? Missing
+  behavior, invented behavior, and silent scope changes all count.
+
+## 4. Aggregate
+
+One report, two labelled sections, each finding tied to a file and line. Findings
+only; whether a defect can wait is the user's call. End with the single most
+important finding, not a summary of all of them.

package/skills/pigpen-commit/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pigpen-commit
+description: "Read this skill before making git commits"
+license: Apache-2.0
+---
+
+Adapted from mitsuhiko/agent-stuff `skills/commit` (Apache-2.0); see the Package's
+CREDITS.md. **This file was changed from the original:** the body is strongly
+encouraged rather than optional, and the format rules were tightened.
+
+Create a git commit for the current changes using Conventional Commits format with a **polished, highly descriptive** message.
+
+## Format
+
+`<type>(<scope>): <summary>`
+
+- `type` REQUIRED. Use `feat` for new features, `fix` for bug fixes. Other common types: `docs`, `refactor`, `chore`, `test`, `perf`.
+- `scope` OPTIONAL. Short noun in parentheses for the affected area (e.g., `api`, `parser`, `ui`).
+- `summary` REQUIRED. Short, imperative, <= 72 chars, no trailing period.
+
+## Notes
+
+- Body is **strongly encouraged** — always include one unless the change is trivially obvious (e.g., fixing a typo). The body should explain **what** changed, **why** it changed, the approach taken, and any notable decisions. A reader of `git log` should understand the change without looking at the diff.
+- Do NOT include breaking-change markers or footers.
+- Do NOT add sign-offs (no `Signed-off-by`), unless the project requires them.
+- Only commit; do NOT push.
+- If it is unclear whether a file should be included, ask the user which files to commit.
+- Treat any caller-provided arguments as additional commit guidance. Common patterns:
+  - Freeform instructions should influence scope, summary, and body.
+  - File paths or globs should limit which files to commit. If files are specified, only stage/commit those unless the user explicitly asks otherwise.
+  - If arguments combine files and instructions, honor both.
+
+## Steps
+
+1. Infer from the prompt if the user provided specific file paths/globs and/or additional instructions.
+2. Review `git status` and `git diff` to understand the current changes (limit to argument-specified files if provided).
+3. (Optional) Run `git log -n 50 --pretty=format:%s` to see commonly used scopes.
+4. If there are ambiguous extra files, ask the user for clarification before committing.
+5. Stage only the intended files (all changes if no files specified).
+6. Run `git commit -m "<subject>"` (and `-m "<body>"` if needed).

package/skills/pigpen-diagnosing-bugs/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pigpen-diagnosing-bugs
+description: Diagnosis loop for hard bugs and performance regressions. Use when the user says diagnose or debug, or reports something broken, throwing, failing, or slow.
+---
+
+Adapted from Matt Pocock's `diagnosing-bugs` skill (MIT), condensed; see the Package's
+CREDITS.md.
+
+If the project keeps a glossary (`CONTEXT.md`), read it for a mental model of the
+modules involved, and check recorded decisions (ADRs) in the area: a surprising
+behavior is sometimes a decision that was written down.
+
+## Phase 1: build a feedback loop
+
+This is the skill; everything after is mechanical. Get a **tight** pass/fail signal
+that goes red on this bug, and the bug is 90 percent fixed. Start with the real
+surface that exposed the failure, then make that loop faster and more repeatable. In
+rough order of preference:
+
+1. A reproduction against the running system: the agent itself, a browser, a CLI, an
+   API or an SDK.
+2. A benchmark that reproduces a performance or scale regression.
+3. Replay of a captured trace, payload, or event log through the real path.
+4. An existing focused test that already reproduces the bug.
+5. A headless browser or caller script that checks the visible symptom.
+6. A throwaway harness: the minimal subset of the system that exercises the path.
+7. A property or fuzz loop over random inputs, for "sometimes wrong output".
+8. A bisection harness, so `git bisect run` can walk to the breaking change.
+9. A differential loop: same input through two versions or configs, diffed.
+10. A human-in-the-loop script, so manual actions still produce structured output.
+
+Then tighten it: faster (cache setup, narrow scope), sharper (assert the specific
+symptom, not "didn't crash"), deterministic (pin time, seed RNG, isolate the
+filesystem). A two-second deterministic loop is a superpower; a flaky thirty-second
+one is barely better than none.
+
+For non-deterministic bugs, raise the reproduction rate rather than hunting a clean
+repro: loop the trigger 100 times, parallelize, stress, inject sleeps. A 50 percent
+flake is debuggable; a 1 percent flake is not.
+
+If you genuinely cannot build a loop, stop and say so, list what you tried, and ask
+for a reproducing environment, a captured artifact, or permission to add temporary
+instrumentation. Do not hypothesize without a loop.
+
+## Phase 2: localize
+
+Consume the loop: bisect the code path, test hypotheses one variable at a time, add
+instrumentation the loop reads. State each hypothesis before testing it, so a wrong
+guess is information rather than drift.
+
+## Phase 3: fix and prove
+
+Fix the cause, not the symptom. The loop that failed now succeeds, and the benchmark
+recovers when performance was the defect. Turn the smallest useful reproduction into
+a permanent regression test, and check it can fail (revert the fix, watch it go red).
+If the fix reveals a defect out of scope, report it plainly. Naming the defect does
+not resolve it.

package/skills/pigpen-grilling/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: pigpen-grilling
+description: Interview the user relentlessly about a plan, decision, or idea until shared understanding is reached. Use when the user wants their thinking stress-tested or says "grill".
+---
+
+Adapted from Matt Pocock's `grilling` skill (MIT); see the Package's CREDITS.md. This
+version asks one question at a time.
+
+Interview the user about every aspect of the plan until you reach a shared
+understanding. Walk each branch of the decision tree, resolving dependencies between
+decisions one by one.
+
+Ask one question at a time and wait for the answer. If a structured-question tool is
+available (for example `ask_user_question`), use it; otherwise ask in chat. Never put
+more than one substantive decision in one question: a batch lets the load-bearing one
+hide among the easy ones.
+
+For each question, give your recommended answer with your reasoning, and present
+verified context and consequences rather than unexplained labels. When choices are
+offered, always allow a free-text answer. Propose a concrete criterion to confirm
+rather than asking an open question.
+
+If a fact can be found in the environment (the filesystem, the code, the tracker),
+look it up instead of asking. Decisions belong to the user; facts do not. Never ask
+the human for something you can resolve yourself: a revision, a file path, a retry, a
+validation fix.
+
+If the project has a glossary (`CONTEXT.md`), use its canonical terms. When the user's
+answer introduces a conflicting term, stop and resolve the term before continuing.
+
+Do not act on the plan until the user confirms the understanding is shared. Record the
+accepted answers and their rationale where the project keeps decisions.

package/skills/pigpen-handoff/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: pigpen-handoff
+description: Compact the current conversation into a handoff document for the next session's agent.
+---
+
+Adapted from Matt Pocock's `handoff` skill (MIT); see the Package's CREDITS.md.
+
+Write a handoff document so a fresh agent can continue this work, and save it to the
+operating system's temporary directory, never the workspace. A handoff is session
+memory, not a deliverable: do not commit one to the repository.
+
+The document is an index, not a store. Durable knowledge already has a home: specs,
+ADRs, glossaries, plans, issues, commits, and diffs. Reference each by path or URL and
+never duplicate its content. What belongs inline is only what exists nowhere else yet:
+the current state of the task, the next step, the dead ends already tried, and the
+constraints spoken but not yet written down. If something inline deserves to outlive
+the handoff, file it properly first (a decision record, a glossary term, an issue
+comment) and then point at it.
+
+Include a "suggested skills" section naming the skills the next session should invoke,
+and name the issue or ticket the session should pick up, if one exists.
+
+Redact secrets: API keys, passwords, personal information.
+
+If the user passed arguments, treat them as what the next session will focus on, and
+shape the document for that.

package/skills/pigpen-prototype/LOGIC.md

@@ -0,0 +1,27 @@
+# Logic prototypes
+
+The question: does this state model or algorithm feel right in the hand, not
+just on paper?
+
+Build a minimal interactive terminal app around the state machine or core
+logic, real enough to poke:
+
+- Model the states and transitions as plainly as the language allows: a
+  discriminated union, an enum plus a transition function, a reducer. This
+  snippet is the likely survivor; the decision-rich shape may be inlined into
+  the resolving ticket, so keep it separable from the harness around it.
+- A read-eval loop drives it: print the full current state, list the legal
+  actions, apply the chosen one, print the new state. Illegal actions print
+  why they are illegal rather than crashing, because the rejected transitions
+  are half of what the prototype is checking.
+- Seed it with the awkward cases from the discussion: the double-cancel, the
+  refund after partial shipment, the concurrent claim. Script them as named
+  scenarios the user can replay with one keystroke, so the conversation can
+  point at "scenario 3" instead of re-deriving it.
+- Keep the vocabulary of the project glossary (`CONTEXT.md`, if any) in state names and actions. A prototype
+  that renames the domain mid-flight pollutes the discussion it exists to
+  sharpen.
+
+Done when the user has pushed the model through the awkward cases and either
+trusts it or has found where it breaks. Record the verdict and the question it
+settled on the ticket, then capture and discard per the rules in SKILL.md.

package/skills/pigpen-prototype/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: pigpen-prototype
+description: Build a throwaway prototype that answers a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+Adapted from Matt Pocock's `prototype` skill (MIT), condensed; see the Package's
+CREDITS.md.
+
+A prototype is **throwaway code that answers a question**. The question decides the
+shape, so identify it first, from the prompt, the surrounding code, a decision record,
+or by asking:
+
+- "Does this logic or state model feel right?" leads to [LOGIC.md](LOGIC.md): a tiny
+  interactive terminal app that pushes the state machine through cases that are hard
+  to reason about on paper.
+- "What should this look like?" leads to [UI.md](UI.md): several radically different
+  variations on one route, switchable at runtime.
+
+If the question is ambiguous and the user is not reachable, pick the branch that
+matches the surrounding code (a backend module means logic, a page or component means
+UI) and state the assumption at the top of the prototype.
+
+## Rules for both branches
+
+1. **Throwaway from day one, marked as such.** Put the code next to the module or page
+   it prototypes so context is obvious, named so a casual reader sees it is not
+   production. Follow the project's existing routing and runner conventions; invent
+   nothing top-level.
+2. **One command to run.** The user starts it without thinking.
+3. **No persistence by default.** State lives in memory. If the question is about
+   persistence, use a scratch store with a wipe-me name.
+4. **Skip the polish.** No tests, no abstractions, no error handling beyond runnable.
+   The least code that answers the question. Speed of learning is the whole point.
+5. **Surface the state.** After every action, print or render the full relevant state
+   so the user sees what changed.
+6. **Capture, then discard.** Fold the validated decision into the real code or the
+   ticket it answers. Commit the prototype itself to a throwaway branch off the main
+   line and leave a pointer from the ticket. If the decision is hard to reverse and
+   surprising, record it as a decision record. The main branch keeps only the
+   validated decision, never the prototype.

package/skills/pigpen-prototype/UI.md

@@ -0,0 +1,23 @@
+# UI prototypes
+
+The question: what should this look like, out of a genuinely open space?
+
+Build several **radically different** variations, not one design with three
+accent colors. Different layout, different information hierarchy, different
+interaction model. Three to five variants; fewer hides the space, more blurs
+the reactions.
+
+- All variants live on a single route, switched by a URL search parameter,
+  with a small floating switcher so the user flips between them in place.
+  Obey the project's existing routing convention for where that route goes.
+- Use the project's real component library and design tokens where they
+  exist, so reactions are about the design and not about unstyled controls.
+- Fake the data inline with realistic shapes and awkward lengths: the
+  40-character name, the empty list, the 200-row table. A variant that only
+  looks right with pretty data has not answered the question.
+- Wire only the interactions the question is about. Everything else is inert
+  and visibly so.
+
+Show the variants, collect the reaction to each, and converge: often the
+answer is one variant's layout with another's detail. Record which variant
+won and why on the ticket, then capture and discard per SKILL.md.

package/skills/pigpen-research/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pigpen-research
+description: Investigate a question against primary sources and report findings with citations, provenance, and explicit uncertainty.
+---
+
+# Research
+
+Adapted from Matt Pocock's `research` skill (MIT); see the Package's CREDITS.md.
+
+Investigate the question against primary sources: official documentation, source code,
+specifications, and first-party APIs. Follow each claim to the source that owns it.
+
+Record each captured claim as one semantic unit:
+
+- **Value:** what the claim says.
+- **Source:** the exact citation, file, API, or measurement.
+- **Basis:** `stated`, `inferred`, or `unverified`.
+- **Reasoning:** why the evidence supports the claim or why uncertainty remains.
+
+Do not present an inference as something the source stated. Do not merge conflicting
+claims by silently replacing one source with another; show the conflict.
+
+Findings go, in order:
+
+1. the reply, when the asker is in this session;
+2. the issue or decision record the research was meant to inform;
+3. the project's established place for research notes, when the evidence fits neither.
+
+If no durable research location exists, keep the findings in the reply and propose a
+location. Never create a loose summary or report file merely because the research was
+long.
+
+When delegating to a background agent (if your setup has subagents), give it one
+factual question, the decision it informs, source priority, exit criteria, and the
+required citation shape. It returns evidence and citations to you; it does not decide.
+Independent questions may run in parallel. Reduce their claims and surface conflicts
+instead of concatenating reports.

package/skills/pigpen-tdd/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: pigpen-tdd
+description: Test-driven development. Use when building features or fixing bugs test-first, or when the user mentions red-green or integration tests.
+---
+
+Adapted from Matt Pocock's `tdd` skill (MIT); see the Package's CREDITS.md. Changes: a
+mutation gate, and a stricter rule that tests take their expected values from an
+independent oracle.
+
+This skill is an explicit test-first mode. Load it when the user asks for TDD or when
+an accepted plan selects red-green-refactor for a crisp contract.
+
+If the project keeps a glossary (`CONTEXT.md` or `GLOSSARY.md`), read it first so test
+names and interface vocabulary match the domain language, and respect recorded
+decisions (ADRs) in the area you touch.
+
+## Seams
+
+A **seam** is the public boundary you test at: where behavior is observable without
+reaching inside. Tests live at seams, never against internals. Before writing any
+test, write down the seams under test and confirm them with the user; agreeing them up
+front is how testing effort lands on critical paths. Prefer existing seams, and the
+highest seam possible.
+
+## What a good test is
+
+A test verifies behavior through the public interface and takes its expected value
+from an independent oracle: the spec, a worked example, a known-good literal. Never
+from the code's own computation. A good test reads like a specification and survives
+refactors.
+
+## Anti-patterns
+
+- **Implementation-coupled**: mocks internal collaborators, tests private methods, or
+  verifies through a side channel. The tell: it breaks on refactor when behavior did
+  not change.
+- **Tautological**: the assertion recomputes the expected value the way the code does,
+  so it passes by construction and can never disagree.
+- **Horizontal slicing**: all tests first, then all implementation. Work in vertical
+  slices instead: one test, one minimal implementation, repeat, each a tracer bullet
+  shaped by what the last cycle taught.
+
+## The loop
+
+Red before green: write the failing test, then only enough code to pass it. One seam,
+one test, one slice per cycle. Refactoring belongs to review, not to the red-green
+cycle.
+
+**Mutation gate.** A test earns its keep only if it could fail. After green, flip one
+small detail in the code it covers, a comparison or an operator, and confirm the test
+goes red; restore, and confirm green. A passing test you could not make fail is
+decoration. Run the smallest slice early and locally; the full suite once at the end.
+
+Exercise invalid, empty, boundary, and error-path inputs, not only the happy path.
+Never weaken, skip, hardcode, or delete a test to force it green. If a test is wrong,
+say so and fix it in the open.

package/upstream/mattpocock-skills/LICENSE

@@ -0,0 +1,21 @@
+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.