From 221ffca96736afefdc08ca7cf0b3965e9ea83f41 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:47:36 +0100 Subject: [PATCH 01/24] feat: Add new skills and templates for domain modeling, bug diagnosis, and architectural improvement - Introduced a human-in-the-loop script for bug diagnosis to capture user feedback. - Created ADR and CONTEXT formats to standardize architectural decision records and domain context documentation. - Developed a domain modeling skill to refine terminology and maintain a shared language. - Enhanced the improve-codebase-architecture skill to provide visual reports and deepening opportunities. - Consolidated grilling and handoff skills for better user interaction and documentation. - Updated existing skills to improve clarity and consistency in descriptions and functionality. --- .claude-plugin/plugin.json | 5 +- CLAUDE.md | 4 +- README.md | 35 ++++-- docs/commands-vs-skills.md | 16 +++ skills/engineering/README.md | 29 +++-- .../DEEPENING.md | 2 +- .../DESIGN-IT-TWICE.md} | 6 +- skills/engineering/codebase-design/SKILL.md | 114 ++++++++++++++++++ .../{diagnose => diagnosing-bugs}/SKILL.md | 6 +- .../scripts/hitl-loop.template.sh | 0 .../ADR-FORMAT.md | 0 .../CONTEXT-FORMAT.md | 0 skills/engineering/domain-modeling/SKILL.md | 74 ++++++++++++ skills/engineering/grill-with-docs/SKILL.md | 88 +------------- .../HTML-REPORT.md | 6 +- .../improve-codebase-architecture/LANGUAGE.md | 53 -------- .../improve-codebase-architecture/SKILL.md | 41 ++----- skills/engineering/prototype/SKILL.md | 3 +- .../setup-matt-pocock-skills/SKILL.md | 4 +- .../setup-matt-pocock-skills/domain.md | 4 +- skills/engineering/tdd/SKILL.md | 5 +- skills/engineering/tdd/deep-modules.md | 33 ----- skills/engineering/tdd/interface-design.md | 31 ----- skills/engineering/to-issues/SKILL.md | 3 +- skills/engineering/to-prd/SKILL.md | 3 +- skills/engineering/triage/SKILL.md | 5 +- skills/engineering/zoom-out/SKILL.md | 2 +- skills/productivity/README.md | 10 ++ skills/productivity/caveman/SKILL.md | 7 +- skills/productivity/grill-me/SKILL.md | 9 +- skills/productivity/grilling/SKILL.md | 10 ++ skills/productivity/handoff/SKILL.md | 1 + skills/productivity/write-a-skill/SKILL.md | 3 +- 33 files changed, 328 insertions(+), 284 deletions(-) create mode 100644 docs/commands-vs-skills.md rename skills/engineering/{improve-codebase-architecture => codebase-design}/DEEPENING.md (95%) rename skills/engineering/{improve-codebase-architecture/INTERFACE-DESIGN.md => codebase-design/DESIGN-IT-TWICE.md} (87%) create mode 100644 skills/engineering/codebase-design/SKILL.md rename skills/engineering/{diagnose => diagnosing-bugs}/SKILL.md (97%) rename skills/engineering/{diagnose => diagnosing-bugs}/scripts/hitl-loop.template.sh (100%) rename skills/engineering/{grill-with-docs => domain-modeling}/ADR-FORMAT.md (100%) rename skills/engineering/{grill-with-docs => domain-modeling}/CONTEXT-FORMAT.md (100%) create mode 100644 skills/engineering/domain-modeling/SKILL.md delete mode 100644 skills/engineering/improve-codebase-architecture/LANGUAGE.md delete mode 100644 skills/engineering/tdd/deep-modules.md delete mode 100644 skills/engineering/tdd/interface-design.md create mode 100644 skills/productivity/grilling/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 304870a..679d479 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "mattpocock-skills", "skills": [ - "./skills/engineering/diagnose", + "./skills/engineering/diagnosing-bugs", "./skills/engineering/grill-with-docs", "./skills/engineering/triage", "./skills/engineering/improve-codebase-architecture", @@ -11,8 +11,11 @@ "./skills/engineering/to-prd", "./skills/engineering/zoom-out", "./skills/engineering/prototype", + "./skills/engineering/domain-modeling", + "./skills/engineering/codebase-design", "./skills/productivity/caveman", "./skills/productivity/grill-me", + "./skills/productivity/grilling", "./skills/productivity/handoff", "./skills/productivity/teach", "./skills/productivity/write-a-skill" diff --git a/CLAUDE.md b/CLAUDE.md index 1100056..3899085 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,4 +11,6 @@ Every skill in `engineering/`, `productivity/`, or `misc/` must have a reference Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. -Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. +Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. + +Every `SKILL.md` is either a command (always user-invoked, `disable-model-invocation: true`) or a skill (model- or user-invocable). For the full definitions, description conventions, and the rule that commands invoke skills but never commands, see [docs/commands-vs-skills.md](./docs/commands-vs-skills.md). diff --git a/README.md b/README.md index 3011cde..02fb10a 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ For automated tests, a red-green-refactor loop is critical. This is where the ag I've built a **[`/tdd`](./skills/engineering/tdd/SKILL.md) skill** you can slot into any project. It encourages red-green-refactor and gives the agent plenty of guidance on what makes good and bad tests. -For debugging, I've also built a **[`/diagnose`](./skills/engineering/diagnose/SKILL.md)** skill that wraps best debugging practices into a simple loop. +For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/diagnosing-bugs/SKILL.md)** skill that wraps best debugging practices into a simple loop. ### #4: We Built A Ball Of Mud @@ -142,31 +142,46 @@ Software engineering fundamentals matter more than ever. These skills are my bes ## Reference +These come in two flavours. **Commands** are always user-invoked (you type `/grill-me`); their job is to orchestrate. **Skills** can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A command may invoke skills, but never another command. + ### Engineering Skills I use daily for code work. -- **[diagnose](./skills/engineering/diagnose/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. -- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. -- **[triage](./skills/engineering/triage/SKILL.md)** — Triage issues through a state machine of triage roles. -- **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`. -- **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Scaffold the per-repo config (issue tracker, triage label vocabulary, domain doc layout) that the other engineering skills consume. Run once per repo before using `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out`. -- **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. -- **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices. -- **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation context into a PRD and submit it as a GitHub issue. No interview — just synthesizes what you've already discussed. -- **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code. +**Commands** + +- **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. +- **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. +- **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. +- **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. +- **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. +- **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. +- **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers on an unfamiliar section of code. - **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. +**Skills** + +- **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. +- **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. +- **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. +- **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. + ### Productivity General workflow tools, not code-specific. +**Commands** + - **[caveman](./skills/productivity/caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./skills/productivity/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[write-a-skill](./skills/productivity/write-a-skill/SKILL.md)** — Create new skills with proper structure, progressive disclosure, and bundled resources. +**Skills** + +- **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. The reusable loop behind `grill-me` and `grill-with-docs`. + ### Misc Tools I keep around but rarely use. diff --git a/docs/commands-vs-skills.md b/docs/commands-vs-skills.md new file mode 100644 index 0000000..b6bb8e3 --- /dev/null +++ b/docs/commands-vs-skills.md @@ -0,0 +1,16 @@ +# Commands vs skills + +Every `SKILL.md` in this repo is one of two kinds. The test for "is it a skill" is: _could the model usefully reach for this autonomously?_ Reuse is the reason to extract a skill, not the test. + +- **Command** — _always_ user-invoked. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…") from command descriptions. A command may invoke skills, but **never another command**. +- **Skill** — invocable by **model or user**. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. Do not set `disable-model-invocation`. + +Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. + +## Dependencies between them + +Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. + +## Passive vs active domain work + +Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 065c2bf..12c32a5 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -2,13 +2,24 @@ Skills I use daily for code work. -- **[diagnose](./diagnose/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. -- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates `CONTEXT.md` and ADRs inline. -- **[triage](./triage/SKILL.md)** — Triage issues through a state machine of triage roles. -- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Find deepening opportunities in a codebase, informed by the domain language in `CONTEXT.md` and the decisions in `docs/adr/`. -- **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Scaffold the per-repo config (issue tracker, triage label vocabulary, domain doc layout) that the other engineering skills consume. +## Commands + +User-invoked entry points (`disable-model-invocation: true`). + +- **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. +- **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. +- **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. +- **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. +- **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. +- **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. +- **[zoom-out](./zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers. +- **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype — a runnable terminal app for state/logic questions, or several toggleable UI variations. + +## Skills + +Model- or user-invocable (rich trigger phrasing so the model can reach for them). + +- **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. -- **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable GitHub issues using vertical slices. -- **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation context into a PRD and submit it as a GitHub issue. -- **[zoom-out](./zoom-out/SKILL.md)** — Tell the agent to zoom out and give broader context or a higher-level perspective on an unfamiliar section of code. -- **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. +- **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. +- **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. diff --git a/skills/engineering/improve-codebase-architecture/DEEPENING.md b/skills/engineering/codebase-design/DEEPENING.md similarity index 95% rename from skills/engineering/improve-codebase-architecture/DEEPENING.md rename to skills/engineering/codebase-design/DEEPENING.md index ecaf5d7..3938457 100644 --- a/skills/engineering/improve-codebase-architecture/DEEPENING.md +++ b/skills/engineering/codebase-design/DEEPENING.md @@ -1,6 +1,6 @@ # Deepening -How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**. ## Dependency categories diff --git a/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md similarity index 87% rename from skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md rename to skills/engineering/codebase-design/DESIGN-IT-TWICE.md index 3197723..49a7c42 100644 --- a/skills/engineering/improve-codebase-architecture/INTERFACE-DESIGN.md +++ b/skills/engineering/codebase-design/DESIGN-IT-TWICE.md @@ -1,8 +1,8 @@ -# Interface Design +# Design It Twice When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. -Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. +Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. ## Process @@ -27,7 +27,7 @@ Prompt each sub-agent with a separate technical brief (file paths, coupling deta - Agent 3: "Optimise for the most common caller — make the default case trivial." - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." -Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. +Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. Each sub-agent outputs: diff --git a/skills/engineering/codebase-design/SKILL.md b/skills/engineering/codebase-design/SKILL.md new file mode 100644 index 0000000..db1f10a --- /dev/null +++ b/skills/engineering/codebase-design/SKILL.md @@ -0,0 +1,114 @@ +--- +name: codebase-design +description: Shared discipline and vocabulary for designing deep modules — a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, choose between interface alternatives, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +--- + +# Codebase Design + +Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone. + +## Glossary + +Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. + +**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service. + +**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface). + +**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. + +**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation. + +**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context). + +**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside). + +**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests. + +**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere. + +## Deep vs shallow + +**Deep module** = small interface + lots of implementation: + +``` +┌─────────────────────┐ +│ Small Interface │ ← Few methods, simple params +├─────────────────────┤ +│ │ +│ Deep Implementation│ ← Complex logic hidden +│ │ +└─────────────────────┘ +``` + +**Shallow module** = large interface + little implementation (avoid): + +``` +┌─────────────────────────────────┐ +│ Large Interface │ ← Many methods, complex params +├─────────────────────────────────┤ +│ Thin Implementation │ ← Just passes through +└─────────────────────────────────┘ +``` + +When designing an interface, ask: + +- Can I reduce the number of methods? +- Can I simplify the parameters? +- Can I hide more complexity inside? + +## Principles + +- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. +- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. +- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape. +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. + +## Designing for testability + +Good interfaces make testing natural: + +1. **Accept dependencies, don't create them.** + + ```typescript + // Testable + function processOrder(order, paymentGateway) {} + + // Hard to test + function processOrder(order) { + const gateway = new StripeGateway(); + } + ``` + +2. **Return results, don't produce side effects.** + + ```typescript + // Testable + function calculateDiscount(cart): Discount {} + + // Hard to test + function applyDiscount(cart): void { + cart.total -= discount; + } + ``` + +3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup. + +## Relationships + +- A **Module** has exactly one **Interface** (the surface it presents to callers and tests). +- **Depth** is a property of a **Module**, measured against its **Interface**. +- A **Seam** is where a **Module**'s **Interface** lives. +- An **Adapter** sits at a **Seam** and satisfies the **Interface**. +- **Depth** produces **Leverage** for callers and **Locality** for maintainers. + +## Rejected framings + +- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. +- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. +- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. + +## Going deeper + +- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing. +- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement. diff --git a/skills/engineering/diagnose/SKILL.md b/skills/engineering/diagnosing-bugs/SKILL.md similarity index 97% rename from skills/engineering/diagnose/SKILL.md rename to skills/engineering/diagnosing-bugs/SKILL.md index ed55bda..31b3cda 100644 --- a/skills/engineering/diagnose/SKILL.md +++ b/skills/engineering/diagnosing-bugs/SKILL.md @@ -1,13 +1,13 @@ --- -name: diagnose +name: diagnosing-bugs description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression. --- -# Diagnose +# Diagnosing Bugs A discipline for hard bugs. Skip phases only when explicitly justified. -When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. +When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching. ## Phase 1 — Build a feedback loop diff --git a/skills/engineering/diagnose/scripts/hitl-loop.template.sh b/skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh similarity index 100% rename from skills/engineering/diagnose/scripts/hitl-loop.template.sh rename to skills/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh diff --git a/skills/engineering/grill-with-docs/ADR-FORMAT.md b/skills/engineering/domain-modeling/ADR-FORMAT.md similarity index 100% rename from skills/engineering/grill-with-docs/ADR-FORMAT.md rename to skills/engineering/domain-modeling/ADR-FORMAT.md diff --git a/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md b/skills/engineering/domain-modeling/CONTEXT-FORMAT.md similarity index 100% rename from skills/engineering/grill-with-docs/CONTEXT-FORMAT.md rename to skills/engineering/domain-modeling/CONTEXT-FORMAT.md diff --git a/skills/engineering/domain-modeling/SKILL.md b/skills/engineering/domain-modeling/SKILL.md new file mode 100644 index 0000000..221af0d --- /dev/null +++ b/skills/engineering/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +description: Actively build and sharpen a project's domain model while you design — challenge fuzzy or conflicting terms against the glossary, stress-test concepts with concrete edge-case scenarios, cross-check claims against the code, and update CONTEXT.md and ADRs inline as decisions crystallise. Use when the user wants to refine domain terminology, build a ubiquitous language, pin down what a term really means, record a hard-won architectural decision, or when another skill needs to actively maintain the domain model. +--- + +# Domain Modeling + +Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) + +## File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index 5ea0aa9..634f7da 100644 --- a/skills/engineering/grill-with-docs/SKILL.md +++ b/skills/engineering/grill-with-docs/SKILL.md @@ -1,88 +1,10 @@ --- name: grill-with-docs -description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions. +description: Grilling session that also builds your project's domain model — sharpens terminology and updates CONTEXT.md and ADRs inline as decisions crystallise. +disable-model-invocation: true --- - +Run the `/grilling` and `/domain-modeling` skills together: -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time, waiting for feedback on each question before continuing. - -If a question can be answered by exploring the codebase, explore the codebase instead. - - - - - -## Domain awareness - -During codebase exploration, also look for existing documentation: - -### File structure - -Most repos have a single context: - -``` -/ -├── CONTEXT.md -├── docs/ -│ └── adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: - -``` -/ -├── CONTEXT-MAP.md -├── docs/ -│ └── adr/ ← system-wide decisions -├── src/ -│ ├── ordering/ -│ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions -│ └── billing/ -│ ├── CONTEXT.md -│ └── docs/adr/ -``` - -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. - -## During the session - -### Challenge against the glossary - -When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" - -### Sharpen fuzzy language - -When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." - -### Discuss concrete scenarios - -When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. - -### Cross-reference with code - -When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" - -### Update CONTEXT.md inline - -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). - -`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. - -### Offer ADRs sparingly - -Only offer to create an ADR when all three are true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will wonder "why did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). - - +- Grill me about the plan one question at a time, walking each branch of the decision tree (`/grilling`). +- As domain terms and decisions surface, actively sharpen the language and update `CONTEXT.md` and ADRs inline (`/domain-modeling`). diff --git a/skills/engineering/improve-codebase-architecture/HTML-REPORT.md b/skills/engineering/improve-codebase-architecture/HTML-REPORT.md index 8adc368..17f6d2c 100644 --- a/skills/engineering/improve-codebase-architecture/HTML-REPORT.md +++ b/skills/engineering/improve-codebase-architecture/HTML-REPORT.md @@ -39,7 +39,7 @@ Repo name, date, and a compact legend: solid box = module, dashed line = seam, r ## Candidate card -The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony. +The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony. Each candidate is one `
`: @@ -105,7 +105,7 @@ One larger card. Candidate name, one sentence on why, anchor link to its card. T ## Tone -Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift. +Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift. **Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality. @@ -120,4 +120,4 @@ Plain English, concise — but the architectural nouns and verbs come straight f **Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place. -No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one. +No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one. diff --git a/skills/engineering/improve-codebase-architecture/LANGUAGE.md b/skills/engineering/improve-codebase-architecture/LANGUAGE.md deleted file mode 100644 index 530c276..0000000 --- a/skills/engineering/improve-codebase-architecture/LANGUAGE.md +++ /dev/null @@ -1,53 +0,0 @@ -# Language - -Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. - -## Terms - -**Module** -Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice. -_Avoid_: unit, component, service. - -**Interface** -Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. -_Avoid_: API, signature (too narrow — those refer only to the type-level surface). - -**Implementation** -What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. - -**Depth** -Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation. - -**Seam** _(from Michael Feathers)_ -A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it. -_Avoid_: boundary (overloaded with DDD's bounded context). - -**Adapter** -A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside). - -**Leverage** -What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests. - -**Locality** -What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere. - -## Principles - -- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface. -- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep. -- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape. -- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it. - -## Relationships - -- A **Module** has exactly one **Interface** (the surface it presents to callers and tests). -- **Depth** is a property of a **Module**, measured against its **Interface**. -- A **Seam** is where a **Module**'s **Interface** lives. -- An **Adapter** sits at a **Seam** and satisfies the **Interface**. -- **Depth** produces **Leverage** for callers and **Locality** for maintainers. - -## Rejected framings - -- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead. -- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know. -- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**. diff --git a/skills/engineering/improve-codebase-architecture/SKILL.md b/skills/engineering/improve-codebase-architecture/SKILL.md index c12b263..a79b493 100644 --- a/skills/engineering/improve-codebase-architecture/SKILL.md +++ b/skills/engineering/improve-codebase-architecture/SKILL.md @@ -1,38 +1,23 @@ --- name: improve-codebase-architecture -description: Find deepening opportunities in a codebase, informed by the domain language in CONTEXT.md and the decisions in docs/adr/. Use when the user wants to improve architecture, find refactoring opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. +description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. +disable-model-invocation: true --- # Improve Codebase Architecture Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability. -## Glossary +This command is _informed_ by the project's domain model and built on a shared design vocabulary: -Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). - -- **Module** — anything with an interface and an implementation (function, class, package, slice). -- **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. -- **Implementation** — the code inside. -- **Depth** — leverage at the interface: a lot of behaviour behind a small interface. **Deep** = high leverage. **Shallow** = interface nearly as complex as the implementation. -- **Seam** — where an interface lives; a place behaviour can be altered without editing in place. (Use this, not "boundary.") -- **Adapter** — a concrete thing satisfying an interface at a seam. -- **Leverage** — what callers get from depth. -- **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. - -Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): - -- **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. -- **The interface is the test surface.** -- **One adapter = hypothetical seam. Two adapters = real seam.** - -This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. +- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary." +- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate. ## Process ### 1. Explore -Read the project's domain glossary and any ADRs in the area you're touching first. +Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first. Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction: @@ -50,7 +35,7 @@ Write a self-contained HTML file to the OS temp directory so nothing lands in th The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual. -For each candidate, the same template as before, but rendered as a card: +For each candidate, render a card with: - **Files** — which files/modules are involved - **Problem** — why the current architecture is causing friction @@ -61,7 +46,7 @@ For each candidate, the same template as before, but rendered as a card: End the report with a **Top recommendation** section: which candidate you'd tackle first and why. -**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." +**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service." **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids. @@ -71,11 +56,11 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o ### 3. Grilling loop -Once the user picks a candidate, drop into a grilling conversation. Walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. +Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive. -Side effects happen inline as decisions crystallize: +Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go: -- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/grill-with-docs` (see [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md). -- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. +- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern. diff --git a/skills/engineering/prototype/SKILL.md b/skills/engineering/prototype/SKILL.md index 64f3e61..ddebc18 100644 --- a/skills/engineering/prototype/SKILL.md +++ b/skills/engineering/prototype/SKILL.md @@ -1,6 +1,7 @@ --- name: prototype -description: Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs". +description: Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. +disable-model-invocation: true --- # Prototype diff --git a/skills/engineering/setup-matt-pocock-skills/SKILL.md b/skills/engineering/setup-matt-pocock-skills/SKILL.md index 1ebc6e1..1e06975 100644 --- a/skills/engineering/setup-matt-pocock-skills/SKILL.md +++ b/skills/engineering/setup-matt-pocock-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: setup-matt-pocock-skills -description: Sets up an `## Agent skills` block in AGENTS.md/CLAUDE.md and `docs/agents/` so the engineering skills know this repo's issue tracker (GitHub or local markdown), triage label vocabulary, and domain doc layout. Run before first use of `to-issues`, `to-prd`, `triage`, `diagnose`, `tdd`, `improve-codebase-architecture`, or `zoom-out` — or if those skills appear to be missing context about the issue tracker, triage labels, or domain docs. +description: Configure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills. disable-model-invocation: true --- @@ -60,7 +60,7 @@ Default: each role's string equals its name. Ask the user if they want to overri **Section C — Domain docs.** -> Explainer: Some skills (`improve-codebase-architecture`, `diagnose`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place. +> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place. Confirm the layout: diff --git a/skills/engineering/setup-matt-pocock-skills/domain.md b/skills/engineering/setup-matt-pocock-skills/domain.md index c97d6a6..b548c53 100644 --- a/skills/engineering/setup-matt-pocock-skills/domain.md +++ b/skills/engineering/setup-matt-pocock-skills/domain.md @@ -8,7 +8,7 @@ How the engineering skills should consume this repo's domain documentation when - **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. - **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src//docs/adr/` for context-scoped decisions. -If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved. +If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved. ## File structure @@ -42,7 +42,7 @@ Multi-context repo (presence of `CONTEXT-MAP.md` at the root): When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids. -If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`). +If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`). ## Flag ADR conflicts diff --git a/skills/engineering/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md index 7a98941..54f4862 100644 --- a/skills/engineering/tdd/SKILL.md +++ b/skills/engineering/tdd/SKILL.md @@ -44,14 +44,13 @@ RIGHT (vertical): ### 1. Planning -When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching. +When exploring the codebase, read `CONTEXT.md` (if it exists) so that test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching. Before writing any code: - [ ] Confirm with user what interface changes are needed - [ ] Confirm with user which behaviors to test (prioritize) -- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation) -- [ ] Design interfaces for [testability](interface-design.md) +- [ ] Identify opportunities for deep modules (small interface, deep implementation) — run the `/codebase-design` skill for the vocabulary and the testability checks - [ ] List the behaviors to test (not implementation steps) - [ ] Get user approval on the plan diff --git a/skills/engineering/tdd/deep-modules.md b/skills/engineering/tdd/deep-modules.md deleted file mode 100644 index 0d9720c..0000000 --- a/skills/engineering/tdd/deep-modules.md +++ /dev/null @@ -1,33 +0,0 @@ -# Deep Modules - -From "A Philosophy of Software Design": - -**Deep module** = small interface + lots of implementation - -``` -┌─────────────────────┐ -│ Small Interface │ ← Few methods, simple params -├─────────────────────┤ -│ │ -│ │ -│ Deep Implementation│ ← Complex logic hidden -│ │ -│ │ -└─────────────────────┘ -``` - -**Shallow module** = large interface + little implementation (avoid) - -``` -┌─────────────────────────────────┐ -│ Large Interface │ ← Many methods, complex params -├─────────────────────────────────┤ -│ Thin Implementation │ ← Just passes through -└─────────────────────────────────┘ -``` - -When designing interfaces, ask: - -- Can I reduce the number of methods? -- Can I simplify the parameters? -- Can I hide more complexity inside? diff --git a/skills/engineering/tdd/interface-design.md b/skills/engineering/tdd/interface-design.md deleted file mode 100644 index a0a20ca..0000000 --- a/skills/engineering/tdd/interface-design.md +++ /dev/null @@ -1,31 +0,0 @@ -# Interface Design for Testability - -Good interfaces make testing natural: - -1. **Accept dependencies, don't create them** - - ```typescript - // Testable - function processOrder(order, paymentGateway) {} - - // Hard to test - function processOrder(order) { - const gateway = new StripeGateway(); - } - ``` - -2. **Return results, don't produce side effects** - - ```typescript - // Testable - function calculateDiscount(cart): Discount {} - - // Hard to test - function applyDiscount(cart): void { - cart.total -= discount; - } - ``` - -3. **Small surface area** - - Fewer methods = fewer tests needed - - Fewer params = simpler test setup diff --git a/skills/engineering/to-issues/SKILL.md b/skills/engineering/to-issues/SKILL.md index 9f6efbf..9b7dec9 100644 --- a/skills/engineering/to-issues/SKILL.md +++ b/skills/engineering/to-issues/SKILL.md @@ -1,6 +1,7 @@ --- name: to-issues -description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. Use when user wants to convert a plan into issues, create implementation tickets, or break down work into issues. +description: Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. +disable-model-invocation: true --- # To Issues diff --git a/skills/engineering/to-prd/SKILL.md b/skills/engineering/to-prd/SKILL.md index ee758fd..6844b17 100644 --- a/skills/engineering/to-prd/SKILL.md +++ b/skills/engineering/to-prd/SKILL.md @@ -1,6 +1,7 @@ --- name: to-prd -description: Turn the current conversation context into a PRD and publish it to the project issue tracker. Use when user wants to create a PRD from the current context. +description: Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +disable-model-invocation: true --- This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. diff --git a/skills/engineering/triage/SKILL.md b/skills/engineering/triage/SKILL.md index 3dee68f..145a98f 100644 --- a/skills/engineering/triage/SKILL.md +++ b/skills/engineering/triage/SKILL.md @@ -1,6 +1,7 @@ --- name: triage -description: Triage issues through a state machine driven by triage roles. Use when user wants to create an issue, triage issues, review incoming bugs or feature requests, prepare issues for an AFK agent, or manage issue workflow. +description: Move issues through a state machine of triage roles — categorise, reproduce, grill if needed, and write agent-ready briefs. +disable-model-invocation: true --- # Triage @@ -66,7 +67,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick. 3. **Reproduce (bugs only).** Before any grilling, attempt reproduction: read the reporter's steps, trace the relevant code, run tests or commands. Report what happened — successful repro with code path, failed repro, or insufficient detail (a strong `needs-info` signal). A confirmed repro makes a much stronger agent brief. -4. **Grill (if needed).** If the issue needs fleshing out, run a `/grill-with-docs` session. +4. **Grill (if needed).** If the issue needs fleshing out, run the `/grilling` and `/domain-modeling` skills together — grill the issue into shape one question at a time, sharpening domain terms and updating `CONTEXT.md`/ADRs inline as decisions land. 5. **Apply the outcome:** - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)). diff --git a/skills/engineering/zoom-out/SKILL.md b/skills/engineering/zoom-out/SKILL.md index 1e7a5dc..8cc007c 100644 --- a/skills/engineering/zoom-out/SKILL.md +++ b/skills/engineering/zoom-out/SKILL.md @@ -1,6 +1,6 @@ --- name: zoom-out -description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture. +description: Ask the agent to zoom out a level and map the relevant modules and callers using the project's domain language. disable-model-invocation: true --- diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 23a506e..c53a097 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -2,8 +2,18 @@ General workflow tools, not code-specific. +## Commands + +User-invoked entry points (`disable-model-invocation: true`). + - **[caveman](./caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[write-a-skill](./write-a-skill/SKILL.md)** — Create new skills with proper structure, progressive disclosure, and bundled resources. + +## Skills + +Model- or user-invocable (rich trigger phrasing so the model can reach for them). + +- **[grilling](./grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. diff --git a/skills/productivity/caveman/SKILL.md b/skills/productivity/caveman/SKILL.md index 85770a3..9b0fc8b 100644 --- a/skills/productivity/caveman/SKILL.md +++ b/skills/productivity/caveman/SKILL.md @@ -1,10 +1,7 @@ --- name: caveman -description: > - Ultra-compressed communication mode. Cuts token usage ~75% by dropping - filler, articles, and pleasantries while keeping full technical accuracy. - Use when user says "caveman mode", "talk like caveman", "use caveman", - "less tokens", "be brief", or invokes /caveman. +description: Ultra-compressed communication mode — cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. +disable-model-invocation: true --- Respond terse like smart caveman. All technical substance stay. Only fluff die. diff --git a/skills/productivity/grill-me/SKILL.md b/skills/productivity/grill-me/SKILL.md index bd04394..7ea10d6 100644 --- a/skills/productivity/grill-me/SKILL.md +++ b/skills/productivity/grill-me/SKILL.md @@ -1,10 +1,7 @@ --- name: grill-me -description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me". +description: Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. +disable-model-invocation: true --- -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time. - -If a question can be answered by exploring the codebase, explore the codebase instead. +Run the `/grilling` skill. diff --git a/skills/productivity/grilling/SKILL.md b/skills/productivity/grilling/SKILL.md new file mode 100644 index 0000000..68c768e --- /dev/null +++ b/skills/productivity/grilling/SKILL.md @@ -0,0 +1,10 @@ +--- +name: grilling +description: Interview the user relentlessly about a plan or design until you reach shared understanding, walking each branch of the decision tree and resolving dependencies between decisions one at a time. Use when the user wants to stress-test a plan, get grilled on a design, pressure-test decisions before building, or when another skill needs a grilling loop. +--- + +Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time, waiting for feedback on each question before continuing. + +If a question can be answered by exploring the codebase, explore the codebase instead. diff --git a/skills/productivity/handoff/SKILL.md b/skills/productivity/handoff/SKILL.md index 0aa5b99..ec762d9 100644 --- a/skills/productivity/handoff/SKILL.md +++ b/skills/productivity/handoff/SKILL.md @@ -2,6 +2,7 @@ name: handoff description: Compact the current conversation into a handoff document for another agent to pick up. argument-hint: "What will the next session be used for?" +disable-model-invocation: true --- Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace. diff --git a/skills/productivity/write-a-skill/SKILL.md b/skills/productivity/write-a-skill/SKILL.md index 7339c8a..4f085e5 100644 --- a/skills/productivity/write-a-skill/SKILL.md +++ b/skills/productivity/write-a-skill/SKILL.md @@ -1,6 +1,7 @@ --- name: write-a-skill -description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill. +description: Create a new agent skill with proper structure, progressive disclosure, and bundled resources. +disable-model-invocation: true --- # Writing Skills From 2064fb64bce8e0914b2b1da788474b54b173dd08 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:49:52 +0100 Subject: [PATCH 02/24] refine: Simplify instructions for running grilling and domain modeling skills --- skills/engineering/grill-with-docs/SKILL.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index 634f7da..2686e19 100644 --- a/skills/engineering/grill-with-docs/SKILL.md +++ b/skills/engineering/grill-with-docs/SKILL.md @@ -4,7 +4,4 @@ description: Grilling session that also builds your project's domain model — s disable-model-invocation: true --- -Run the `/grilling` and `/domain-modeling` skills together: - -- Grill me about the plan one question at a time, walking each branch of the decision tree (`/grilling`). -- As domain terms and decisions surface, actively sharpen the language and update `CONTEXT.md` and ADRs inline (`/domain-modeling`). +Run a `/grilling` session, using the `/domain-modeling` skill. From cbf6db4233c7e4202abaf79643f7ab395c75a2df Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:50:55 +0100 Subject: [PATCH 03/24] refine: Update description for grill-me skill and adjust session instruction for clarity --- skills/productivity/grill-me/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/productivity/grill-me/SKILL.md b/skills/productivity/grill-me/SKILL.md index 7ea10d6..9470cfc 100644 --- a/skills/productivity/grill-me/SKILL.md +++ b/skills/productivity/grill-me/SKILL.md @@ -1,7 +1,7 @@ --- name: grill-me -description: Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. +description: A relentless interview to sharpen a plan or design. disable-model-invocation: true --- -Run the `/grilling` skill. +Run a `/grilling` session. From 0a4b76776dfd9979bfe013d99b5562a03b743839 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:51:24 +0100 Subject: [PATCH 04/24] refine: Add disable-model-invocation flag to edit-article skill for improved functionality --- skills/personal/edit-article/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/skills/personal/edit-article/SKILL.md b/skills/personal/edit-article/SKILL.md index b319b7c..2a6ad33 100644 --- a/skills/personal/edit-article/SKILL.md +++ b/skills/personal/edit-article/SKILL.md @@ -1,6 +1,7 @@ --- name: edit-article description: Edit and improve articles by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, or improve an article draft. +disable-model-invocation: true --- 1. First, divide the article into sections based on its headings. Think about the main points you want to make during those sections. From 7d3ada9716a9ee08d6c6f775d8a78ef889e1798f Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:51:43 +0100 Subject: [PATCH 05/24] refine: Remove caveman skill documentation to streamline productivity skills --- skills/productivity/caveman/SKILL.md | 46 ---------------------------- 1 file changed, 46 deletions(-) delete mode 100644 skills/productivity/caveman/SKILL.md diff --git a/skills/productivity/caveman/SKILL.md b/skills/productivity/caveman/SKILL.md deleted file mode 100644 index 9b0fc8b..0000000 --- a/skills/productivity/caveman/SKILL.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: caveman -description: Ultra-compressed communication mode — cuts token usage ~75% by dropping filler, articles, and pleasantries while keeping full technical accuracy. -disable-model-invocation: true ---- - -Respond terse like smart caveman. All technical substance stay. Only fluff die. - -## Persistence - -ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode". - -## Rules - -Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough. - -Technical terms stay exact. Code blocks unchanged. Errors quoted exact. - -Pattern: `[thing] [action] [reason]. [next step].` - -Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..." -Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:" - -### Examples - -**"Why React component re-render?"** - -> Inline obj prop -> new ref -> re-render. `useMemo`. - -**"Explain database connection pooling."** - -> Pool = reuse DB conn. Skip handshake -> fast under load. - -## Auto-Clarity Exception - -Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done. - -Example -- destructive op: - -> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone. -> -> ```sql -> DROP TABLE users; -> ``` -> -> Caveman resume. Verify backup exist first. From 0a8105bba99d8f1cbe3c460060ab70164046024b Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:51:56 +0100 Subject: [PATCH 06/24] refine: Remove caveman skill documentation to streamline productivity skills --- skills/productivity/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/skills/productivity/README.md b/skills/productivity/README.md index c53a097..5cdb585 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -6,7 +6,6 @@ General workflow tools, not code-specific. User-invoked entry points (`disable-model-invocation: true`). -- **[caveman](./caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. From 800201f7b2829ae7c0fe67dc94c72da772dac6c2 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:52:51 +0100 Subject: [PATCH 07/24] refine: Update description for grilling skill to enhance clarity and focus --- skills/productivity/grilling/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/productivity/grilling/SKILL.md b/skills/productivity/grilling/SKILL.md index 68c768e..24d1f82 100644 --- a/skills/productivity/grilling/SKILL.md +++ b/skills/productivity/grilling/SKILL.md @@ -1,6 +1,6 @@ --- name: grilling -description: Interview the user relentlessly about a plan or design until you reach shared understanding, walking each branch of the decision tree and resolving dependencies between decisions one at a time. Use when the user wants to stress-test a plan, get grilled on a design, pressure-test decisions before building, or when another skill needs a grilling loop. +description: Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases. --- Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. From 658d53e6ded8cc0eaa26a96e0580bee9381ca0e3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 16:53:42 +0100 Subject: [PATCH 08/24] Improved /grill-with-docs commit message --- skills/engineering/grill-with-docs/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/engineering/grill-with-docs/SKILL.md b/skills/engineering/grill-with-docs/SKILL.md index 2686e19..bed05d2 100644 --- a/skills/engineering/grill-with-docs/SKILL.md +++ b/skills/engineering/grill-with-docs/SKILL.md @@ -1,6 +1,6 @@ --- name: grill-with-docs -description: Grilling session that also builds your project's domain model — sharpens terminology and updates CONTEXT.md and ADRs inline as decisions crystallise. +description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. disable-model-invocation: true --- From 3832253f149ea165f45a32ea727886e6d0094d60 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Sun, 31 May 2026 17:40:53 +0100 Subject: [PATCH 09/24] The fewer seams, the better --- skills/engineering/to-prd/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/engineering/to-prd/SKILL.md b/skills/engineering/to-prd/SKILL.md index 6844b17..e5f1141 100644 --- a/skills/engineering/to-prd/SKILL.md +++ b/skills/engineering/to-prd/SKILL.md @@ -12,7 +12,7 @@ The issue tracker and triage label vocabulary should have been provided to you 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching. -2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. +2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one. Check with the user that these seams match their expectations. From 81ddacb08b3878d07ac4fa2de60bd8a53bacba5b Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 2 Jun 2026 21:07:31 +0100 Subject: [PATCH 10/24] refine: Add skill documentation for resolving merge conflicts --- .../engineering/resolving-merge-conflicts/SKILL.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 skills/engineering/resolving-merge-conflicts/SKILL.md diff --git a/skills/engineering/resolving-merge-conflicts/SKILL.md b/skills/engineering/resolving-merge-conflicts/SKILL.md new file mode 100644 index 0000000..aadb3fc --- /dev/null +++ b/skills/engineering/resolving-merge-conflicts/SKILL.md @@ -0,0 +1,14 @@ +--- +name: resolving-merge-conflicts +description: "Use when you need to resolve an in-progress git merge/rebase conflict." +--- + +1. **See the current state** of the merge/rebase. Check git history, and the conflicting files. + +2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets. + +3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`. + +4. Discover the project's **automated checks** and run them — typically typecheck, then tests, then format. Fix anything the merge broke. + +5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased. From 788b5c382b769155afcbac0d8402c3b56eae02fd Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 3 Jun 2026 12:46:28 +0100 Subject: [PATCH 11/24] Added prefactoring --- skills/engineering/to-issues/SKILL.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/engineering/to-issues/SKILL.md b/skills/engineering/to-issues/SKILL.md index 9b7dec9..333f1ee 100644 --- a/skills/engineering/to-issues/SKILL.md +++ b/skills/engineering/to-issues/SKILL.md @@ -20,16 +20,18 @@ Work from whatever is already in the conversation context. If the user passes an If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching. +Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change." + ### 3. Draft vertical slices Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer. -Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review. AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible. - + - Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests) - A completed slice is demoable or verifiable on its own -- Prefer many thin slices over few thick ones +- Any prefactoring should be done first + ### 4. Quiz the user @@ -37,7 +39,6 @@ Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an Present the proposed breakdown as a numbered list. For each slice, show: - **Title**: short descriptive name -- **Type**: HITL / AFK - **Blocked by**: which other slices (if any) must complete first - **User stories covered**: which user stories this addresses (if the source material has them) @@ -46,7 +47,6 @@ Ask the user: - Does the granularity feel right? (too coarse / too fine) - Are the dependency relationships correct? - Should any slices be merged or split further? -- Are the correct slices marked as HITL and AFK? Iterate until the user approves the breakdown. From ffb2fa662321045a8ace6f56f29ef8af11e19d3d Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 10 Jun 2026 14:11:53 +0100 Subject: [PATCH 12/24] feat: Add implement skill documentation for PRD-based work --- skills/engineering/implement/SKILL.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 skills/engineering/implement/SKILL.md diff --git a/skills/engineering/implement/SKILL.md b/skills/engineering/implement/SKILL.md new file mode 100644 index 0000000..384d2b6 --- /dev/null +++ b/skills/engineering/implement/SKILL.md @@ -0,0 +1,15 @@ +--- +name: implement +description: "Implement a piece of work based on a PRD or set of issues." +disable-model-invocation: true +--- + +Implement the work described by the user in the PRD or issues. + +Use /tdd where possible, at pre-agreed seams. + +Run typechecking regularly, single test files regularly, and the full test suite once at the end. + +Once done, use /review to review the work. + +Commit your work to the current branch. From ab7196a1584ac60688aeb63cf0b56a5114c4a6f3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Mon, 15 Jun 2026 13:30:21 +0100 Subject: [PATCH 13/24] feat: Add decision-mapping skill Adds a new engineering skill that turns loose ideas with many interdependent open decisions into a sequenced DAG of one-session investigation tickets, driving them to resolution one at a time. Sits at the front of the pipeline, before /to-prd. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/plugin.json | 1 + README.md | 1 + skills/engineering/README.md | 1 + skills/engineering/decision-mapping/SKILL.md | 103 +++++++++++++++++++ 4 files changed, 106 insertions(+) create mode 100644 skills/engineering/decision-mapping/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 679d479..413575f 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -13,6 +13,7 @@ "./skills/engineering/prototype", "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", + "./skills/engineering/decision-mapping", "./skills/productivity/caveman", "./skills/productivity/grill-me", "./skills/productivity/grilling", diff --git a/README.md b/README.md index 02fb10a..98bee05 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,7 @@ Skills I use daily for code work. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. +- **[decision-mapping](./skills/engineering/decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. ### Productivity diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 12c32a5..58e02a9 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -23,3 +23,4 @@ Model- or user-invocable (rich trigger phrasing so the model can reach for them) - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. +- **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. diff --git a/skills/engineering/decision-mapping/SKILL.md b/skills/engineering/decision-mapping/SKILL.md new file mode 100644 index 0000000..9812baf --- /dev/null +++ b/skills/engineering/decision-mapping/SKILL.md @@ -0,0 +1,103 @@ +--- +name: decision-mapping +description: Turn a loose idea with many interdependent open decisions into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. Use when the user's idea is too loose to plan in one sitting, there are many dependent design decisions, the user wants to map or sequence open decisions, plan prototyping or spike sessions, "plan the planning", or resume work on an existing decision map. +--- + +# Decision Mapping + +This skill bridges loose idea and actionable plan. When a concept has too many open, interdependent design decisions to grill to a conclusion in one session — some unresolvable by discussion alone, others blocked on spikes — it maps those decisions into a sequenced DAG of one-session investigation tickets, then drives them to resolution one at a time. + +It is the planning-phase mirror of `/to-issues`: `/to-issues` breaks a *stable* design into implementation tickets; this breaks a *loose* one into investigation tickets. It sits at the front of the pipeline, before `/to-prd`. + +## The decision map + +The decision map is a single compact Markdown file, one per planning effort, git-tracked alongside the project. It is the canonical artifact — the **whole map is loaded as context into every session**, so it must stay compact. + +### Structure + +Numbered entries ("tickets"), each its own section keyed by its number: + +```markdown +## 1. Should we use a relational or document store? + +blocked_by: [] + +**Question.** ... + +**Answer.** ... (once resolved) + +**Reasoning.** ... +``` + +Each ticket carries: + +- **Number** — unique, stable, never reused. +- **`blocked_by: [numbers]`** — the dependency edges, forming a DAG. Omit or leave empty when unblocked. +- **Free-form body** — the decision phrased as a question, and once resolved, the answer and reasoning. Keep it minimal but non-lossy. No rigid extra fields (no risk scores, no expiry fields). + +Each ticket must be sized to **one context-window session** — resolvable before the agent drifts out of the smart zone. Same sizing constraint as a Ticket in `/to-issues`. Each ticket owns its own section so parallel sessions editing different tickets produce clean diffs. + +## Two traversals + +**Breadth-first** — used to build or update the map. Fan across the frontier of open decisions. Resolve trivially-decidable ones inline. Tag the rest by how they'll be resolved: + +- **discuss** — run `/grilling` for a focused interview. +- **spike** — build throwaway code via `/prototype` to learn something the discussion can't settle. The build step may be delegated to a subagent. +- **defer** — record the question but mark it out-of-scope until a later session unlocks it. + +Do not descend into or resolve decisions deeply during breadth-first traversal. + +**Depth-first** — used inside a session to drive one ticket as far as it goes until its question resolves. Invoke `/grilling` for the interview itself. + +These compose: breadth-first to see the tree, depth-first to drive one node to ground. + +## Fog of war + +The map is *deliberately* incomplete beyond the frontier — only map as deep as the next spike, because a spike's outcome determines which decisions even exist downstream. + +Every session ends with a **re-map**: + +1. Record what the session resolved in the ticket's body. +2. Add newly-discovered tickets (with correct `blocked_by` edges). +3. Reopen any previously-resolved ticket the session invalidated, and propagate suspicion to anything `blocked_by` it. + +Never try to prove the map complete. The only validation target is that the **next session is correctly chosen**. + +## Invocation + +There is no auto-discovery. The user always points the skill at what to work on. + +### Bootstrap + +User invokes with a loose idea. + +1. Run breadth-first grilling (via `/grilling`) to surface the open decisions. +2. Write a new decision map — mostly fog, frontier identified, trivially-decidable entries resolved inline. +3. Stop. Map-building is one session's work; do not also resolve tickets. + +### Resume + +User invokes with a path to an existing map and a ticket number. + +1. Load the **whole map** as context. +2. Depth-first grill that ticket to resolution (via `/grilling`). +3. Write the answer and reasoning back into that ticket's section. +4. Re-map: add new tickets, reopen invalidated ones, update `blocked_by` edges. +5. Stop. + +The user picks the ticket. You may advise which tickets are currently unblocked, but do not choose. The process is entirely user-driven and never autonomous. + +A pair of independent (unblocked, non-overlapping) tickets may be run in parallel as separate sessions; any cross-cutting edits are a git merge the user reconciles. + +## Lifecycle + +``` +loose idea + → bootstrap map (this skill) + → resume sessions (this skill, one ticket per session) + → concept stabilises + → /to-prd absorbs the map + → /to-issues + → /implement + → map archived/deleted (durable conclusions now live in the PRD) +``` From bc4cf903ff4855ce23199a8dd3bf98b3dbd7ad71 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 13:45:28 +0100 Subject: [PATCH 14/24] Added writing-great-skills skill --- .claude-plugin/plugin.json | 2 +- README.md | 2 +- skills/engineering/decision-mapping/SKILL.md | 92 ++++----- skills/engineering/diagnosing-bugs/SKILL.md | 33 +++- skills/productivity/README.md | 2 +- skills/productivity/grilling/SKILL.md | 2 +- skills/productivity/write-a-skill/SKILL.md | 118 ------------ .../writing-great-skills/GLOSSARY.md | 175 ++++++++++++++++++ .../writing-great-skills/SKILL.md | 70 +++++++ 9 files changed, 310 insertions(+), 186 deletions(-) delete mode 100644 skills/productivity/write-a-skill/SKILL.md create mode 100644 skills/productivity/writing-great-skills/GLOSSARY.md create mode 100644 skills/productivity/writing-great-skills/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 413575f..174bcbc 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -19,6 +19,6 @@ "./skills/productivity/grilling", "./skills/productivity/handoff", "./skills/productivity/teach", - "./skills/productivity/write-a-skill" + "./skills/productivity/writing-great-skills" ] } diff --git a/README.md b/README.md index 98bee05..a23628b 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ General workflow tools, not code-specific. - **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./skills/productivity/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. -- **[write-a-skill](./skills/productivity/write-a-skill/SKILL.md)** — Create new skills with proper structure, progressive disclosure, and bundled resources. +- **[writing-great-skills](./skills/productivity/writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. **Skills** diff --git a/skills/engineering/decision-mapping/SKILL.md b/skills/engineering/decision-mapping/SKILL.md index 9812baf..50a63c0 100644 --- a/skills/engineering/decision-mapping/SKILL.md +++ b/skills/engineering/decision-mapping/SKILL.md @@ -1,77 +1,60 @@ --- name: decision-mapping -description: Turn a loose idea with many interdependent open decisions into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. Use when the user's idea is too loose to plan in one sitting, there are many dependent design decisions, the user wants to map or sequence open decisions, plan prototyping or spike sessions, "plan the planning", or resume work on an existing decision map. +description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. Use when the user's idea is too loose to plan in one sitting, they want to plan prototyping sessions, or resume work on an existing decision map. --- -# Decision Mapping +This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or discussion. -This skill bridges loose idea and actionable plan. When a concept has too many open, interdependent design decisions to grill to a conclusion in one session — some unresolvable by discussion alone, others blocked on spikes — it maps those decisions into a sequenced DAG of one-session investigation tickets, then drives them to resolution one at a time. - -It is the planning-phase mirror of `/to-issues`: `/to-issues` breaks a *stable* design into implementation tickets; this breaks a *loose* one into investigation tickets. It sits at the front of the pipeline, before `/to-prd`. - -## The decision map +## The Decision Map The decision map is a single compact Markdown file, one per planning effort, git-tracked alongside the project. It is the canonical artifact — the **whole map is loaded as context into every session**, so it must stay compact. +Assets created during tickets should be linked to from the map, not duplicated within it. + ### Structure Numbered entries ("tickets"), each its own section keyed by its number: ```markdown -## 1. Should we use a relational or document store? +## #1: Relational Or Non-Relational Database? -blocked_by: [] +Blocked by: #, # +Type: Research | Prototype | Discuss -**Question.** ... +### Question -**Answer.** ... (once resolved) + -**Reasoning.** ... +### Answer + + ``` -Each ticket carries: +Each ticket must be sized to one 100K token agent session. -- **Number** — unique, stable, never reused. -- **`blocked_by: [numbers]`** — the dependency edges, forming a DAG. Omit or leave empty when unblocked. -- **Free-form body** — the decision phrased as a question, and once resolved, the answer and reasoning. Keep it minimal but non-lossy. No rigid extra fields (no risk scores, no expiry fields). +## Ticket Types -Each ticket must be sized to **one context-window session** — resolvable before the agent drifts out of the smart zone. Same sizing constraint as a Ticket in `/to-issues`. Each ticket owns its own section so parallel sessions editing different tickets produce clean diffs. +There are three types of tickets: -## Two traversals - -**Breadth-first** — used to build or update the map. Fan across the frontier of open decisions. Resolve trivially-decidable ones inline. Tag the rest by how they'll be resolved: - -- **discuss** — run `/grilling` for a focused interview. -- **spike** — build throwaway code via `/prototype` to learn something the discussion can't settle. The build step may be delegated to a subagent. -- **defer** — record the question but mark it out-of-scope until a later session unlocks it. - -Do not descend into or resolve decisions deeply during breadth-first traversal. - -**Depth-first** — used inside a session to drive one ticket as far as it goes until its question resolves. Invoke `/grilling` for the interview itself. - -These compose: breadth-first to see the tree, depth-first to drive one node to ground. +- **Research**: Reading documentation, third-party API's, or local resources like knowledge bases. Creates a markdown summary as an asset. Use this when knowledge outside the current working directory is required. +- **Prototype**: Writing UI or logic code to test a hypothesis, or to explore a design space. Uses the /prototype skill. Creates a prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question. +- **Discuss**: Conversation with the agent. Uses the /grilling and /domain-modelling skills. The default case. ## Fog of war -The map is *deliberately* incomplete beyond the frontier — only map as deep as the next spike, because a spike's outcome determines which decisions even exist downstream. +The map is _deliberately_ incomplete beyond the frontier. Your job is to investigate the frontier, and to resolve tickets in order to push the frontier forward. Push back the fog of war, one node at a time. -Every session ends with a **re-map**: - -1. Record what the session resolved in the ticket's body. -2. Add newly-discovered tickets (with correct `blocked_by` edges). -3. Reopen any previously-resolved ticket the session invalidated, and propagate suspicion to anything `blocked_by` it. - -Never try to prove the map complete. The only validation target is that the **next session is correctly chosen**. +At some point, the fog of war should have been pushed back far enough that the path to the finish line is clear. At that point, no more tickets will be required and the decision map can be considered 'done'. ## Invocation -There is no auto-discovery. The user always points the skill at what to work on. +There are two ways this skill can be invoked: **bootstrap** and **resume**. ### Bootstrap User invokes with a loose idea. -1. Run breadth-first grilling (via `/grilling`) to surface the open decisions. +1. Run a /grilling and /domain-modelling session to surface the open decisions. 2. Write a new decision map — mostly fog, frontier identified, trivially-decidable entries resolved inline. 3. Stop. Map-building is one session's work; do not also resolve tickets. @@ -80,24 +63,21 @@ User invokes with a loose idea. User invokes with a path to an existing map and a ticket number. 1. Load the **whole map** as context. -2. Depth-first grill that ticket to resolution (via `/grilling`). -3. Write the answer and reasoning back into that ticket's section. -4. Re-map: add new tickets, reopen invalidated ones, update `blocked_by` edges. +2. Run a session to resolve the ticket, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modelling`. +3. Record what the session resolved in the ticket's body. +4. Add newly-discovered tickets (with correct `blocked_by` edges). 5. Stop. -The user picks the ticket. You may advise which tickets are currently unblocked, but do not choose. The process is entirely user-driven and never autonomous. +If the decisions made invalidate other parts of the map, update or delete those nodes. -A pair of independent (unblocked, non-overlapping) tickets may be run in parallel as separate sessions; any cross-cutting edits are a git merge the user reconciles. +## Parallelism -## Lifecycle +The user may choose to run tickets in parallel, so expect other agents to make changes to the map. -``` -loose idea - → bootstrap map (this skill) - → resume sessions (this skill, one ticket per session) - → concept stabilises - → /to-prd absorbs the map - → /to-issues - → /implement - → map archived/deleted (durable conclusions now live in the PRD) -``` +## Skipping The Decision Map + +Many times, the initial grilling will result in no fog of war. No unresolved tickets. Nothing to do, except implement. + +In those situations, you should offer the user the chance to skip the decision map - since the decision map is only needed if multi-session decisions need to be made. + +If they skip it, you should recommend either implementing directly or using `/to-prd` to schedule a multi-session implementation. diff --git a/skills/engineering/diagnosing-bugs/SKILL.md b/skills/engineering/diagnosing-bugs/SKILL.md index 31b3cda..1ef97c2 100644 --- a/skills/engineering/diagnosing-bugs/SKILL.md +++ b/skills/engineering/diagnosing-bugs/SKILL.md @@ -11,7 +11,7 @@ When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear men ## Phase 1 — Build a feedback loop -**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you. +**This is the skill.** Everything else is mechanical. If you have a **tight** pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause; bisection, hypothesis-testing, and instrumentation all just consume it. If you don't have one, no amount of staring at code will save you. Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.** @@ -30,15 +30,15 @@ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give Build the right feedback loop, and the bug is 90% fixed. -### Iterate on the loop itself +### Tighten the loop -Treat the loop as a product. Once you have _a_ loop, ask: +Treat the loop as a product. Once you have _a_ loop, **tighten** it: - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.) - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".) - Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.) -A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower. +A 30-second flaky loop is barely better than no loop; a 2-second deterministic one is tight — a debugging superpower. ### Non-deterministic bugs @@ -48,11 +48,20 @@ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigg Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop. -Do not proceed to Phase 2 until you have a loop you believe in. +### Completion criterion — a tight loop that goes red -## Phase 2 — Reproduce +Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is: -Run the loop. Watch the bug appear. +- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_. +- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above). +- [ ] **Fast** — seconds, not minutes. +- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`. + +If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2. + +## Phase 2 — Reproduce + minimise + +Run the loop. Watch it go red — the bug appears. Confirm: @@ -60,7 +69,15 @@ Confirm: - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against). - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it. -Do not proceed until you reproduce the bug. +### Minimise + +Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure. + +Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5. + +Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green. + +Do not proceed until you have reproduced **and** minimised. ## Phase 3 — Hypothesise diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 5cdb585..570dab3 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -9,7 +9,7 @@ User-invoked entry points (`disable-model-invocation: true`). - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. -- **[write-a-skill](./write-a-skill/SKILL.md)** — Create new skills with proper structure, progressive disclosure, and bundled resources. +- **[writing-great-skills](./writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. ## Skills diff --git a/skills/productivity/grilling/SKILL.md b/skills/productivity/grilling/SKILL.md index 24d1f82..fe3569d 100644 --- a/skills/productivity/grilling/SKILL.md +++ b/skills/productivity/grilling/SKILL.md @@ -5,6 +5,6 @@ description: Interview the user relentlessly about a plan or design. Use when th Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. -Ask the questions one at a time, waiting for feedback on each question before continuing. +Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. If a question can be answered by exploring the codebase, explore the codebase instead. diff --git a/skills/productivity/write-a-skill/SKILL.md b/skills/productivity/write-a-skill/SKILL.md deleted file mode 100644 index 4f085e5..0000000 --- a/skills/productivity/write-a-skill/SKILL.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -name: write-a-skill -description: Create a new agent skill with proper structure, progressive disclosure, and bundled resources. -disable-model-invocation: true ---- - -# Writing Skills - -## Process - -1. **Gather requirements** - ask user about: - - What task/domain does the skill cover? - - What specific use cases should it handle? - - Does it need executable scripts or just instructions? - - Any reference materials to include? - -2. **Draft the skill** - create: - - SKILL.md with concise instructions - - Additional reference files if content exceeds 500 lines - - Utility scripts if deterministic operations needed - -3. **Review with user** - present draft and ask: - - Does this cover your use cases? - - Anything missing or unclear? - - Should any section be more/less detailed? - -## Skill Structure - -``` -skill-name/ -├── SKILL.md # Main instructions (required) -├── REFERENCE.md # Detailed docs (if needed) -├── EXAMPLES.md # Usage examples (if needed) -└── scripts/ # Utility scripts (if needed) - └── helper.js -``` - -## SKILL.md Template - -```md ---- -name: skill-name -description: Brief description of capability. Use when [specific triggers]. ---- - -# Skill Name - -## Quick start - -[Minimal working example] - -## Workflows - -[Step-by-step processes with checklists for complex tasks] - -## Advanced features - -[Link to separate files: See [REFERENCE.md](REFERENCE.md)] -``` - -## Description Requirements - -The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request. - -**Goal**: Give your agent just enough info to know: - -1. What capability this skill provides -2. When/why to trigger it (specific keywords, contexts, file types) - -**Format**: - -- Max 1024 chars -- Write in third person -- First sentence: what it does -- Second sentence: "Use when [specific triggers]" - -**Good example**: - -``` -Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction. -``` - -**Bad example**: - -``` -Helps with documents. -``` - -The bad example gives your agent no way to distinguish this from other document skills. - -## When to Add Scripts - -Add utility scripts when: - -- Operation is deterministic (validation, formatting) -- Same code would be generated repeatedly -- Errors need explicit handling - -Scripts save tokens and improve reliability vs generated code. - -## When to Split Files - -Split into separate files when: - -- SKILL.md exceeds 100 lines -- Content has distinct domains (finance vs sales schemas) -- Advanced features are rarely needed - -## Review Checklist - -After drafting, verify: - -- [ ] Description includes triggers ("Use when...") -- [ ] SKILL.md under 100 lines -- [ ] No time-sensitive info -- [ ] Consistent terminology -- [ ] Concrete examples included -- [ ] References one level deep diff --git a/skills/productivity/writing-great-skills/GLOSSARY.md b/skills/productivity/writing-great-skills/GLOSSARY.md new file mode 100644 index 0000000..83af665 --- /dev/null +++ b/skills/productivity/writing-great-skills/GLOSSARY.md @@ -0,0 +1,175 @@ +# Glossary — Building Great Skills + +The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; every term below is a lever on that goal. This is the disclosed reference for [`writing-great-skills`](SKILL.md). + +**Bold terms** in any definition are themselves defined in this glossary; find them by their heading. + +## Language + +### Predictability + +The degree to which a skill makes the agent behave the same *way* on every run — the same process, not the same output (a brainstorming skill should *predictably* diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals. + +_Avoid_: consistency, reliability, robustness, output-determinism + +### Model-Invoked + +A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always *includes* user reach. There is no model-only state: a description only ever *adds* agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load. + +_Avoid_: ability, tool, capability + +### User-Invoked + +A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-*only*, where **model-invoked** is user-*and-agent*). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it. + +_Avoid_: procedure, workflow, command + +### Description + +The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence *is* the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**. + +_Avoid_: frontmatter, summary + +### Context Pointer + +A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides *when* the agent reaches — and *how reliably*. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails. + +_Avoid_: link, reference, import + +### Context Load + +The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills. + +_Avoid_: token cost, context bloat + +### Cognitive Load + +The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not. + +_Avoid_: human index, burden, overhead + +### Granularity + +How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion. + +_Avoid_: chunking, modularity + +### Router Skill + +A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply. + +_Avoid_: dispatcher, menu, registry, index, router procedure + +### Information Hierarchy + +A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs: + +- **Steps** — in-file, primary +- **Reference**, in-file — secondary +- **Reference**, disclosed — behind a **context pointer** + +A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can. + +_Avoid_: structure, organization, layout + +### Branch + +A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none. + +_Avoid_: path, case, fork + +### Progressive Disclosure + +Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails. + +_Avoid_: lazy loading, chunking + +### Steps + +The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague. + +_Avoid_: workflow, instructions, choreography + +### Completion Criterion + +The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs *steps* to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is *not* step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive. + +_Avoid_: done condition, exit condition, stopping rule + +### Post-Completion Steps + +The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two. + +_Avoid_: horizon, fog of war, lookahead + +### Legwork + +The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short. + +_Avoid_: scope, effort, diligence, coverage + +### Reference + +Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**. + +_Avoid_: supporting material, docs, background + +### External Reference + +**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other. + +_Avoid_: doc, resource, knowledge base + +### Leading Word + +A compact concept — also called a *Leitwort* — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first. + +A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill. + +_Avoid_: keyword, term, motif + +### Single Source of Truth + +The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation. + +_Avoid_: home, canonical location + +### Relevance + +Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour. + +_Avoid_: load-bearing, staleness, freshness + +## Failure Modes + +### Premature Completion + +Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy *and* you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion. + +_Avoid_: premature closure, the rush, rushing, shortcutting + +### Duplication + +The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning. + +_Avoid_: repetition, redundancy + +### Sediment + +Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning. + +_Avoid_: accretion, bloat, cruft, rot + +### Sprawl + +A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause. + +_Avoid_: bloat, length, size, verbosity + +### No-Op + +An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless. + +A leading word is a *technique*; No-Op is a *verdict* on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate. + +_Avoid_: redundant instruction, restating the obvious, belaboring diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md new file mode 100644 index 0000000..4669bea --- /dev/null +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -0,0 +1,70 @@ +--- +name: writing-great-skills +description: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. +disable-model-invocation: true +--- + +A skill exists to wrangle determinism out of a stochastic system. **Predictability** — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it. + +**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning. + +## Invocation + +Two choices, trading different costs: + +- A **model-invoked** skill keeps a **description**, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to **context load** — the description sits in the window every turn. Mechanics: omit `disable-model-invocation`, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…"). +- A **user-invoked** skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends **cognitive load**: _you_ are the index that must remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` becomes human-facing — a one-line summary, trigger lists stripped. + +Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load. + +When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each. + +## Information hierarchy + +A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material: + +1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a **completion criterion**, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites **premature completion**. +2. **In-skill reference** — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._ +3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully **external reference** that lives outside the skill system and any skill can point at.) + +A demanding completion criterion drives thorough **legwork** — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence. + +Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision. + +**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material. + +## When to split + +**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts: + +- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to be worth it. +- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view encourages the agent to do more **legwork** on the current task. + +## Pruning + +Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. + +Check every line for **relevance**: does it still bear on what the skill does? + +## Leading words + +A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. + +It serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word appears. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably. + +Hunt for opportunities to refactor skills to use leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. Examples include: + +- "fast, deterministic, low-overhead" -> _tight_ — one quality restated across a phase — into a single pretrained word (a _tight_ loop). +- "a loop you believe in" -> _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't). + +You win twice over: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them. + +## Failure modes + +Use these to diagnose issues the user may be having with the skill. + +- **Premature completion** — ending a step before it's genuinely done, attention slipping to _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it is irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut). +- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank. +- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline. +- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs. +- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique. From 801a01cc7d265e06dd9dbcef5a4c471add05a0b3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:18:05 +0100 Subject: [PATCH 15/24] refine: Update terminology from Commands/Skills to User-invoked/Model-invoked and enhance documentation --- CLAUDE.md | 4 ++-- README.md | 10 +++++----- docs/commands-vs-skills.md | 16 ---------------- docs/invocation.md | 18 ++++++++++++++++++ skills/engineering/README.md | 8 ++++---- skills/productivity/README.md | 8 ++++---- .../writing-great-skills/GLOSSARY.md | 6 ++++++ .../productivity/writing-great-skills/SKILL.md | 2 ++ 8 files changed, 41 insertions(+), 31 deletions(-) delete mode 100644 docs/commands-vs-skills.md create mode 100644 docs/invocation.md diff --git a/CLAUDE.md b/CLAUDE.md index 3899085..53c86e9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,6 @@ Every skill in `engineering/`, `productivity/`, or `misc/` must have a reference Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. -Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. +Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. -Every `SKILL.md` is either a command (always user-invoked, `disable-model-invocation: true`) or a skill (model- or user-invocable). For the full definitions, description conventions, and the rule that commands invoke skills but never commands, see [docs/commands-vs-skills.md](./docs/commands-vs-skills.md). +Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md). diff --git a/README.md b/README.md index a23628b..672320b 100644 --- a/README.md +++ b/README.md @@ -142,13 +142,13 @@ Software engineering fundamentals matter more than ever. These skills are my bes ## Reference -These come in two flavours. **Commands** are always user-invoked (you type `/grill-me`); their job is to orchestrate. **Skills** can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A command may invoke skills, but never another command. +These split on one axis — who can invoke them. **User-invoked** skills are reachable only when you type them (e.g. `/grill-me`); their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one. ### Engineering Skills I use daily for code work. -**Commands** +**User-invoked** - **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. @@ -159,7 +159,7 @@ Skills I use daily for code work. - **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers on an unfamiliar section of code. - **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. -**Skills** +**Model-invoked** - **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. @@ -171,7 +171,7 @@ Skills I use daily for code work. General workflow tools, not code-specific. -**Commands** +**User-invoked** - **[caveman](./skills/productivity/caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. @@ -179,7 +179,7 @@ General workflow tools, not code-specific. - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[writing-great-skills](./skills/productivity/writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. -**Skills** +**Model-invoked** - **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. The reusable loop behind `grill-me` and `grill-with-docs`. diff --git a/docs/commands-vs-skills.md b/docs/commands-vs-skills.md deleted file mode 100644 index b6bb8e3..0000000 --- a/docs/commands-vs-skills.md +++ /dev/null @@ -1,16 +0,0 @@ -# Commands vs skills - -Every `SKILL.md` in this repo is one of two kinds. The test for "is it a skill" is: _could the model usefully reach for this autonomously?_ Reuse is the reason to extract a skill, not the test. - -- **Command** — _always_ user-invoked. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…") from command descriptions. A command may invoke skills, but **never another command**. -- **Skill** — invocable by **model or user**. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. Do not set `disable-model-invocation`. - -Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. - -## Dependencies between them - -Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. - -## Passive vs active domain work - -Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/docs/invocation.md b/docs/invocation.md new file mode 100644 index 0000000..c434516 --- /dev/null +++ b/docs/invocation.md @@ -0,0 +1,18 @@ +# Model-invoked vs user-invoked + +Every `SKILL.md` in this repo is a skill. The one axis that splits them is **invocation** — who can reach it: + +- **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…"). +- **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.) + +Because a user-invoked skill has no description, nothing but the human can reach it — no other skill can fire it. So a user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill. + +Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. + +## Dependencies between them + +Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. + +## Passive vs active domain work + +Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 58e02a9..bdec4f2 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -2,9 +2,9 @@ Skills I use daily for code work. -## Commands +## User-invoked -User-invoked entry points (`disable-model-invocation: true`). +Reachable only when you type them (`disable-model-invocation: true`). - **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. @@ -15,9 +15,9 @@ User-invoked entry points (`disable-model-invocation: true`). - **[zoom-out](./zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers. - **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype — a runnable terminal app for state/logic questions, or several toggleable UI variations. -## Skills +## Model-invoked -Model- or user-invocable (rich trigger phrasing so the model can reach for them). +Model- or user-reachable (rich trigger phrasing so the model can reach for them). - **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 570dab3..e98607d 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -2,17 +2,17 @@ General workflow tools, not code-specific. -## Commands +## User-invoked -User-invoked entry points (`disable-model-invocation: true`). +Reachable only when you type them (`disable-model-invocation: true`). - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[writing-great-skills](./writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. -## Skills +## Model-invoked -Model- or user-invocable (rich trigger phrasing so the model can reach for them). +Model- or user-reachable (rich trigger phrasing so the model can reach for them). - **[grilling](./grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. diff --git a/skills/productivity/writing-great-skills/GLOSSARY.md b/skills/productivity/writing-great-skills/GLOSSARY.md index 83af665..665cf07 100644 --- a/skills/productivity/writing-great-skills/GLOSSARY.md +++ b/skills/productivity/writing-great-skills/GLOSSARY.md @@ -72,6 +72,12 @@ A skill with no **steps** uses just the bottom two rungs — often a legitimatel _Avoid_: structure, organization, layout +### Co-location + +Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks *how far down* a piece sits; co-location decides *what sits beside it* once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many. + +_Avoid_: grouping, clustering, cohesion + ### Branch A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none. diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md index 4669bea..cd46075 100644 --- a/skills/productivity/writing-great-skills/SKILL.md +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -33,6 +33,8 @@ Push too little down and the top bloats; push too much and you hide material the **Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material. +Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. + ## When to split **Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts: From e112a6b03cd7893a36760fea1d387dffa6cba80a Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:19:52 +0100 Subject: [PATCH 16/24] Remove zoom-out skill and all references Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/plugin.json | 1 - README.md | 2 -- ...01-explicit-setup-pointer-only-for-hard-dependencies.md | 2 +- skills/engineering/README.md | 1 - skills/engineering/zoom-out/SKILL.md | 7 ------- 5 files changed, 1 insertion(+), 12 deletions(-) delete mode 100644 skills/engineering/zoom-out/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 174bcbc..fdf6f50 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -9,7 +9,6 @@ "./skills/engineering/tdd", "./skills/engineering/to-issues", "./skills/engineering/to-prd", - "./skills/engineering/zoom-out", "./skills/engineering/prototype", "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", diff --git a/README.md b/README.md index 672320b..ba5ea70 100644 --- a/README.md +++ b/README.md @@ -132,7 +132,6 @@ For debugging, I've also built a **[`/diagnosing-bugs`](./skills/engineering/dia This is built in to every layer of these skills: - [`/to-prd`](./skills/engineering/to-prd/SKILL.md) quizzes you about which modules you're touching before creating a PRD -- [`/zoom-out`](./skills/engineering/zoom-out/SKILL.md) tells the agent to explain code in the context of the whole system And crucially, [`/improve-codebase-architecture`](./skills/engineering/improve-codebase-architecture/SKILL.md) helps you rescue a codebase that has become a ball of mud. I recommend running it on your codebase once every few days. @@ -156,7 +155,6 @@ Skills I use daily for code work. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. - **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. - **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. -- **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers on an unfamiliar section of code. - **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. **Model-invoked** diff --git a/docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md b/docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md index 7636786..37918f9 100644 --- a/docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md +++ b/docs/adr/0001-explicit-setup-pointer-only-for-hard-dependencies.md @@ -5,6 +5,6 @@ Engineering skills depend on per-repo config (issue tracker, triage label vocabu We split these into **hard-dependency** and **soft-dependency** skills: - **Hard dependency** (`to-issues`, `to-prd`, `triage`) — include an explicit one-liner: _"… should have been provided to you — run `/setup-matt-pocock-skills` if not."_ Without the mapping, output is wrong, not just fuzzy. -- **Soft dependency** (`diagnose`, `tdd`, `improve-codebase-architecture`, `zoom-out`) — reference "the project's domain glossary" and "ADRs in the area you're touching" in vague prose only. If the docs aren't there, the skill still works; output is just less sharp. +- **Soft dependency** (`diagnose`, `tdd`, `improve-codebase-architecture`) — reference "the project's domain glossary" and "ADRs in the area you're touching" in vague prose only. If the docs aren't there, the skill still works; output is just less sharp. The split keeps soft-dependency skills token-light and avoids cargo-culting the setup pointer into places where it isn't load-bearing. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index bdec4f2..444cb43 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -12,7 +12,6 @@ Reachable only when you type them (`disable-model-invocation: true`). - **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. - **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. - **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. -- **[zoom-out](./zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers. - **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype — a runnable terminal app for state/logic questions, or several toggleable UI variations. ## Model-invoked diff --git a/skills/engineering/zoom-out/SKILL.md b/skills/engineering/zoom-out/SKILL.md deleted file mode 100644 index 8cc007c..0000000 --- a/skills/engineering/zoom-out/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: zoom-out -description: Ask the agent to zoom out a level and map the relevant modules and callers using the project's domain language. -disable-model-invocation: true ---- - -I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary. From 2e647324f90f36b4c8ef8cbca0bbda89b2a82434 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:29:34 +0100 Subject: [PATCH 17/24] =?UTF-8?q?refine:=20Tighten=20review=20skill=20?= =?UTF-8?q?=E2=80=94=20fail-fast=20ref=20check,=20single-sourced=20rules,?= =?UTF-8?q?=20no-op=20cuts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Validate the fixed point resolves and diff is non-empty before spawning sub-agents - Single-source the tooling-enforced and two-axis rationale (point to Why two axes) - Fix rerank contradiction: summarize worst issue per axis, not across axes - Drop dead "Read X, then read the diff" preambles from both briefs Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/in-progress/review/SKILL.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/skills/in-progress/review/SKILL.md b/skills/in-progress/review/SKILL.md index 7507a36..e6c4001 100644 --- a/skills/in-progress/review/SKILL.md +++ b/skills/in-progress/review/SKILL.md @@ -22,6 +22,8 @@ Whatever the user said is the fixed point — a commit SHA, branch name, tag, `m Capture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`. +Before going further, confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents. + ### 2. Identify the spec source Look for the originating spec, in this order: @@ -33,16 +35,7 @@ Look for the originating spec, in this order: ### 3. Identify the standards sources -Anything in the repo that documents how code should be written. Common locations: - -- `CLAUDE.md`, `AGENTS.md` -- `CONTRIBUTING.md` -- `CONTEXT.md`, `CONTEXT-MAP.md`, per-context `CONTEXT.md` files -- `docs/adr/` (architectural decisions are standards) -- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json` (machine-enforced standards — note them but don't re-check what tooling already checks) -- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`, or similar at the repo root or under `docs/` - -Collect the list of files. The **Standards** sub-agent will read them. +Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`. ### 4. Spawn both sub-agents in parallel @@ -52,21 +45,21 @@ Send a single message with two `Agent` tool calls. Use the `general-purpose` sub - The full diff command and commit list. - The list of standards-source files you found in step 3. -- The brief: "Read the standards docs. Then read the diff. Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." +- The brief: "Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." **Spec sub-agent prompt** — include: - The diff command and commit list. - The path or fetched contents of the spec. -- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words." +- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words." If the spec is missing, skip the Spec sub-agent and note this in the final report. ### 5. Aggregate -Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate so the user can see them independently. +Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see *Why two axes*). -End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged. +End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent. ## Why two axes From aa7ed40cbe9dfc863e5ec52bb1415fc8eaf2b729 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:33:42 +0100 Subject: [PATCH 18/24] refine: Make writing-great-skills hunt no-ops at the sentence level MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a Pruning directive to run the no-op test sentence by sentence and delete whole failing sentences rather than trim words. References the existing no-op test as single source of truth — no restated definition. Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/productivity/writing-great-skills/SKILL.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md index cd46075..beae64e 100644 --- a/skills/productivity/writing-great-skills/SKILL.md +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -48,6 +48,8 @@ Keep each meaning in a **single source of truth**: one authoritative place, so c Check every line for **relevance**: does it still bear on what the skill does? +Then hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails, delete the whole sentence rather than trim words from it. Be aggressive — most prose that fails should go, not be rewritten. + ## Leading words A **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated throughout the text (though not necessarily - a strong leading word might only be needed once), it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds. From df129fcfce610712a737fe4bb9362e621f0752c5 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:45:47 +0100 Subject: [PATCH 19/24] refine: Add 'ask-matt' skill and update documentation for user-invoked skills --- .claude-plugin/plugin.json | 1 + README.md | 1 + skills/engineering/README.md | 1 + skills/engineering/ask-matt/SKILL.md | 59 ++++++++++++++++++++++++++++ skills/in-progress/review/SKILL.md | 6 +-- 5 files changed, 64 insertions(+), 4 deletions(-) create mode 100644 skills/engineering/ask-matt/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index fdf6f50..82b7fb3 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,7 @@ { "name": "mattpocock-skills", "skills": [ + "./skills/engineering/ask-matt", "./skills/engineering/diagnosing-bugs", "./skills/engineering/grill-with-docs", "./skills/engineering/triage", diff --git a/README.md b/README.md index ba5ea70..147403b 100644 --- a/README.md +++ b/README.md @@ -149,6 +149,7 @@ Skills I use daily for code work. **User-invoked** +- **[ask-matt](./skills/engineering/ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. - **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./skills/engineering/improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 444cb43..21bace5 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -6,6 +6,7 @@ Skills I use daily for code work. Reachable only when you type them (`disable-model-invocation: true`). +- **[ask-matt](./ask-matt/SKILL.md)** — Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. - **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. - **[improve-codebase-architecture](./improve-codebase-architecture/SKILL.md)** — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md new file mode 100644 index 0000000..3d6be69 --- /dev/null +++ b/skills/engineering/ask-matt/SKILL.md @@ -0,0 +1,59 @@ +--- +name: ask-matt +description: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo. +disable-model-invocation: true +--- + +# Ask Matt + +You don't remember every skill, so ask. Describe where you are — "I've got a vague idea", "bugs are piling up", "this code's a mess" — and this answers with the **flow** to follow and the skill to type next. + +A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone. + +## The main flow: idea → ship + +The route most work travels. You have an idea and want it built. + +1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.) +2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions): + - **`/handoff`** out, then open a fresh session against that file, + - **`/prototype`** to answer the question with throwaway code, + - **`/handoff`** back what you learned, and reference it from the original idea thread. +3. **Branch — is this a multi-session build?** + - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues) → **`/implement`** the issues one by one, each in its own agent. + - **No** → **`/implement`** right here, in the same context window. + +### Context hygiene + +Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue. + +The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread. + +## On-ramps + +A starting situation that generates work, then merges onto the main flow. + +- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up. + +## Codebase health + +Not feature work — upkeep. + +- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one *generates an idea* you can take into the main flow at `/grill-with-docs`. + +## Crossing sessions + +- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**. +- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues. + +## Standalone + +Off the main flow entirely. + +- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo. +- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace. +- **`/writing-great-skills`** — reference for writing and editing skills well. + +## Precondition + +**`/setup-matt-pocock-skills`** — run once per repo before any engineering flow. It configures the issue tracker, triage labels, and doc layout the other skills assume. diff --git a/skills/in-progress/review/SKILL.md b/skills/in-progress/review/SKILL.md index e6c4001..63e71f3 100644 --- a/skills/in-progress/review/SKILL.md +++ b/skills/in-progress/review/SKILL.md @@ -3,8 +3,6 @@ name: review description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". --- -# Review - Two-axis review of the diff between `HEAD` and a fixed point the user supplies: - **Standards** — does the code conform to this repo's documented coding standards? @@ -18,7 +16,7 @@ The issue tracker should have been provided to you — run `/setup-matt-pocock-s ### 1. Pin the fixed point -Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what — a branch, a commit, or `main`?" Don't proceed until you have it. +Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it. Capture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`. @@ -57,7 +55,7 @@ If the spec is missing, skip the Spec sub-agent and note this in the final repor ### 5. Aggregate -Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see *Why two axes*). +Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_). End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent. From 48f3d31fef07afef4b02fa3c822a4ee55ce6c1e0 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:53:11 +0100 Subject: [PATCH 20/24] refine: Clarify multi-session build process and enhance triage guidance in 'ask-matt' skill documentation --- skills/engineering/ask-matt/SKILL.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 3d6be69..7736669 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -20,7 +20,7 @@ The route most work travels. You have an idea and want it built. - **`/prototype`** to answer the question with throwaway code, - **`/handoff`** back what you learned, and reference it from the original idea thread. 3. **Branch — is this a multi-session build?** - - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues) → **`/implement`** the issues one by one, each in its own agent. + - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on. - **No** → **`/implement`** right here, in the same context window. ### Context hygiene @@ -35,11 +35,13 @@ A starting situation that generates work, then merges onto the main flow. - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up. + Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**. + ## Codebase health Not feature work — upkeep. -- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one *generates an idea* you can take into the main flow at `/grill-with-docs`. +- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. ## Crossing sessions @@ -56,4 +58,4 @@ Off the main flow entirely. ## Precondition -**`/setup-matt-pocock-skills`** — run once per repo before any engineering flow. It configures the issue tracker, triage labels, and doc layout the other skills assume. +**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work. From 245e31bbbd2e91a35e3f683166ce70c12d06b8ef Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:56:08 +0100 Subject: [PATCH 21/24] refine: Remove 'caveman' skill and update documentation accordingly --- .claude-plugin/plugin.json | 1 - README.md | 1 - 2 files changed, 2 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 82b7fb3..a509de5 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -14,7 +14,6 @@ "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", "./skills/engineering/decision-mapping", - "./skills/productivity/caveman", "./skills/productivity/grill-me", "./skills/productivity/grilling", "./skills/productivity/handoff", diff --git a/README.md b/README.md index 147403b..fb1fea1 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,6 @@ General workflow tools, not code-specific. **User-invoked** -- **[caveman](./skills/productivity/caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./skills/productivity/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. From 460f19f240ea3677dc6ac7a5dba9c8050e0b7bfc Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:57:25 +0100 Subject: [PATCH 22/24] refine: Simplify description in 'ask-matt' skill documentation --- skills/engineering/ask-matt/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 7736669..4c71d22 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -6,7 +6,7 @@ disable-model-invocation: true # Ask Matt -You don't remember every skill, so ask. Describe where you are — "I've got a vague idea", "bugs are piling up", "this code's a mess" — and this answers with the **flow** to follow and the skill to type next. +You don't remember every skill, so ask. A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone. From ee8bae40062cd6b435073368ed0c540f48c35862 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 15:15:11 +0100 Subject: [PATCH 23/24] Reduced description lengths --- .claude-plugin/plugin.json | 1 - README.md | 1 - skills/engineering/README.md | 1 - skills/engineering/codebase-design/SKILL.md | 2 +- skills/engineering/diagnosing-bugs/SKILL.md | 2 +- skills/engineering/domain-modeling/SKILL.md | 2 +- skills/engineering/tdd/SKILL.md | 2 +- skills/in-progress/README.md | 1 + .../decision-mapping/SKILL.md | 3 ++- skills/productivity/writing-great-skills/SKILL.md | 8 ++++++++ 10 files changed, 15 insertions(+), 8 deletions(-) rename skills/{engineering => in-progress}/decision-mapping/SKILL.md (94%) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a509de5..41c5e54 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -13,7 +13,6 @@ "./skills/engineering/prototype", "./skills/engineering/domain-modeling", "./skills/engineering/codebase-design", - "./skills/engineering/decision-mapping", "./skills/productivity/grill-me", "./skills/productivity/grilling", "./skills/productivity/handoff", diff --git a/README.md b/README.md index fb1fea1..0ba0078 100644 --- a/README.md +++ b/README.md @@ -164,7 +164,6 @@ Skills I use daily for code work. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. -- **[decision-mapping](./skills/engineering/decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. ### Productivity diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 21bace5..76d6416 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -23,4 +23,3 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them) - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. -- **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of one-session investigation tickets, then drive them to resolution one at a time. diff --git a/skills/engineering/codebase-design/SKILL.md b/skills/engineering/codebase-design/SKILL.md index db1f10a..16620c2 100644 --- a/skills/engineering/codebase-design/SKILL.md +++ b/skills/engineering/codebase-design/SKILL.md @@ -1,6 +1,6 @@ --- name: codebase-design -description: Shared discipline and vocabulary for designing deep modules — a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, choose between interface alternatives, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. +description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary. --- # Codebase Design diff --git a/skills/engineering/diagnosing-bugs/SKILL.md b/skills/engineering/diagnosing-bugs/SKILL.md index 1ef97c2..f400de7 100644 --- a/skills/engineering/diagnosing-bugs/SKILL.md +++ b/skills/engineering/diagnosing-bugs/SKILL.md @@ -1,6 +1,6 @@ --- name: diagnosing-bugs -description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression. +description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow. --- # Diagnosing Bugs diff --git a/skills/engineering/domain-modeling/SKILL.md b/skills/engineering/domain-modeling/SKILL.md index 221af0d..d0f7e1a 100644 --- a/skills/engineering/domain-modeling/SKILL.md +++ b/skills/engineering/domain-modeling/SKILL.md @@ -1,6 +1,6 @@ --- name: domain-modeling -description: Actively build and sharpen a project's domain model while you design — challenge fuzzy or conflicting terms against the glossary, stress-test concepts with concrete edge-case scenarios, cross-check claims against the code, and update CONTEXT.md and ADRs inline as decisions crystallise. Use when the user wants to refine domain terminology, build a ubiquitous language, pin down what a term really means, record a hard-won architectural decision, or when another skill needs to actively maintain the domain model. +description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. --- # Domain Modeling diff --git a/skills/engineering/tdd/SKILL.md b/skills/engineering/tdd/SKILL.md index 54f4862..1ce5d21 100644 --- a/skills/engineering/tdd/SKILL.md +++ b/skills/engineering/tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: tdd -description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development. +description: Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests. --- # Test-Driven Development diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index eda3fe3..169809f 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -2,6 +2,7 @@ Skills that are still being developed. They're not ready to ship — expect rough edges, breaking changes, and abandoned experiments. They're excluded from the plugin and the top-level README until they graduate to a stable bucket. +- **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. User-invoked. - **[review](./review/SKILL.md)** — Review changes since a fixed point along two parallel axes: **Standards** (does the diff follow the repo's coding standards?) and **Spec** (does the diff faithfully implement the originating issue/PRD?). - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end. - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. diff --git a/skills/engineering/decision-mapping/SKILL.md b/skills/in-progress/decision-mapping/SKILL.md similarity index 94% rename from skills/engineering/decision-mapping/SKILL.md rename to skills/in-progress/decision-mapping/SKILL.md index 50a63c0..0c42714 100644 --- a/skills/engineering/decision-mapping/SKILL.md +++ b/skills/in-progress/decision-mapping/SKILL.md @@ -1,6 +1,7 @@ --- name: decision-mapping -description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. Use when the user's idea is too loose to plan in one sitting, they want to plan prototyping sessions, or resume work on an existing decision map. +description: Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. +disable-model-invocation: true --- This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or discussion. diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md index beae64e..61abad4 100644 --- a/skills/productivity/writing-great-skills/SKILL.md +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -19,6 +19,14 @@ Pick model-invocation only when the agent must reach the skill on its own, or an When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each. +## Writing the description + +A model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word increases **context load**, so a description earns even harder pruning than the body: + +- **Front-load the skill's leading word** — the description is where it does its invocation work. +- **One trigger per branch.** Synonyms that rename a single branch are **duplication** — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches. +- **Cut identity that's already in the body.** Keep the description to triggers, plus any "when another skill needs…" reach clause. + ## Information hierarchy A skill is built from two content types — **steps** and **reference** — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material: From a0324014864317489b5958bf632d7ec8dbccbdcd Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 15:21:20 +0100 Subject: [PATCH 24/24] chore: set up changesets Add changesets for tracking and versioning skill changes: - package.json (private) + @changesets/cli and @changesets/changelog-github - .changeset/config.json using the GitHub release-style changelog - release workflow that opens a version PR on push to main (no npm publish) - initial changeset recording recent skill updates Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/README.md | 8 + .changeset/config.json | 14 + .changeset/initial-skill-updates.md | 12 + .github/workflows/release.yml | 36 + .gitignore | 1 + package-lock.json | 1385 +++++++++++++++++++++++++++ package.json | 20 + 7 files changed, 1476 insertions(+) create mode 100644 .changeset/README.md create mode 100644 .changeset/config.json create mode 100644 .changeset/initial-skill-updates.md create mode 100644 .github/workflows/release.yml create mode 100644 .gitignore create mode 100644 package-lock.json create mode 100644 package.json diff --git a/.changeset/README.md b/.changeset/README.md new file mode 100644 index 0000000..654c6d4 --- /dev/null +++ b/.changeset/README.md @@ -0,0 +1,8 @@ +# Changesets + +Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works +with multi-package repos, or single-package repos to help you version and publish your code. You can +find the full documentation for it [in our repository](https://github.com/changesets/changesets). + +We have a quick list of common questions to get you started engaging with this project in +[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md). diff --git a/.changeset/config.json b/.changeset/config.json new file mode 100644 index 0000000..24fd08f --- /dev/null +++ b/.changeset/config.json @@ -0,0 +1,14 @@ +{ + "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json", + "changelog": [ + "@changesets/changelog-github", + { "repo": "mattpocock/skills" } + ], + "commit": false, + "fixed": [], + "linked": [], + "access": "restricted", + "baseBranch": "main", + "updateInternalDependencies": "patch", + "ignore": [] +} diff --git a/.changeset/initial-skill-updates.md b/.changeset/initial-skill-updates.md new file mode 100644 index 0000000..8d5626c --- /dev/null +++ b/.changeset/initial-skill-updates.md @@ -0,0 +1,12 @@ +--- +"mattpocock-skills": minor +--- + +Recent skill updates: + +- Add `ask-matt` user-invoked skill for triage and multi-session build guidance. +- Add `writing-great-skills` skill, with no-op hunting at the sentence level. +- Add `decision-mapping`, `prefactoring`, and `implement` (PRD-based) skills. +- Tighten the review skill: fail-fast ref check, single-sourced rules, no-op cuts. +- Rename terminology from Commands/Skills to User-invoked/Model-invoked across the docs. +- Remove the `caveman` and `zoom-out` skills and all references. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..a385441 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,36 @@ +name: Release + +on: + push: + branches: + - main + +concurrency: ${{ github.workflow }}-${{ github.ref }} + +jobs: + release: + name: Version + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: 22 + + - name: Install dependencies + run: npm ci + + - name: Create Version Pull Request + uses: changesets/action@v1 + with: + version: npx changeset version + commit: "chore: version skills" + title: "chore: version skills" + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3c3629e --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..db12f08 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,1385 @@ +{ + "name": "mattpocock-skills", + "version": "0.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "mattpocock-skills", + "version": "0.0.0", + "license": "MIT", + "devDependencies": { + "@changesets/changelog-github": "^0.7.0", + "@changesets/cli": "^2.30.0" + } + }, + "node_modules/@babel/runtime": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.7.tgz", + "integrity": "sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@changesets/apply-release-plan": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/@changesets/apply-release-plan/-/apply-release-plan-7.1.1.tgz", + "integrity": "sha512-9qPCm/rLx/xoOFXIHGB229+4GOL76S4MC+7tyOuTsR6+1jYlfFDQORdvwR5hDA6y4FL2BPt3qpbcQIS+dW85LA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/config": "^3.1.4", + "@changesets/get-version-range-type": "^0.4.0", + "@changesets/git": "^3.0.4", + "@changesets/should-skip-package": "^0.1.2", + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3", + "detect-indent": "^6.0.0", + "fs-extra": "^7.0.1", + "lodash.startcase": "^4.4.0", + "outdent": "^0.5.0", + "prettier": "^2.7.1", + "resolve-from": "^5.0.0", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/assemble-release-plan": { + "version": "6.0.10", + "resolved": "https://registry.npmjs.org/@changesets/assemble-release-plan/-/assemble-release-plan-6.0.10.tgz", + "integrity": "sha512-rSDcqdJ9KbVyjpBIuCidhvZNIiVt1XaIYp73ycVQRIA5n/j6wQaEk0ChRLMUQ1vkxZe51PTQ9OIhbg6HQMW45A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/errors": "^0.2.0", + "@changesets/get-dependents-graph": "^2.1.4", + "@changesets/should-skip-package": "^0.1.2", + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/changelog-git": { + "version": "0.2.1", + "resolved": "https://registry.npmjs.org/@changesets/changelog-git/-/changelog-git-0.2.1.tgz", + "integrity": "sha512-x/xEleCFLH28c3bQeQIyeZf8lFXyDFVn1SgcBiR2Tw/r4IAWlk1fzxCEZ6NxQAjF2Nwtczoen3OA2qR+UawQ8Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/types": "^6.1.0" + } + }, + "node_modules/@changesets/changelog-github": { + "version": "0.7.0", + "resolved": "https://registry.npmjs.org/@changesets/changelog-github/-/changelog-github-0.7.0.tgz", + "integrity": "sha512-rBsbRvc4TVn+FvFnOVM3LxlFJfTXXCp8gfVJ+0BubxWNSVnLuAzowi5j+IEraLLP52w8AAs9QfKbPS3MMiXQJA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/get-github-info": "^0.8.0", + "@changesets/types": "^6.1.0", + "dotenv": "^8.1.0" + } + }, + "node_modules/@changesets/cli": { + "version": "2.31.0", + "resolved": "https://registry.npmjs.org/@changesets/cli/-/cli-2.31.0.tgz", + "integrity": "sha512-AhI4enNTgHu2IZr6K4WZyf0EPch4XVMn1yOMFmCD9gsfBGqMYaHXls5HyDv6/CL5axVQABz68eG30eCtbr2wFg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/apply-release-plan": "^7.1.1", + "@changesets/assemble-release-plan": "^6.0.10", + "@changesets/changelog-git": "^0.2.1", + "@changesets/config": "^3.1.4", + "@changesets/errors": "^0.2.0", + "@changesets/get-dependents-graph": "^2.1.4", + "@changesets/get-release-plan": "^4.0.16", + "@changesets/git": "^3.0.4", + "@changesets/logger": "^0.1.1", + "@changesets/pre": "^2.0.2", + "@changesets/read": "^0.6.7", + "@changesets/should-skip-package": "^0.1.2", + "@changesets/types": "^6.1.0", + "@changesets/write": "^0.4.0", + "@inquirer/external-editor": "^1.0.2", + "@manypkg/get-packages": "^1.1.3", + "ansi-colors": "^4.1.3", + "enquirer": "^2.4.1", + "fs-extra": "^7.0.1", + "mri": "^1.2.0", + "package-manager-detector": "^0.2.0", + "picocolors": "^1.1.0", + "resolve-from": "^5.0.0", + "semver": "^7.5.3", + "spawndamnit": "^3.0.1", + "term-size": "^2.1.0" + }, + "bin": { + "changeset": "bin.js" + } + }, + "node_modules/@changesets/config": { + "version": "3.1.4", + "resolved": "https://registry.npmjs.org/@changesets/config/-/config-3.1.4.tgz", + "integrity": "sha512-pf0bvD/v6WI2cRlZ6hzpjtZdSlXDXMAJ+Iz7xfFzV4ZxJ8OGGAON+1qYc99ZPrijnt4xp3VGG7eNvAOGS24V1Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/errors": "^0.2.0", + "@changesets/get-dependents-graph": "^2.1.4", + "@changesets/logger": "^0.1.1", + "@changesets/should-skip-package": "^0.1.2", + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1", + "micromatch": "^4.0.8" + } + }, + "node_modules/@changesets/errors": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/@changesets/errors/-/errors-0.2.0.tgz", + "integrity": "sha512-6BLOQUscTpZeGljvyQXlWOItQyU71kCdGz7Pi8H8zdw6BI0g3m43iL4xKUVPWtG+qrrL9DTjpdn8eYuCQSRpow==", + "dev": true, + "license": "MIT", + "dependencies": { + "extendable-error": "^0.1.5" + } + }, + "node_modules/@changesets/get-dependents-graph": { + "version": "2.1.4", + "resolved": "https://registry.npmjs.org/@changesets/get-dependents-graph/-/get-dependents-graph-2.1.4.tgz", + "integrity": "sha512-ZsS00x6WvmHq3sQv8oCMwL0f/z3wbXCVuSVTJwCnnmbC/iBdNJGFx1EcbMG4PC6sXRyH69liM4A2WKXzn/kRPg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3", + "picocolors": "^1.1.0", + "semver": "^7.5.3" + } + }, + "node_modules/@changesets/get-github-info": { + "version": "0.8.0", + "resolved": "https://registry.npmjs.org/@changesets/get-github-info/-/get-github-info-0.8.0.tgz", + "integrity": "sha512-cRnC+xdF0JIik7coko3iUP9qbnfi1iJQ3sAa6dE+Tx3+ET8bjFEm63PA4WEohgjYcmsOikPHWzPsMWWiZmntOQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "dataloader": "^1.4.0", + "node-fetch": "^2.5.0" + } + }, + "node_modules/@changesets/get-release-plan": { + "version": "4.0.16", + "resolved": "https://registry.npmjs.org/@changesets/get-release-plan/-/get-release-plan-4.0.16.tgz", + "integrity": "sha512-2K5Om6CrMPm45rtvckfzWo7e9jOVCKLCnXia5eUPaURH7/LWzri7pK1TycdzAuAtehLkW7VPbWLCSExTHmiI6g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/assemble-release-plan": "^6.0.10", + "@changesets/config": "^3.1.4", + "@changesets/pre": "^2.0.2", + "@changesets/read": "^0.6.7", + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3" + } + }, + "node_modules/@changesets/get-version-range-type": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/@changesets/get-version-range-type/-/get-version-range-type-0.4.0.tgz", + "integrity": "sha512-hwawtob9DryoGTpixy1D3ZXbGgJu1Rhr+ySH2PvTLHvkZuQ7sRT4oQwMh0hbqZH1weAooedEjRsbrWcGLCeyVQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@changesets/git": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@changesets/git/-/git-3.0.4.tgz", + "integrity": "sha512-BXANzRFkX+XcC1q/d27NKvlJ1yf7PSAgi8JG6dt8EfbHFHi4neau7mufcSca5zRhwOL8j9s6EqsxmT+s+/E6Sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/errors": "^0.2.0", + "@manypkg/get-packages": "^1.1.3", + "is-subdir": "^1.1.1", + "micromatch": "^4.0.8", + "spawndamnit": "^3.0.1" + } + }, + "node_modules/@changesets/logger": { + "version": "0.1.1", + "resolved": "https://registry.npmjs.org/@changesets/logger/-/logger-0.1.1.tgz", + "integrity": "sha512-OQtR36ZlnuTxKqoW4Sv6x5YIhOmClRd5pWsjZsddYxpWs517R0HkyiefQPIytCVh4ZcC5x9XaG8KTdd5iRQUfg==", + "dev": true, + "license": "MIT", + "dependencies": { + "picocolors": "^1.1.0" + } + }, + "node_modules/@changesets/parse": { + "version": "0.4.3", + "resolved": "https://registry.npmjs.org/@changesets/parse/-/parse-0.4.3.tgz", + "integrity": "sha512-ZDmNc53+dXdWEv7fqIUSgRQOLYoUom5Z40gmLgmATmYR9NbL6FJJHwakcCpzaeCy+1D0m0n7mT4jj2B/MQPl7A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/types": "^6.1.0", + "js-yaml": "^4.1.1" + } + }, + "node_modules/@changesets/pre": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/@changesets/pre/-/pre-2.0.2.tgz", + "integrity": "sha512-HaL/gEyFVvkf9KFg6484wR9s0qjAXlZ8qWPDkTyKF6+zqjBe/I2mygg3MbpZ++hdi0ToqNUF8cjj7fBy0dg8Ug==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/errors": "^0.2.0", + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3", + "fs-extra": "^7.0.1" + } + }, + "node_modules/@changesets/read": { + "version": "0.6.7", + "resolved": "https://registry.npmjs.org/@changesets/read/-/read-0.6.7.tgz", + "integrity": "sha512-D1G4AUYGrBEk8vj8MGwf75k9GpN6XL3wg8i42P2jZZwFLXnlr2Pn7r9yuQNbaMCarP7ZQWNJbV6XLeysAIMhTA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/git": "^3.0.4", + "@changesets/logger": "^0.1.1", + "@changesets/parse": "^0.4.3", + "@changesets/types": "^6.1.0", + "fs-extra": "^7.0.1", + "p-filter": "^2.1.0", + "picocolors": "^1.1.0" + } + }, + "node_modules/@changesets/should-skip-package": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/@changesets/should-skip-package/-/should-skip-package-0.1.2.tgz", + "integrity": "sha512-qAK/WrqWLNCP22UDdBTMPH5f41elVDlsNyat180A33dWxuUDyNpg6fPi/FyTZwRriVjg0L8gnjJn2F9XAoF0qw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/types": "^6.1.0", + "@manypkg/get-packages": "^1.1.3" + } + }, + "node_modules/@changesets/types": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-6.1.0.tgz", + "integrity": "sha512-rKQcJ+o1nKNgeoYRHKOS07tAMNd3YSN0uHaJOZYjBAgxfV7TUE7JE+z4BzZdQwb5hKaYbayKN5KrYV7ODb2rAA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@changesets/write": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/@changesets/write/-/write-0.4.0.tgz", + "integrity": "sha512-CdTLvIOPiCNuH71pyDu3rA+Q0n65cmAbXnwWH84rKGiFumFzkmHNT8KHTMEchcxN+Kl8I54xGUhJ7l3E7X396Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@changesets/types": "^6.1.0", + "fs-extra": "^7.0.1", + "human-id": "^4.1.1", + "prettier": "^2.7.1" + } + }, + "node_modules/@inquirer/external-editor": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/@inquirer/external-editor/-/external-editor-1.0.3.tgz", + "integrity": "sha512-RWbSrDiYmO4LbejWY7ttpxczuwQyZLBUyygsA9Nsv95hpzUWwnNTVQmAq3xuh7vNwCp07UTmE5i11XAEExx4RA==", + "dev": true, + "license": "MIT", + "dependencies": { + "chardet": "^2.1.1", + "iconv-lite": "^0.7.0" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@types/node": ">=18" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/@manypkg/find-root": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@manypkg/find-root/-/find-root-1.1.0.tgz", + "integrity": "sha512-mki5uBvhHzO8kYYix/WRy2WX8S3B5wdVSc9D6KcU5lQNglP2yt58/VfLuAK49glRXChosY8ap2oJ1qgma3GUVA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.5.5", + "@types/node": "^12.7.1", + "find-up": "^4.1.0", + "fs-extra": "^8.1.0" + } + }, + "node_modules/@manypkg/find-root/node_modules/@types/node": { + "version": "12.20.55", + "resolved": "https://registry.npmjs.org/@types/node/-/node-12.20.55.tgz", + "integrity": "sha512-J8xLz7q2OFulZ2cyGTLE1TbbZcjpno7FaN6zdJNrgAdrJ+DZzh/uFR6YrTb4C+nXakvud8Q4+rbhoIWlYQbUFQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@manypkg/find-root/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@manypkg/get-packages": { + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@manypkg/get-packages/-/get-packages-1.1.3.tgz", + "integrity": "sha512-fo+QhuU3qE/2TQMQmbVMqaQ6EWbMhi4ABWP+O4AM1NqPBuy0OrApV5LO6BrrgnhtAHS2NH6RrVk9OL181tTi8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/runtime": "^7.5.5", + "@changesets/types": "^4.0.1", + "@manypkg/find-root": "^1.1.0", + "fs-extra": "^8.1.0", + "globby": "^11.0.0", + "read-yaml-file": "^1.1.0" + } + }, + "node_modules/@manypkg/get-packages/node_modules/@changesets/types": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/@changesets/types/-/types-4.1.0.tgz", + "integrity": "sha512-LDQvVDv5Kb50ny2s25Fhm3d9QSZimsoUGBsUioj6MC3qbMUCuC8GPIvk/M6IvXx3lYhAs0lwWUQLb+VIEUCECw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@manypkg/get-packages/node_modules/fs-extra": { + "version": "8.1.0", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz", + "integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.2.0", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/@nodelib/fs.scandir": { + "version": "2.1.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz", + "integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "2.0.5", + "run-parallel": "^1.1.9" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.stat": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz", + "integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/@nodelib/fs.walk": { + "version": "1.2.8", + "resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz", + "integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.scandir": "2.1.5", + "fastq": "^1.6.0" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/@types/node": { + "version": "25.9.3", + "resolved": "https://registry.npmjs.org/@types/node/-/node-25.9.3.tgz", + "integrity": "sha512-603BddQMv3pUcr4U2dhujk83N2tTDVr/34wII2B6bJy6g+8WD6yUb11jszNs0gdi4PesVWl7ABt8nYMVpnLUcg==", + "dev": true, + "license": "MIT", + "optional": true, + "peer": true, + "dependencies": { + "undici-types": ">=7.24.0 <7.24.7" + } + }, + "node_modules/ansi-colors": { + "version": "4.1.3", + "resolved": "https://registry.npmjs.org/ansi-colors/-/ansi-colors-4.1.3.tgz", + "integrity": "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/ansi-regex": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz", + "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true, + "license": "Python-2.0" + }, + "node_modules/array-union": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/array-union/-/array-union-2.1.0.tgz", + "integrity": "sha512-HGyxoOTYUyCM6stUe6EJgnd4EoewAI7zMdfqO+kGjnlZmBDz/cR5pf8r/cR4Wq60sL/p0IkcjUEEPwS3GFrIyw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/better-path-resolve": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/better-path-resolve/-/better-path-resolve-1.0.0.tgz", + "integrity": "sha512-pbnl5XzGBdrFU/wT4jqmJVPn2B6UHPBOhzMQkY/SPUPB6QtUXtmBHBIwCbXJol93mOpGMnQyP/+BB19q04xj7g==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-windows": "^1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/braces": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz", + "integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "fill-range": "^7.1.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/chardet": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/chardet/-/chardet-2.1.1.tgz", + "integrity": "sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/dataloader": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/dataloader/-/dataloader-1.4.0.tgz", + "integrity": "sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/detect-indent": { + "version": "6.1.0", + "resolved": "https://registry.npmjs.org/detect-indent/-/detect-indent-6.1.0.tgz", + "integrity": "sha512-reYkTUJAZb9gUuZ2RvVCNhVHdg62RHnJ7WJl8ftMi4diZ6NWlciOzQN88pUhSELEwflJht4oQDv0F0BMlwaYtA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/dir-glob": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/dir-glob/-/dir-glob-3.0.1.tgz", + "integrity": "sha512-WkrWp9GR4KXfKGYzOLmTuGVi1UWFfws377n9cc55/tb6DuqyF6pcQ5AbiHEshaDpY9v6oaSr2XCDidGmMwdzIA==", + "dev": true, + "license": "MIT", + "dependencies": { + "path-type": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/dotenv": { + "version": "8.6.0", + "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-8.6.0.tgz", + "integrity": "sha512-IrPdXQsk2BbzvCBGBOTmmSH5SodmqZNt4ERAZDmW4CT+tL8VtvinqywuANaFu4bOMWki16nqf0e4oC0QIaDr/g==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=10" + } + }, + "node_modules/enquirer": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/enquirer/-/enquirer-2.4.1.tgz", + "integrity": "sha512-rRqJg/6gd538VHvR3PSrdRBb/1Vy2YfzHqzvbhGIQpDRKIa4FgV/54b5Q1xYSxOOwKvjXweS26E0Q+nAMwp2pQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-colors": "^4.1.1", + "strip-ansi": "^6.0.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/esprima": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/esprima/-/esprima-4.0.1.tgz", + "integrity": "sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==", + "dev": true, + "license": "BSD-2-Clause", + "bin": { + "esparse": "bin/esparse.js", + "esvalidate": "bin/esvalidate.js" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/extendable-error": { + "version": "0.1.7", + "resolved": "https://registry.npmjs.org/extendable-error/-/extendable-error-0.1.7.tgz", + "integrity": "sha512-UOiS2in6/Q0FK0R0q6UY9vYpQ21mr/Qn1KOnte7vsACuNJf514WvCCUHSRCPcgjPT2bAhNIJdlE6bVap1GKmeg==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-glob": { + "version": "3.3.3", + "resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.3.tgz", + "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@nodelib/fs.stat": "^2.0.2", + "@nodelib/fs.walk": "^1.2.3", + "glob-parent": "^5.1.2", + "merge2": "^1.3.0", + "micromatch": "^4.0.8" + }, + "engines": { + "node": ">=8.6.0" + } + }, + "node_modules/fastq": { + "version": "1.20.1", + "resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz", + "integrity": "sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==", + "dev": true, + "license": "ISC", + "dependencies": { + "reusify": "^1.0.4" + } + }, + "node_modules/fill-range": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz", + "integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==", + "dev": true, + "license": "MIT", + "dependencies": { + "to-regex-range": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/find-up": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/find-up/-/find-up-4.1.0.tgz", + "integrity": "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==", + "dev": true, + "license": "MIT", + "dependencies": { + "locate-path": "^5.0.0", + "path-exists": "^4.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/fs-extra": { + "version": "7.0.1", + "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-7.0.1.tgz", + "integrity": "sha512-YJDaCJZEnBmcbw13fvdAM9AwNOJwOzrE4pqMqBq5nFiEqXUqHwlK4B+3pUw6JNvfSPtX05xFHtYy/1ni01eGCw==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.1.2", + "jsonfile": "^4.0.0", + "universalify": "^0.1.0" + }, + "engines": { + "node": ">=6 <7 || >=8" + } + }, + "node_modules/glob-parent": { + "version": "5.1.2", + "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz", + "integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==", + "dev": true, + "license": "ISC", + "dependencies": { + "is-glob": "^4.0.1" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/globby": { + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.1.0.tgz", + "integrity": "sha512-jhIXaOzy1sb8IyocaruWSn1TjmnBVs8Ayhcy83rmxNJ8q2uWKCAj3CnJY+KpGSXCueAPc0i05kVvVKtP1t9S3g==", + "dev": true, + "license": "MIT", + "dependencies": { + "array-union": "^2.1.0", + "dir-glob": "^3.0.1", + "fast-glob": "^3.2.9", + "ignore": "^5.2.0", + "merge2": "^1.4.1", + "slash": "^3.0.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/graceful-fs": { + "version": "4.2.11", + "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz", + "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==", + "dev": true, + "license": "ISC" + }, + "node_modules/human-id": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/human-id/-/human-id-4.2.0.tgz", + "integrity": "sha512-K3GbkIWqyvvlpfhBPlbEvD97TtqBpAYA4kt+cn2lD2x2HuohzZCibcA2nOlnJT6exqvJLggoB5nv2dNf192nEA==", + "dev": true, + "license": "MIT", + "bin": { + "human-id": "dist/cli.js" + } + }, + "node_modules/iconv-lite": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz", + "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/ignore": { + "version": "5.3.2", + "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz", + "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4" + } + }, + "node_modules/is-extglob": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz", + "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-glob": { + "version": "4.0.3", + "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz", + "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-extglob": "^2.1.1" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/is-number": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz", + "integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.12.0" + } + }, + "node_modules/is-subdir": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/is-subdir/-/is-subdir-1.2.0.tgz", + "integrity": "sha512-2AT6j+gXe/1ueqbW6fLZJiIw3F8iXGJtt0yDrZaBhAZEG1raiTxKWU+IPqMCzQAXOUCKdA4UDMgacKH25XG2Cw==", + "dev": true, + "license": "MIT", + "dependencies": { + "better-path-resolve": "1.0.0" + }, + "engines": { + "node": ">=4" + } + }, + "node_modules/is-windows": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/is-windows/-/is-windows-1.0.2.tgz", + "integrity": "sha512-eXK1UInq2bPmjyX6e3VHIzMLobc4J94i4AWn+Hpq3OU5KkrRC96OAcR3PRJ/pGu6m8TRnBHP9dkXQVsT/COVIA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "dev": true, + "license": "ISC" + }, + "node_modules/js-yaml": { + "version": "4.2.0", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.2.0.tgz", + "integrity": "sha512-ePWsvanv0DWuDRsW8dnt+R4jQ31SCRCQ7hhNcPXZPsoBZiemuZNYGf7adZdqX2D86j6rvKp3RpCxVTSb8WQlOw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/puzrin" + }, + { + "type": "github", + "url": "https://github.com/sponsors/nodeca" + } + ], + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/jsonfile": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-4.0.0.tgz", + "integrity": "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg==", + "dev": true, + "license": "MIT", + "optionalDependencies": { + "graceful-fs": "^4.1.6" + } + }, + "node_modules/locate-path": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-5.0.0.tgz", + "integrity": "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-locate": "^4.1.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/lodash.startcase": { + "version": "4.4.0", + "resolved": "https://registry.npmjs.org/lodash.startcase/-/lodash.startcase-4.4.0.tgz", + "integrity": "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg==", + "dev": true, + "license": "MIT" + }, + "node_modules/merge2": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz", + "integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 8" + } + }, + "node_modules/micromatch": { + "version": "4.0.8", + "resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz", + "integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==", + "dev": true, + "license": "MIT", + "dependencies": { + "braces": "^3.0.3", + "picomatch": "^2.3.1" + }, + "engines": { + "node": ">=8.6" + } + }, + "node_modules/mri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", + "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/node-fetch": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz", + "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "whatwg-url": "^5.0.0" + }, + "engines": { + "node": "4.x || >=6.0.0" + }, + "peerDependencies": { + "encoding": "^0.1.0" + }, + "peerDependenciesMeta": { + "encoding": { + "optional": true + } + } + }, + "node_modules/outdent": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/outdent/-/outdent-0.5.0.tgz", + "integrity": "sha512-/jHxFIzoMXdqPzTaCpFzAAWhpkSjZPF4Vsn6jAfNpmbH/ymsmd7Qc6VE9BGn0L6YMj6uwpQLxCECpus4ukKS9Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/p-filter": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-filter/-/p-filter-2.1.0.tgz", + "integrity": "sha512-ZBxxZ5sL2HghephhpGAQdoskxplTwr7ICaehZwLIlfL6acuVgZPm8yBNuRAFBGEqtD/hmUeq9eqLg2ys9Xr/yw==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-map": "^2.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/p-limit": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-2.3.0.tgz", + "integrity": "sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-try": "^2.0.0" + }, + "engines": { + "node": ">=6" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/p-locate": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-4.1.0.tgz", + "integrity": "sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==", + "dev": true, + "license": "MIT", + "dependencies": { + "p-limit": "^2.2.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/p-map": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/p-map/-/p-map-2.1.0.tgz", + "integrity": "sha512-y3b8Kpd8OAN444hxfBbFfj1FY/RjtTd8tzYwhUqNYXx0fXx2iX4maP4Qr6qhIKbQXI02wTLAda4fYUbDagTUFw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/p-try": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/p-try/-/p-try-2.2.0.tgz", + "integrity": "sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/package-manager-detector": { + "version": "0.2.11", + "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-0.2.11.tgz", + "integrity": "sha512-BEnLolu+yuz22S56CU1SUKq3XC3PkwD5wv4ikR4MfGvnRVcmzXR9DwSlW2fEamyTPyXHomBJRzgapeuBvRNzJQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "quansync": "^0.2.7" + } + }, + "node_modules/path-exists": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz", + "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-type": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz", + "integrity": "sha512-gDKb8aZMDeD/tZWs9P6+q0J9Mwkdl6xMV8TjnGP3qJVJ06bdMgkbBlLU8IdfOsIsFz2BW1rNVT3XuNEl8zPAvw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "dev": true, + "license": "ISC" + }, + "node_modules/picomatch": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz", + "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8.6" + }, + "funding": { + "url": "https://github.com/sponsors/jonschlinkert" + } + }, + "node_modules/pify": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/pify/-/pify-4.0.1.tgz", + "integrity": "sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/prettier": { + "version": "2.8.8", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.8.8.tgz", + "integrity": "sha512-tdN8qQGvNjw4CHbY+XXk0JgCXn9QiF21a55rBe5LJAU+kDyC4WQn4+awm2Xfk2lQMk5fKup9XgzTZtGkjBdP9Q==", + "dev": true, + "license": "MIT", + "bin": { + "prettier": "bin-prettier.js" + }, + "engines": { + "node": ">=10.13.0" + }, + "funding": { + "url": "https://github.com/prettier/prettier?sponsor=1" + } + }, + "node_modules/quansync": { + "version": "0.2.11", + "resolved": "https://registry.npmjs.org/quansync/-/quansync-0.2.11.tgz", + "integrity": "sha512-AifT7QEbW9Nri4tAwR5M/uzpBuqfZf+zwaEM/QkzEjj7NBuFD2rBuy0K3dE+8wltbezDV7JMA0WfnCPYRSYbXA==", + "dev": true, + "funding": [ + { + "type": "individual", + "url": "https://github.com/sponsors/antfu" + }, + { + "type": "individual", + "url": "https://github.com/sponsors/sxzz" + } + ], + "license": "MIT" + }, + "node_modules/queue-microtask": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz", + "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT" + }, + "node_modules/read-yaml-file": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/read-yaml-file/-/read-yaml-file-1.1.0.tgz", + "integrity": "sha512-VIMnQi/Z4HT2Fxuwg5KrY174U1VdUIASQVWXXyqtNRtxSr9IYkn1rsI6Tb6HsrHCmB7gVpNwX6JxPTHcH6IoTA==", + "dev": true, + "license": "MIT", + "dependencies": { + "graceful-fs": "^4.1.5", + "js-yaml": "^3.6.1", + "pify": "^4.0.1", + "strip-bom": "^3.0.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/read-yaml-file/node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "license": "MIT", + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, + "node_modules/read-yaml-file/node_modules/js-yaml": { + "version": "3.14.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.2.tgz", + "integrity": "sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^1.0.7", + "esprima": "^4.0.0" + }, + "bin": { + "js-yaml": "bin/js-yaml.js" + } + }, + "node_modules/resolve-from": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-5.0.0.tgz", + "integrity": "sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/reusify": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/reusify/-/reusify-1.1.0.tgz", + "integrity": "sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==", + "dev": true, + "license": "MIT", + "engines": { + "iojs": ">=1.0.0", + "node": ">=0.10.0" + } + }, + "node_modules/run-parallel": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz", + "integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/feross" + }, + { + "type": "patreon", + "url": "https://www.patreon.com/feross" + }, + { + "type": "consulting", + "url": "https://feross.org/support" + } + ], + "license": "MIT", + "dependencies": { + "queue-microtask": "^1.2.2" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "dev": true, + "license": "MIT" + }, + "node_modules/semver": { + "version": "7.8.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz", + "integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/slash": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz", + "integrity": "sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/spawndamnit": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/spawndamnit/-/spawndamnit-3.0.1.tgz", + "integrity": "sha512-MmnduQUuHCoFckZoWnXsTg7JaiLBJrKFj9UI2MbRPGaJeVpsLcVBu6P/IGZovziM/YBsellCmsprgNA+w0CzVg==", + "dev": true, + "license": "SEE LICENSE IN LICENSE", + "dependencies": { + "cross-spawn": "^7.0.5", + "signal-exit": "^4.0.1" + } + }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/strip-ansi": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz", + "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==", + "dev": true, + "license": "MIT", + "dependencies": { + "ansi-regex": "^5.0.1" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/strip-bom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-bom/-/strip-bom-3.0.0.tgz", + "integrity": "sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/term-size": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/term-size/-/term-size-2.2.1.tgz", + "integrity": "sha512-wK0Ri4fOGjv/XPy8SBHZChl8CM7uMc5VML7SqiQ0zG7+J5Vr+RMQDoHa2CNT6KHUnTGIXH34UDMkPzAUyapBZg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=8" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/to-regex-range": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz", + "integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-number": "^7.0.0" + }, + "engines": { + "node": ">=8.0" + } + }, + "node_modules/tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==", + "dev": true, + "license": "MIT" + }, + "node_modules/undici-types": { + "version": "7.24.6", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.24.6.tgz", + "integrity": "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg==", + "dev": true, + "license": "MIT", + "optional": true, + "peer": true + }, + "node_modules/universalify": { + "version": "0.1.2", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.1.2.tgz", + "integrity": "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==", + "dev": true, + "license": "BSD-2-Clause" + }, + "node_modules/whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "dev": true, + "license": "MIT", + "dependencies": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "dev": true, + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..11ed986 --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "mattpocock-skills", + "version": "0.0.0", + "private": true, + "description": "Matt Pocock's agent skills for real engineering", + "repository": { + "type": "git", + "url": "https://github.com/mattpocock/skills" + }, + "license": "MIT", + "scripts": { + "changeset": "changeset", + "version": "changeset version" + }, + "devDependencies": { + "@changesets/changelog-github": "^0.7.0", + "@changesets/cli": "^2.30.0" + }, + "packageManager": "npm@10.9.4" +}