From 63a7aba9deafe4874c58b4160180507d85b04df7 Mon Sep 17 00:00:00 2001 From: Light26 <67133749+LightDevCoder@users.noreply.github.com> Date: Thu, 23 Jul 2026 11:19:16 +0800 Subject: [PATCH 01/10] feat: add pinned Matt third-party collection --- .github/workflows/quality.yml | 24 + AGENTS.md | 171 ++- CATALOG.md | 84 +- CATALOG.zh-CN.md | 41 + CHANGELOG.md | 39 +- CHANGELOG.zh-CN.md | 20 + README.md | 175 ++- README.zh-CN.md | 58 + UPSTREAM_LOCK.json | 1014 ++++++++++++++++- config/upstream-allowlist.json | 30 + docs/INSTALLATION.md | 130 +-- docs/INSTALLATION.zh-CN.md | 25 + docs/MAINTENANCE.md | 138 +-- docs/MAINTENANCE.zh-CN.md | 24 + docs/PROVENANCE_POLICY.md | 22 + docs/PROVENANCE_POLICY.zh-CN.md | 14 + docs/REVIEW_POLICY.md | 30 + docs/REVIEW_POLICY.zh-CN.md | 13 + docs/THIRD_PARTY_ADMISSION.md | 170 +-- docs/THIRD_PARTY_ADMISSION.zh-CN.md | 29 + docs/UPDATE_POLICY.md | 20 + docs/UPDATE_POLICY.zh-CN.md | 11 + .../releases/v0.1.1/DISCOVERY_VERIFICATION.md | 16 + .../v0.1.1/INSTALLATION_VERIFICATION.md | 14 + docs/evidence/releases/v0.1.1/LIMITATIONS.md | 13 + .../releases/v0.1.1/RELEASE_RECEIPT.md | 31 + .../releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md | 16 + docs/evidence/releases/v0.1.1/TEST_SUMMARY.md | 20 + scripts/sync-upstream.ps1 | 425 +++++++ skills/ask-matt/LICENSE | 21 + skills/ask-matt/PATCHES.md | 24 + skills/ask-matt/SKILL.md | 76 ++ skills/ask-matt/UPSTREAM.md | 50 + skills/ask-matt/agents/openai.yaml | 7 + skills/code-review/LICENSE | 21 + skills/code-review/PATCHES.md | 24 + skills/code-review/SKILL.md | 89 ++ skills/code-review/UPSTREAM.md | 50 + skills/code-review/agents/openai.yaml | 7 + skills/codebase-design/DEEPENING.md | 37 + skills/codebase-design/DESIGN-IT-TWICE.md | 44 + skills/codebase-design/LICENSE | 21 + skills/codebase-design/PATCHES.md | 24 + skills/codebase-design/SKILL.md | 114 ++ skills/codebase-design/UPSTREAM.md | 50 + skills/codebase-design/agents/openai.yaml | 7 + skills/design-an-interface/LICENSE | 21 + skills/design-an-interface/PATCHES.md | 24 + skills/design-an-interface/SKILL.md | 94 ++ skills/design-an-interface/UPSTREAM.md | 50 + skills/design-an-interface/agents/openai.yaml | 7 + skills/diagnosing-bugs/LICENSE | 21 + skills/diagnosing-bugs/PATCHES.md | 24 + skills/diagnosing-bugs/SKILL.md | 134 +++ skills/diagnosing-bugs/UPSTREAM.md | 50 + skills/diagnosing-bugs/agents/openai.yaml | 7 + .../scripts/hitl-loop.template.sh | 41 + skills/domain-modeling/ADR-FORMAT.md | 47 + skills/domain-modeling/CONTEXT-FORMAT.md | 60 + skills/domain-modeling/LICENSE | 21 + skills/domain-modeling/PATCHES.md | 24 + skills/domain-modeling/SKILL.md | 74 ++ skills/domain-modeling/UPSTREAM.md | 50 + skills/domain-modeling/agents/openai.yaml | 7 + skills/grill-me/LICENSE | 21 + skills/grill-me/PATCHES.md | 24 + skills/grill-me/SKILL.md | 7 + skills/grill-me/UPSTREAM.md | 50 + skills/grill-me/agents/openai.yaml | 7 + skills/grill-with-docs/LICENSE | 21 + skills/grill-with-docs/PATCHES.md | 24 + skills/grill-with-docs/SKILL.md | 7 + skills/grill-with-docs/UPSTREAM.md | 50 + skills/grill-with-docs/agents/openai.yaml | 7 + skills/grilling/LICENSE | 21 + skills/grilling/PATCHES.md | 24 + skills/grilling/SKILL.md | 12 + skills/grilling/UPSTREAM.md | 50 + skills/grilling/agents/openai.yaml | 7 + skills/handoff/LICENSE | 21 + skills/handoff/PATCHES.md | 24 + skills/handoff/SKILL.md | 16 + skills/handoff/UPSTREAM.md | 50 + skills/handoff/agents/openai.yaml | 7 + skills/implement/LICENSE | 21 + skills/implement/PATCHES.md | 24 + skills/implement/SKILL.md | 15 + skills/implement/UPSTREAM.md | 50 + skills/implement/agents/openai.yaml | 7 + .../HTML-REPORT.md | 123 ++ skills/improve-codebase-architecture/LICENSE | 21 + .../improve-codebase-architecture/PATCHES.md | 24 + skills/improve-codebase-architecture/SKILL.md | 66 ++ .../improve-codebase-architecture/UPSTREAM.md | 50 + .../agents/openai.yaml | 7 + skills/loop-me/LICENSE | 21 + skills/loop-me/PATCHES.md | 24 + skills/loop-me/SKILL.md | 32 + skills/loop-me/UPSTREAM.md | 50 + skills/loop-me/agents/openai.yaml | 7 + skills/prototype/LICENSE | 21 + skills/prototype/LOGIC.md | 79 ++ skills/prototype/PATCHES.md | 24 + skills/prototype/SKILL.md | 30 + skills/prototype/UI.md | 112 ++ skills/prototype/UPSTREAM.md | 50 + skills/prototype/agents/openai.yaml | 7 + skills/qa/LICENSE | 21 + skills/qa/PATCHES.md | 24 + skills/qa/SKILL.md | 130 +++ skills/qa/UPSTREAM.md | 50 + skills/qa/agents/openai.yaml | 7 + skills/research/LICENSE | 21 + skills/research/PATCHES.md | 24 + skills/research/SKILL.md | 12 + skills/research/UPSTREAM.md | 50 + skills/research/agents/openai.yaml | 7 + skills/tdd/LICENSE | 21 + skills/tdd/PATCHES.md | 24 + skills/tdd/SKILL.md | 36 + skills/tdd/UPSTREAM.md | 50 + skills/tdd/agents/openai.yaml | 7 + skills/tdd/mocking.md | 59 + skills/tdd/tests.md | 77 ++ skills/teach/GLOSSARY-FORMAT.md | 35 + skills/teach/LEARNING-RECORD-FORMAT.md | 46 + skills/teach/LICENSE | 21 + skills/teach/MISSION-FORMAT.md | 31 + skills/teach/PATCHES.md | 24 + skills/teach/RESOURCES-FORMAT.md | 32 + skills/teach/SKILL.md | 140 +++ skills/teach/UPSTREAM.md | 50 + skills/teach/agents/openai.yaml | 7 + skills/to-spec/LICENSE | 21 + skills/to-spec/PATCHES.md | 24 + skills/to-spec/SKILL.md | 75 ++ skills/to-spec/UPSTREAM.md | 50 + skills/to-spec/agents/openai.yaml | 7 + skills/to-tickets/LICENSE | 21 + skills/to-tickets/PATCHES.md | 24 + skills/to-tickets/SKILL.md | 114 ++ skills/to-tickets/UPSTREAM.md | 50 + skills/to-tickets/agents/openai.yaml | 7 + skills/ubiquitous-language/LICENSE | 21 + skills/ubiquitous-language/PATCHES.md | 24 + skills/ubiquitous-language/SKILL.md | 93 ++ skills/ubiquitous-language/UPSTREAM.md | 50 + skills/ubiquitous-language/agents/openai.yaml | 7 + skills/wayfinder/LICENSE | 21 + skills/wayfinder/PATCHES.md | 24 + skills/wayfinder/SKILL.md | 127 +++ skills/wayfinder/UPSTREAM.md | 50 + skills/wayfinder/agents/openai.yaml | 7 + skills/writing-great-skills/GLOSSARY.md | 201 ++++ skills/writing-great-skills/LICENSE | 21 + skills/writing-great-skills/PATCHES.md | 24 + skills/writing-great-skills/SKILL.md | 83 ++ skills/writing-great-skills/UPSTREAM.md | 50 + .../writing-great-skills/agents/openai.yaml | 7 + sources/mattpocock-skills/README.md | 18 + sources/mattpocock-skills/README.zh-CN.md | 16 + tests/third-party-collection-tests.ps1 | 168 +++ 162 files changed, 7452 insertions(+), 513 deletions(-) create mode 100644 .github/workflows/quality.yml create mode 100644 CATALOG.zh-CN.md create mode 100644 CHANGELOG.zh-CN.md create mode 100644 README.zh-CN.md create mode 100644 config/upstream-allowlist.json create mode 100644 docs/INSTALLATION.zh-CN.md create mode 100644 docs/MAINTENANCE.zh-CN.md create mode 100644 docs/PROVENANCE_POLICY.md create mode 100644 docs/PROVENANCE_POLICY.zh-CN.md create mode 100644 docs/REVIEW_POLICY.md create mode 100644 docs/REVIEW_POLICY.zh-CN.md create mode 100644 docs/THIRD_PARTY_ADMISSION.zh-CN.md create mode 100644 docs/UPDATE_POLICY.md create mode 100644 docs/UPDATE_POLICY.zh-CN.md create mode 100644 docs/evidence/releases/v0.1.1/DISCOVERY_VERIFICATION.md create mode 100644 docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md create mode 100644 docs/evidence/releases/v0.1.1/LIMITATIONS.md create mode 100644 docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md create mode 100644 docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md create mode 100644 docs/evidence/releases/v0.1.1/TEST_SUMMARY.md create mode 100644 scripts/sync-upstream.ps1 create mode 100644 skills/ask-matt/LICENSE create mode 100644 skills/ask-matt/PATCHES.md create mode 100644 skills/ask-matt/SKILL.md create mode 100644 skills/ask-matt/UPSTREAM.md create mode 100644 skills/ask-matt/agents/openai.yaml create mode 100644 skills/code-review/LICENSE create mode 100644 skills/code-review/PATCHES.md create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/code-review/UPSTREAM.md create mode 100644 skills/code-review/agents/openai.yaml create mode 100644 skills/codebase-design/DEEPENING.md create mode 100644 skills/codebase-design/DESIGN-IT-TWICE.md create mode 100644 skills/codebase-design/LICENSE create mode 100644 skills/codebase-design/PATCHES.md create mode 100644 skills/codebase-design/SKILL.md create mode 100644 skills/codebase-design/UPSTREAM.md create mode 100644 skills/codebase-design/agents/openai.yaml create mode 100644 skills/design-an-interface/LICENSE create mode 100644 skills/design-an-interface/PATCHES.md create mode 100644 skills/design-an-interface/SKILL.md create mode 100644 skills/design-an-interface/UPSTREAM.md create mode 100644 skills/design-an-interface/agents/openai.yaml create mode 100644 skills/diagnosing-bugs/LICENSE create mode 100644 skills/diagnosing-bugs/PATCHES.md create mode 100644 skills/diagnosing-bugs/SKILL.md create mode 100644 skills/diagnosing-bugs/UPSTREAM.md create mode 100644 skills/diagnosing-bugs/agents/openai.yaml create mode 100644 skills/diagnosing-bugs/scripts/hitl-loop.template.sh create mode 100644 skills/domain-modeling/ADR-FORMAT.md create mode 100644 skills/domain-modeling/CONTEXT-FORMAT.md create mode 100644 skills/domain-modeling/LICENSE create mode 100644 skills/domain-modeling/PATCHES.md create mode 100644 skills/domain-modeling/SKILL.md create mode 100644 skills/domain-modeling/UPSTREAM.md create mode 100644 skills/domain-modeling/agents/openai.yaml create mode 100644 skills/grill-me/LICENSE create mode 100644 skills/grill-me/PATCHES.md create mode 100644 skills/grill-me/SKILL.md create mode 100644 skills/grill-me/UPSTREAM.md create mode 100644 skills/grill-me/agents/openai.yaml create mode 100644 skills/grill-with-docs/LICENSE create mode 100644 skills/grill-with-docs/PATCHES.md create mode 100644 skills/grill-with-docs/SKILL.md create mode 100644 skills/grill-with-docs/UPSTREAM.md create mode 100644 skills/grill-with-docs/agents/openai.yaml create mode 100644 skills/grilling/LICENSE create mode 100644 skills/grilling/PATCHES.md create mode 100644 skills/grilling/SKILL.md create mode 100644 skills/grilling/UPSTREAM.md create mode 100644 skills/grilling/agents/openai.yaml create mode 100644 skills/handoff/LICENSE create mode 100644 skills/handoff/PATCHES.md create mode 100644 skills/handoff/SKILL.md create mode 100644 skills/handoff/UPSTREAM.md create mode 100644 skills/handoff/agents/openai.yaml create mode 100644 skills/implement/LICENSE create mode 100644 skills/implement/PATCHES.md create mode 100644 skills/implement/SKILL.md create mode 100644 skills/implement/UPSTREAM.md create mode 100644 skills/implement/agents/openai.yaml create mode 100644 skills/improve-codebase-architecture/HTML-REPORT.md create mode 100644 skills/improve-codebase-architecture/LICENSE create mode 100644 skills/improve-codebase-architecture/PATCHES.md create mode 100644 skills/improve-codebase-architecture/SKILL.md create mode 100644 skills/improve-codebase-architecture/UPSTREAM.md create mode 100644 skills/improve-codebase-architecture/agents/openai.yaml create mode 100644 skills/loop-me/LICENSE create mode 100644 skills/loop-me/PATCHES.md create mode 100644 skills/loop-me/SKILL.md create mode 100644 skills/loop-me/UPSTREAM.md create mode 100644 skills/loop-me/agents/openai.yaml create mode 100644 skills/prototype/LICENSE create mode 100644 skills/prototype/LOGIC.md create mode 100644 skills/prototype/PATCHES.md create mode 100644 skills/prototype/SKILL.md create mode 100644 skills/prototype/UI.md create mode 100644 skills/prototype/UPSTREAM.md create mode 100644 skills/prototype/agents/openai.yaml create mode 100644 skills/qa/LICENSE create mode 100644 skills/qa/PATCHES.md create mode 100644 skills/qa/SKILL.md create mode 100644 skills/qa/UPSTREAM.md create mode 100644 skills/qa/agents/openai.yaml create mode 100644 skills/research/LICENSE create mode 100644 skills/research/PATCHES.md create mode 100644 skills/research/SKILL.md create mode 100644 skills/research/UPSTREAM.md create mode 100644 skills/research/agents/openai.yaml create mode 100644 skills/tdd/LICENSE create mode 100644 skills/tdd/PATCHES.md create mode 100644 skills/tdd/SKILL.md create mode 100644 skills/tdd/UPSTREAM.md create mode 100644 skills/tdd/agents/openai.yaml create mode 100644 skills/tdd/mocking.md create mode 100644 skills/tdd/tests.md create mode 100644 skills/teach/GLOSSARY-FORMAT.md create mode 100644 skills/teach/LEARNING-RECORD-FORMAT.md create mode 100644 skills/teach/LICENSE create mode 100644 skills/teach/MISSION-FORMAT.md create mode 100644 skills/teach/PATCHES.md create mode 100644 skills/teach/RESOURCES-FORMAT.md create mode 100644 skills/teach/SKILL.md create mode 100644 skills/teach/UPSTREAM.md create mode 100644 skills/teach/agents/openai.yaml create mode 100644 skills/to-spec/LICENSE create mode 100644 skills/to-spec/PATCHES.md create mode 100644 skills/to-spec/SKILL.md create mode 100644 skills/to-spec/UPSTREAM.md create mode 100644 skills/to-spec/agents/openai.yaml create mode 100644 skills/to-tickets/LICENSE create mode 100644 skills/to-tickets/PATCHES.md create mode 100644 skills/to-tickets/SKILL.md create mode 100644 skills/to-tickets/UPSTREAM.md create mode 100644 skills/to-tickets/agents/openai.yaml create mode 100644 skills/ubiquitous-language/LICENSE create mode 100644 skills/ubiquitous-language/PATCHES.md create mode 100644 skills/ubiquitous-language/SKILL.md create mode 100644 skills/ubiquitous-language/UPSTREAM.md create mode 100644 skills/ubiquitous-language/agents/openai.yaml create mode 100644 skills/wayfinder/LICENSE create mode 100644 skills/wayfinder/PATCHES.md create mode 100644 skills/wayfinder/SKILL.md create mode 100644 skills/wayfinder/UPSTREAM.md create mode 100644 skills/wayfinder/agents/openai.yaml create mode 100644 skills/writing-great-skills/GLOSSARY.md create mode 100644 skills/writing-great-skills/LICENSE create mode 100644 skills/writing-great-skills/PATCHES.md create mode 100644 skills/writing-great-skills/SKILL.md create mode 100644 skills/writing-great-skills/UPSTREAM.md create mode 100644 skills/writing-great-skills/agents/openai.yaml create mode 100644 sources/mattpocock-skills/README.md create mode 100644 sources/mattpocock-skills/README.zh-CN.md create mode 100644 tests/third-party-collection-tests.ps1 diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml new file mode 100644 index 0000000..e868c31 --- /dev/null +++ b/.github/workflows/quality.yml @@ -0,0 +1,24 @@ +name: Third-party collection quality + +on: + push: + pull_request: + +permissions: + contents: read + +jobs: + powershell: + runs-on: windows-latest + steps: + - name: Checkout private collection + uses: actions/checkout@v4 + - name: Checkout pinned public upstream + shell: pwsh + run: git clone --depth 1 --branch v1.1.0 https://github.com/mattpocock/skills.git "$env:RUNNER_TEMP\mattpocock-skills" + - name: Verify pinned upstream and package contract + shell: pwsh + run: .\scripts\sync-upstream.ps1 -Mode check -UpstreamRoot "$env:RUNNER_TEMP\mattpocock-skills" + - name: Run collection assertions + shell: pwsh + run: .\tests\third-party-collection-tests.ps1 -UpstreamRoot "$env:RUNNER_TEMP\mattpocock-skills" diff --git a/AGENTS.md b/AGENTS.md index 6e16481..c380fb6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,90 +1,85 @@ # skills-3rdParty Maintenance Contract -## Boundary - -This repository contains only third-party Skills requiring a local -modification, compatibility adaptation, repackaging, deliberate version -stabilization, or behaviorally different variant. It is a provenance and -maintenance boundary, not a generic Skill catalog. - -Do not add an unchanged upstream Skill. If direct upstream use works, document -or recommend the upstream source outside this repository. Do not present a -modified third-party Skill as original work. - -## Source-based layout - -Group every admitted package by original source: - -~~~text -/ -├── README.md -└── / - ├── SKILL.md - ├── UPSTREAM.md - ├── PATCHES.md - └── -~~~ - -Do not make empty source groups or group primarily by generic capability. - -## Admission before import - -Before copying or modifying an upstream package: - -1. Follow [docs/THIRD_PARTY_ADMISSION.md](docs/THIRD_PARTY_ADMISSION.md). -2. Record concrete evidence that direct upstream use is insufficient. -3. Identify the original repository, package path, canonical URL, selected - tag/ref, immutable resolved commit, author, and license obligations. -4. Define the smallest local change set, expected behavioral differences, - synchronization method, installation record, and test evidence. -5. Obtain the required review before release. - -Only these categories can justify a fork: compatibility fix, additional Agent -host support, stable pinned behavior unavailable upstream, package -repair/repackaging, or deliberate behavioral variation. Convenience is a -rejection. - -## Required records - -Every admitted package must include: - -- an entry in CATALOG.md; -- completed UPSTREAM.md from [templates/UPSTREAM.md](templates/UPSTREAM.md); -- completed PATCHES.md from [templates/PATCHES.md](templates/PATCHES.md); -- applicable upstream license and notices; -- original repository/path and immutable upstream revision; -- local-change rationale, scope, known differences, and install record; -- synchronization procedure and last synchronization date; and -- an entry in [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json). - -Its source group must include README.md from -[templates/SOURCE_README.md](templates/SOURCE_README.md). It owns source-wide -provenance, installation, and synchronization facts; package files own -package-specific facts. - -## Updates and release - -Follow [docs/MAINTENANCE.md](docs/MAINTENANCE.md). Preserve and reapply the -documented patch set when synchronizing. Do not silently resolve a rebase -conflict or license change. Imports are snapshots, never merged upstream Git -histories. - -Follow [docs/INSTALLATION.md](docs/INSTALLATION.md) to distinguish original -upstream installation from locally modified installation. Never publish an -installer command until its actual behavior has been verified for the released -package and target host. - -For a package add, rename, update, deprecation, sync, or removal, review: - -- root README and source README; -- source catalog; -- package provenance and patch records; -- licenses/notices and UPSTREAM_LOCK.json; -- installation guidance and verification evidence; -- test/review evidence; and -- release notes. - -Static path or Markdown checks are not runtime evidence. Do not release with -unresolved provenance, license, patch, synchronization, installation, or -behavioral-difference records. If upstream eliminates the concrete fork need, -prefer removal and direct users to upstream. +English | [简体中文](README.zh-CN.md) + +This repository is the private, auditable home for approved third-party Skill +packages. It supports three explicit source states: + +1. **Pinned upstream mirror** — an unchanged upstream package snapshot at an + immutable revision, plus clearly labeled collection metadata adapters when + the host contract requires them. +2. **Modified upstream fork** — an upstream package with a documented, + behavior-affecting or compatibility patch and a concrete reason direct use + is insufficient. +3. **External direct dependency** — a package that is intentionally not copied; + its authoritative upstream URL and required revision are recorded instead. + +This broader third-party boundary does not weaken the public first-party +repository's ownership gate. Unmodified third-party packages must never enter +`skills/` in `LightDevCoder/skills`. + +## Package and source layout + +The installer-facing package root is `skills//` because the Skills +CLI and Agent hosts discover packages there. Source grouping is preserved in +`UPSTREAM_LOCK.json`, `sources/mattpocock-skills/README.md`, and each package's +`source_group` and upstream path; aesthetic nesting must not break discovery. + +Every mirrored package contains the complete upstream package files plus: + +- `agents/openai.yaml` — collection metadata adapter, if upstream does not + provide host metadata; +- `LICENSE` — package-local copy of the upstream license; +- `UPSTREAM.md` — provenance, pin, installation, and update record; and +- `PATCHES.md` — explicit local-difference ledger. + +The machine-readable manifest is `UPSTREAM_LOCK.json`; the selected allowlist +is `config/upstream-allowlist.json`. + +## Allowlist and provenance gates + +- Never add a package outside the named allowlist without a separate user + decision and a manifest update. +- Pin an upstream tag/ref and verify its full resolved commit before sync. +- Preserve every upstream-referenced resource; a source checkout scan is not + a fresh-install proof. +- Keep upstream-managed file hashes unchanged unless a local patch record + explicitly names and reviews the difference. +- Preserve the upstream license and distinguish snapshot, patch, and external + dependency states in catalog and release records. +- `grill-me` depends on `grilling`; `grill-with-docs` depends on `grilling` and + `domain-modeling`. These are declared peer Skills, not hidden execution. +- `ask-matt` remains navigation-only. It may describe routes but must not + install, invoke, or orchestrate another Skill. +- `writing-great-skills` is an authoring knowledge source, not an implicit + runtime dependency of first-party `learn-anything`. + +## Synchronization + +Use the controlled script with the read-only upstream checkout: + +```powershell +.\scripts\sync-upstream.ps1 -Mode check +.\scripts\sync-upstream.ps1 -Mode dry-run +.\scripts\sync-upstream.ps1 -Mode diff +.\scripts\sync-upstream.ps1 -Mode sync +``` + +`check` fails on missing packages, missing referenced resources, drift from the +pinned revision, or unauthorized local changes to upstream-managed files. +`dry-run` and `diff` do not write. `sync` is allowed only after reviewing the +upstream revision and its diff. Never silently resolve a conflict or overwrite +an unrecorded local patch. + +## Review, installation, and release + +Package changes require structural, resource, provenance, synchronization, +installation, invocation, and negative-path evidence. `review-loop` owns the +final `PASS`, `FAIL`, or `BLOCKED` verdict; a script or specialist report is +evidence, not the verdict. + +Before release, verify whole-collection and single-package installation into +fresh destinations, discovery without the source checkout, repeat-install +behavior, representative dependency boundaries, and private-repository +access. Record real results under `docs/evidence/releases/` and mark any +unexecuted item `NOT TESTED` or missing independent review `BLOCKED`. diff --git a/CATALOG.md b/CATALOG.md index 39e5316..436e2c1 100644 --- a/CATALOG.md +++ b/CATALOG.md @@ -1,41 +1,65 @@ -# Third-Party Source Catalog +# Third-Party Skills Catalog -This catalog records modified third-party source groups only. It is -intentionally empty while direct upstream use remains sufficient and no -concrete fork has passed admission. +[中文目录](CATALOG.zh-CN.md) -## Current state +This catalog is derived from the 23-entry allowlist and +[UPSTREAM_LOCK.json](UPSTREAM_LOCK.json). Package behavior remains owned by +each upstream `SKILL.md`; this file records source and installation facts. + +## Collection status | Field | Value | | --- | --- | -| Source groups | 0 | -| Modified packages | 0 | -| Lock inventory | [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json), entries: 0 | -| Stable release | [v0.1.0](https://github.com/LightDevCoder/skills-3rdParty/releases/tag/v0.1.0) — private governance release | -| Installation authority | [docs/INSTALLATION.md](docs/INSTALLATION.md) | -| Admission authority | [docs/THIRD_PARTY_ADMISSION.md](docs/THIRD_PARTY_ADMISSION.md) | - -No package is admitted here. An empty catalog is a valid governance-only -state; do not create a source group merely to populate this table. +| Repository | `LightDevCoder/skills-3rdParty` | +| Visibility | Private; intentionally not public | +| Packages | 23 selected Matt Pocock Skills | +| Upstream tag | `v1.1.0` | +| Upstream commit | `d574778f94cf620fcc8ce741584093bc650a61d3` | +| Local release | `v0.1.1` after publication evidence | +| Manifest | [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) | +| Sync | [scripts/sync-upstream.ps1](scripts/sync-upstream.ps1) | -## Direct upstream boundary +## Source groups -Unmodified Matt Pocock Skills remain at -[mattpocock/skills](https://github.com/mattpocock/skills) and are installed -directly from upstream. They must not be copied into this repository. +| Source group | Packages | Original upstream root | +| --- | ---: | --- | +| engineering | 13 | `skills/engineering/` | +| productivity | 6 | `skills/productivity/` | +| deprecated | 3 | `skills/deprecated/` | +| in-progress | 1 | `skills/in-progress/` | -## Future source-group record +The local install layout is intentionally flat under `skills/` to match the +Skills CLI's discovery paths. The upstream grouping is not discarded: every +manifest entry retains its original path and source group. -When a justified variant is admitted, add one entry with: +## Selected packages -- original source identifier and repository; -- package path, immutable upstream ref and resolved commit; -- concrete fork necessity; -- license or notice record; -- local patch record and known differences; -- released local installation path; and -- synchronization date and evidence. +| Skill | Source group | Upstream path | Local state | Dependencies | +| --- | --- | --- | --- | --- | +| `ask-matt` | engineering | `skills/engineering/ask-matt` | snapshot + metadata adapter | none; navigation-only | +| `codebase-design` | engineering | `skills/engineering/codebase-design` | snapshot + metadata adapter | none | +| `code-review` | engineering | `skills/engineering/code-review` | snapshot + metadata adapter | none | +| `design-an-interface` | deprecated | `skills/deprecated/design-an-interface` | snapshot + metadata adapter | none | +| `diagnosing-bugs` | engineering | `skills/engineering/diagnosing-bugs` | snapshot + metadata adapter | none | +| `domain-modeling` | engineering | `skills/engineering/domain-modeling` | snapshot + metadata adapter | none | +| `grilling` | productivity | `skills/productivity/grilling` | snapshot + metadata adapter | none | +| `grill-me` | productivity | `skills/productivity/grill-me` | snapshot + metadata adapter | `grilling` | +| `grill-with-docs` | engineering | `skills/engineering/grill-with-docs` | snapshot + metadata adapter | `grilling`, `domain-modeling` | +| `handoff` | productivity | `skills/productivity/handoff` | snapshot + metadata adapter | none | +| `implement` | engineering | `skills/engineering/implement` | snapshot + metadata adapter | none | +| `improve-codebase-architecture` | engineering | `skills/engineering/improve-codebase-architecture` | snapshot + metadata adapter | none | +| `loop-me` | in-progress | `skills/in-progress/loop-me` | snapshot + metadata adapter | none | +| `prototype` | engineering | `skills/engineering/prototype` | snapshot + metadata adapter | none | +| `qa` | deprecated | `skills/deprecated/qa` | snapshot + metadata adapter | none | +| `research` | engineering | `skills/engineering/research` | snapshot + metadata adapter | none | +| `tdd` | engineering | `skills/engineering/tdd` | snapshot + metadata adapter | none | +| `teach` | productivity | `skills/productivity/teach` | snapshot + metadata adapter | none | +| `to-spec` | engineering | `skills/engineering/to-spec` | snapshot + metadata adapter | none | +| `to-tickets` | engineering | `skills/engineering/to-tickets` | snapshot + metadata adapter | none | +| `ubiquitous-language` | deprecated | `skills/deprecated/ubiquitous-language` | snapshot + metadata adapter | none | +| `wayfinder` | engineering | `skills/engineering/wayfinder` | snapshot + metadata adapter | none; upstream template contains an example `link` placeholder | +| `writing-great-skills` | productivity | `skills/productivity/writing-great-skills` | snapshot + metadata adapter | authoring knowledge only | -The corresponding source README, UPSTREAM.md, PATCHES.md, license/notices, -lock entry, installation evidence, and release notes must be updated in the -same change. +Each package has a package-local [UPSTREAM.md](skills/ask-matt/UPSTREAM.md) +and [PATCHES.md](skills/ask-matt/PATCHES.md); replace the package name in the +path to inspect another entry. diff --git a/CATALOG.zh-CN.md b/CATALOG.zh-CN.md new file mode 100644 index 0000000..dc03677 --- /dev/null +++ b/CATALOG.zh-CN.md @@ -0,0 +1,41 @@ +# 第三方 Skills 目录 + +[English](CATALOG.md) + +本目录由 23 项 allowlist 与 [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) 同步， +只记录来源和安装事实；行为仍以各 upstream `SKILL.md` 及其资源为准。 + +## 集合状态 + +| 字段 | 值 | +| --- | --- | +| 仓库 | `LightDevCoder/skills-3rdParty` | +| 可见性 | Private，刻意不公开 | +| 包数量 | Matt Pocock 指定 Skill 23 个 | +| upstream tag | `v1.1.0` | +| upstream commit | `d574778f94cf620fcc8ce741584093bc650a61d3` | +| 本地 release | `v0.1.1`，须以真实发布证据为准 | +| manifest | [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) | +| 同步工具 | [scripts/sync-upstream.ps1](scripts/sync-upstream.ps1) | + +## Source group + +| 分组 | 数量 | upstream 根路径 | +| --- | ---: | --- | +| engineering | 13 | `skills/engineering/` | +| productivity | 6 | `skills/productivity/` | +| deprecated | 3 | `skills/deprecated/` | +| in-progress | 1 | `skills/in-progress/` | + +本地安装路径保持为 `skills/` 下的扁平目录，以符合 CLI 发现规则；原始分组 +和完整 upstream path 均保留在 manifest 中。 + +## 依赖重点 + +- `grill-me` → `grilling` +- `grill-with-docs` → `grilling`、`domain-modeling` +- `ask-matt`：仅导航；不执行、不安装、不编排 +- `writing-great-skills`：authoring knowledge only + +23 个包的逐项路径、资源、checksum、本地状态和 provenance 请直接查看 +[UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) 及包内 `UPSTREAM.md` / `PATCHES.md`。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 08a9faf..2f1a71c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,25 +1,32 @@ # Changelog -All notable changes to this repository are recorded here. +[简体中文](CHANGELOG.zh-CN.md) -## 0.1.0 — 2026-07-23 +All release claims below require the corresponding repository evidence. A +draft entry is not proof of a tag, release, installation, or independent +review. + +## 0.1.1 — 2026-07-23 (pending evidence confirmation) ### Added -- Governance-only foundation for third-party admission, provenance, licensing, - patch records, synchronization, installation, and release maintenance. -- Empty upstream-lock inventory and reusable source/package record templates. -- Human-readable empty source catalog synchronized with the governance-only - boundary. -- Governance documentation and installation consistency test. +- Exactly 23 selected Matt Pocock Skills from upstream `v1.1.0`, pinned to + `d574778f94cf620fcc8ce741584093bc650a61d3`. +- Complete per-package upstream resources, license copies, metadata adapters, + provenance records, patch ledgers, and machine-readable checksums. +- Explicit pinned-mirror, modified-fork, and external-dependency governance. +- `check`, `dry-run`, `diff`, and `sync` maintenance tooling with an + unauthorized-local-patch negative fixture. +- English/Chinese catalogs, installation, maintenance, provenance, update, + review, source-group, and release-evidence documents. -- No upstream Skill copy, source group, modified package, installer - verification, or local package installation command; the private release is - governance-only by design. +### Release evidence -### Release verification +See [v0.1.1 release receipt](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md). +Until the real tag, private release, fresh-install verification, and +independent review exist, any unrun item remains `NOT TESTED` or `BLOCKED`. + +## 0.1.0 — 2026-07-23 -- Published at https://github.com/LightDevCoder/skills-3rdParty. -- Stable tag: v0.1.0. -- Repository identity, private visibility, empty package boundary, and - governance test were verified against the released content. +The initial private governance-only release. Its empty boundary has been +superseded by the explicitly admitted pinned upstream mirror in `v0.1.1`. diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md new file mode 100644 index 0000000..aa3c989 --- /dev/null +++ b/CHANGELOG.zh-CN.md @@ -0,0 +1,20 @@ +# 更新日志 + +[English](CHANGELOG.md) + +## 0.1.1 — 2026-07-23（待真实发布证据确认） + +### 新增与修复 + +- 按 allowlist 收录 Matt Pocock upstream `v1.1.0` 的 23 个 Skill，并锁定完整 + commit、逐文件 checksum、license、provenance 和依赖状态。 +- 支持 pinned upstream mirror、modified upstream fork、external direct dependency + 三种第三方状态。 +- 增加 `check`、`dry-run`、`diff`、`sync` 同步工具与 unauthorized patch 负向测试。 +- 增加中英文目录、安装、维护、provenance、更新、review、source-group 和 release + evidence 文档。 + +### 发布证据 + +在真实 tag/release、fresh install 和 independent review 完成前，本条目不得写成 +已发布或已验证；请查看 `docs/evidence/releases/v0.1.1/`。 diff --git a/README.md b/README.md index c0d7482..af7e0b6 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,84 @@ -# skills-3rdParty - -This repository is the governed home for locally modified third-party Skills. -It is not a mirror, convenience cache, or alternative installation source for -an unchanged upstream Skill. - -## Current status - -The repository remains governance-only, but its stable governance release is -v0.1.0 at -[LightDevCoder/skills-3rdParty](https://github.com/LightDevCoder/skills-3rdParty/releases/tag/v0.1.0). -It has no admitted source group, modified package, or usable local installation -command. The empty state is intentional and is recorded in -[CATALOG.md](CATALOG.md) and [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json). - -## Admission boundary - -A Skill may enter only when direct upstream use is concretely insufficient for -one of these reasons: - -- a compatibility fix is needed; -- another Agent host must be supported; -- stable pinned behavior is unavailable through direct installation; -- the upstream package needs repair or repackaging; or -- the owner deliberately maintains a behaviorally different variant. - -Convenience, discoverability, backup, or a preference for one catalog is never -enough. An upstream Skill that works unchanged stays upstream and is installed -from its original source. - -## Structure - -~~~text -. -├── AGENTS.md -├── CATALOG.md -├── CHANGELOG.md -├── UPSTREAM_LOCK.json -├── docs/ -│ ├── THIRD_PARTY_ADMISSION.md -│ ├── INSTALLATION.md -│ └── MAINTENANCE.md -└── templates/ - ├── PATCHES.md - ├── SOURCE_README.md - └── UPSTREAM.md -~~~ - -An admitted package is grouped by original source, never by generic -capability: - -~~~text -/ -├── README.md -└── / - ├── SKILL.md - ├── UPSTREAM.md - ├── PATCHES.md - └── -~~~ - -Create source groups only after admission. Use -[templates/SOURCE_README.md](templates/SOURCE_README.md) for the source record -and [templates/UPSTREAM.md](templates/UPSTREAM.md) plus -[templates/PATCHES.md](templates/PATCHES.md) for every package. - -## Installation distinction - -| Need | Authoritative source | Required record | +# Private Third-Party Skills Collection + +[中文说明](README.zh-CN.md) + +`LightDevCoder/skills-3rdParty` is a private, source-audited collection of +third-party Agent Skills. It is intentionally separate from the public +first-party [LightDevCoder/skills](https://github.com/LightDevCoder/skills) +repository and remains private. + +## Current release + +The next stable release is `v0.1.1` on the local `codex/t19-skills-3rdParty` +change set; publication is recorded only after the real tag, release, and +fresh-install evidence exist. The collection mirrors exactly 23 selected Matt +Pocock Skills from upstream tag `v1.1.0`, resolved to +`d574778f94cf620fcc8ce741584093bc650a61d3`. + +The authoritative inventory is [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json). It +records upstream paths, per-file checksums, source groups, license paths, +dependencies, local modification state, and release installation semantics. + +## What is included + +| State | Meaning | Record | | --- | --- | --- | -| Original unchanged upstream Skill | Original upstream repository and its documentation | No local copy or lock entry. | -| Locally modified third-party Skill | A released source-grouped package in this repository | Provenance, license, patch, synchronization, and installation records. | - -Read [docs/INSTALLATION.md](docs/INSTALLATION.md) before using either path. -Its command forms are templates until a release verifies actual installer -behavior. - -## Governance - -- [Source catalog](CATALOG.md) -- [Governance documentation check](tests/governance-docs-tests.ps1) -- [Admission policy](docs/THIRD_PARTY_ADMISSION.md) defines fork-necessity and - evidence gates. -- [Maintenance](docs/MAINTENANCE.md) defines synchronization, conflict, - regression, release, and removal rules. -- [Installation](docs/INSTALLATION.md) separates original-upstream and - locally-modified installation, pinning, fallback, and provenance. -- [AGENTS.md](AGENTS.md) is the maintenance contract. -- [UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) is the inventory of admitted - modified packages and is intentionally empty today. - -This governance release makes no runtime or local package installer claim; -its v0.1.0 release metadata and empty boundary are intentional. +| Pinned upstream mirror | Upstream package files are copied at an immutable revision; only the collection metadata adapter is local. | `UPSTREAM_LOCK.json`, `skills//UPSTREAM.md` | +| Modified upstream fork | A behavior or compatibility change is explicitly justified and patched. | `UPSTREAM.md`, `PATCHES.md`, tests | +| External direct dependency | The package is not copied; users install from its authoritative upstream source. | Source record and installation docs | + +The 23 selected packages are installed under `skills//` so the +Skills CLI can discover them. Original upstream grouping (`engineering`, +`productivity`, `deprecated`, and `in-progress`) remains auditable in the +manifest and [source-group record](sources/mattpocock-skills/README.md). + +## Quick installation + +The `#v0.1.1` fragment pins this private collection release. It does not claim +that the public shorthand without a fragment is immutable. + +Install the complete private collection: + +```text +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 +``` + +Install one package: + +```text +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill grill-me +``` + +Read [Installation](docs/INSTALLATION.md) for private-repository credentials, +fresh destinations, repeat installation, discovery, and the manual fallback. + +## Dependencies and boundaries + +- `grill-me` retains its `grilling` dependency. +- `grill-with-docs` retains its `grilling` and `domain-modeling` dependencies. +- `ask-matt` is navigation-only; it never becomes an automatic executor. +- `writing-great-skills` is authoring knowledge, not an implicit runtime + dependency of first-party `learn-anything`. + +## Maintenance and evidence + +- [Third-party admission](docs/THIRD_PARTY_ADMISSION.md) +- [Provenance policy](docs/PROVENANCE_POLICY.md) +- [Update policy](docs/UPDATE_POLICY.md) +- [Maintenance](docs/MAINTENANCE.md) +- [Installation and fresh-install verification](docs/INSTALLATION.md) +- [Review policy](docs/REVIEW_POLICY.md) +- [Catalog](CATALOG.md) +- [Changelog](CHANGELOG.md) +- [Release evidence](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md) +- [Sync tool](scripts/sync-upstream.ps1) + +Run the repository checks from a clean checkout: + +```powershell +.\scripts\sync-upstream.ps1 -Mode check +.\tests\third-party-collection-tests.ps1 +``` + +Structural checks do not replace fresh installation, discovery, or independent +review evidence. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..949d4a8 --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,58 @@ +# 私有第三方 Skills 集合 + +[English](README.md) + +`LightDevCoder/skills-3rdParty` 是私有、可审计的第三方 Agent Skill 集合， +与公开的[第一方集合](https://github.com/LightDevCoder/skills)严格分开， +仓库保持 private。 + +## 当前版本 + +本次变更目标版本为 `v0.1.1`；只有真实 tag、release 和 fresh-install 证据 +产生后才可宣称已发布。集合准确收录 Matt Pocock 上游 `v1.1.0` 的 23 个 +指定 Skill，解析 commit 为 `d574778f94cf620fcc8ce741584093bc650a61d3`。 + +[UPSTREAM_LOCK.json](UPSTREAM_LOCK.json) 是权威清单，记录 upstream 路径、 +逐文件 checksum、source group、许可证、依赖、本地修改状态和安装语义。 + +## 三种来源状态 + +- **Pinned upstream mirror：** 在不可变 revision 上保存完整 upstream 包； + 若主机需要，额外的集合 metadata adapter 必须单独标记。 +- **Modified upstream fork：** 有明确兼容性、重打包、稳定 pin、主机支持或 + 行为差异原因，并在 `PATCHES.md` 中记录。 +- **External direct dependency：** 不复制，记录权威 upstream 与安装方式。 + +23 个包位于 `skills//` 以保持 Skills CLI 发现能力；原始的 +`engineering`、`productivity`、`deprecated`、`in-progress` 分组保存在 +manifest 和 [source-group 记录](sources/mattpocock-skills/README.md)中。 + +## 安装 + +```text +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill grill-me +``` + +`#v0.1.1` 固定的是本地集合 release；包内容另外固定在 upstream +`v1.1.0`/完整 commit。请阅读[安装指南](docs/INSTALLATION.md)了解 private +凭据、全新目录、重复安装、发现验证和手工回退。 + +## 边界与维护 + +- `grill-me` 保留 `grilling` 依赖。 +- `grill-with-docs` 保留 `grilling` 与 `domain-modeling` 依赖。 +- `ask-matt` 只能导航，不得自动执行或安装。 +- `writing-great-skills` 是 authoring knowledge，不是 `learn-anything` 的 + 隐式运行时依赖。 + +请从[第三方准入](docs/THIRD_PARTY_ADMISSION.md)、[provenance policy](docs/PROVENANCE_POLICY.md)、 +[update policy](docs/UPDATE_POLICY.md)、[维护](docs/MAINTENANCE.md)、[review policy](docs/REVIEW_POLICY.md)、 +[目录](CATALOG.md)和[发布证据](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md)开始。 + +```powershell +.\scripts\sync-upstream.ps1 -Mode check +.\tests\third-party-collection-tests.ps1 +``` + +结构测试不等于 fresh installation、runtime 或独立 review 证据。 diff --git a/UPSTREAM_LOCK.json b/UPSTREAM_LOCK.json index 5041764..65ea20b 100644 --- a/UPSTREAM_LOCK.json +++ b/UPSTREAM_LOCK.json @@ -1,18 +1,1002 @@ { - "schemaVersion": 1, - "description": "Authoritative inventory of admitted locally modified third-party Skills. Direct-use upstream Skills are intentionally excluded.", - "entryRequiredFields": [ - "sourceId", - "skillId", - "upstreamRepository", - "upstreamPath", - "upstreamRef", - "upstreamCommit", - "license", - "upstreamRecord", - "patchRecord", - "lastSynchronized", - "modifiedInstallation" + "schema_version": 2, + "repository": "LightDevCoder/skills-3rdParty", + "visibility": "private", + "source_kind": "pinned-upstream-mirror-with-collection-metadata-adapter", + "upstream": { + "repository": "mattpocock/skills", + "url": "https://github.com/mattpocock/skills", + "selected_tag": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "license": "MIT", + "license_source": "LICENSE at upstream repository root" + }, + "allowlist": [ + "ask-matt", + "codebase-design", + "code-review", + "design-an-interface", + "diagnosing-bugs", + "domain-modeling", + "grilling", + "grill-me", + "grill-with-docs", + "handoff", + "implement", + "improve-codebase-architecture", + "loop-me", + "prototype", + "qa", + "research", + "tdd", + "teach", + "to-spec", + "to-tickets", + "ubiquitous-language", + "wayfinder", + "writing-great-skills" ], - "entries": [] + "collection_checksum": "c712abb181e90de8502dd90d6c31f64c87e647d072fac256e9b6147cb8f2ec65", + "generated_utc": "2026-07-23T03:06:49.4499494Z", + "installation": { + "whole_collection": "npx skills add LightDevCoder/skills-3rdParty#v0.1.1", + "single_skill": "npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill ", + "revision_semantics": "The #v0.1.1 fragment pins the local collection release; the mirrored package content is pinned to upstream v1.1.0 and its resolved commit." + }, + "entries": [ + { + "package_name": "ask-matt", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/ask-matt", + "local_package_path": "skills/ask-matt", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "a74cf85e50937410c1b75856d2118669aed0b9905b1d699b8da2757aa12a05c7", + "files": [ + { + "path": "SKILL.md", + "sha256": "1905dee1e9d0a4b29c04f3bf507cc432f71a251c2ae1829a3bfdb940b1437e94", + "bytes": 7890 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/ask-matt/LICENSE", + "provenance_path": "skills/ask-matt/UPSTREAM.md", + "patch_record_path": "skills/ask-matt/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "codebase-design", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/codebase-design", + "local_package_path": "skills/codebase-design", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "36fe7ffcce1c5aa6ca4d895f6c49b6a4dca855777be06a32c2e3b95cd28da250", + "files": [ + { + "path": "DEEPENING.md", + "sha256": "793b7704484b704e1b5f93aac197a5758018e838afdb8bcb08ad6465960586dc", + "bytes": 2596 + }, + { + "path": "DESIGN-IT-TWICE.md", + "sha256": "578a9a67c20fda10a7e5442e2208d0e5cf68601d012b0ecd6469e651100a308f", + "bytes": 2756 + }, + { + "path": "SKILL.md", + "sha256": "22d3815e5629ddea7ed7c9f8e7c330f6a1559466ee904e58371e1e8a10be0c4b", + "bytes": 6602 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/codebase-design/LICENSE", + "provenance_path": "skills/codebase-design/UPSTREAM.md", + "patch_record_path": "skills/codebase-design/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 3 + } + }, + { + "package_name": "code-review", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/code-review", + "local_package_path": "skills/code-review", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "2ea7e85d156bd697cab1b21fb1afb8519364d864d137f8ffc7face9e595c0cdd", + "files": [ + { + "path": "SKILL.md", + "sha256": "e5507100ac01a04d082ac23ac6311d0fec8699d1ab00c599db7064039b819f63", + "bytes": 6829 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/code-review/LICENSE", + "provenance_path": "skills/code-review/UPSTREAM.md", + "patch_record_path": "skills/code-review/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "design-an-interface", + "source_group": "deprecated", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/deprecated/design-an-interface", + "local_package_path": "skills/design-an-interface", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "e5a512c83d01a5bb845b1ea2b48b658491095c5c04e23fb08469413bc2778c65", + "files": [ + { + "path": "SKILL.md", + "sha256": "88193ab179032918cdea0afe74b8610d6d079ac51191f286c10e9e47839a9e6b", + "bytes": 3460 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/design-an-interface/LICENSE", + "provenance_path": "skills/design-an-interface/UPSTREAM.md", + "patch_record_path": "skills/design-an-interface/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "diagnosing-bugs", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/diagnosing-bugs", + "local_package_path": "skills/diagnosing-bugs", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "e5633c97bf5e0e85b7ed627e285c32d1736358b4c69f286f11890b7a3464ca45", + "files": [ + { + "path": "scripts/hitl-loop.template.sh", + "sha256": "a14e4d722c2324c130d331e87267bc9f9b03bbaf32c3b8e08310b039ea5e5863", + "bytes": 1205 + }, + { + "path": "SKILL.md", + "sha256": "3dfe5ec16b89a01dbc1bf606a1a1cfc32349e225f3bb75a3fb86117974a83cb8", + "bytes": 8670 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/diagnosing-bugs/LICENSE", + "provenance_path": "skills/diagnosing-bugs/UPSTREAM.md", + "patch_record_path": "skills/diagnosing-bugs/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 2 + } + }, + { + "package_name": "domain-modeling", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/domain-modeling", + "local_package_path": "skills/domain-modeling", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "2c6ecbee7a21c2039de3dd034c89a35814894b6d8730767c7bf3084de2a5c8eb", + "files": [ + { + "path": "ADR-FORMAT.md", + "sha256": "dba54707c3251660ecf7ee6ff154a816a62badddd4ef403062f3a34e23509636", + "bytes": 2813 + }, + { + "path": "CONTEXT-FORMAT.md", + "sha256": "f229cd8485b77ea76428ffb807058ebd1d254a391b9669b10081942d3d6e8dd3", + "bytes": 2359 + }, + { + "path": "SKILL.md", + "sha256": "004d5cb6258658f2e9cbf0d9f90bdc9104f8b83bd296556783800c31d503814f", + "bytes": 3501 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/domain-modeling/LICENSE", + "provenance_path": "skills/domain-modeling/UPSTREAM.md", + "patch_record_path": "skills/domain-modeling/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 3 + } + }, + { + "package_name": "grilling", + "source_group": "productivity", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/productivity/grilling", + "local_package_path": "skills/grilling", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "7966a979b8fb5c75c5f946af9df52d3cde94f387c1058c9213d727b7a2d79a68", + "files": [ + { + "path": "SKILL.md", + "sha256": "3ff64dbca5137e8d887bdf3caafbd9067376b251b507517fbe875b70dfb5d345", + "bytes": 833 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/grilling/LICENSE", + "provenance_path": "skills/grilling/UPSTREAM.md", + "patch_record_path": "skills/grilling/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "grill-me", + "source_group": "productivity", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/productivity/grill-me", + "local_package_path": "skills/grill-me", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "6cb3a6e07b201bf025b2f0af56a8bff02eff487b21405cdba13fb93876456d60", + "files": [ + { + "path": "SKILL.md", + "sha256": "9c71927d4f0fd32d815247b4ca1fc782d4c5f2f3c1d6d023d188d4a7e0299b21", + "bytes": 154 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "declared-peer-dependency", + "packages": [ + "grilling" + ], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/grill-me/LICENSE", + "provenance_path": "skills/grill-me/UPSTREAM.md", + "patch_record_path": "skills/grill-me/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "grill-with-docs", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/grill-with-docs", + "local_package_path": "skills/grill-with-docs", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "e053e365d6427a3b367db15b8dd10fd7321e2ef746b466f7f69e660f4dccd96a", + "files": [ + { + "path": "SKILL.md", + "sha256": "269376d5146332f597c4194fa1adef93b879ad62e0183c0d111a447e7af51be9", + "bytes": 252 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "declared-peer-dependency", + "packages": [ + "grilling", + "domain-modeling" + ], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/grill-with-docs/LICENSE", + "provenance_path": "skills/grill-with-docs/UPSTREAM.md", + "patch_record_path": "skills/grill-with-docs/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "handoff", + "source_group": "productivity", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/productivity/handoff", + "local_package_path": "skills/handoff", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "6f6913f9de6beb705b24bed73916c2c8a6e06913367fa977f0e901b9918aa457", + "files": [ + { + "path": "SKILL.md", + "sha256": "65e80725923677f128b1d3cf23397b4bf0cc8659cd408aaee5ab285d01aa54af", + "bytes": 895 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/handoff/LICENSE", + "provenance_path": "skills/handoff/UPSTREAM.md", + "patch_record_path": "skills/handoff/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "implement", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/implement", + "local_package_path": "skills/implement", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "999e56209065940682f9c729fdb7d4fd852fe5adff7b74aee89f96bd783c7da3", + "files": [ + { + "path": "SKILL.md", + "sha256": "30cd7bc1ebfb3891e85a1eed3b3b81aea0fa4ad4553a784de7f8e421b2d223e0", + "bytes": 448 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/implement/LICENSE", + "provenance_path": "skills/implement/UPSTREAM.md", + "patch_record_path": "skills/implement/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "improve-codebase-architecture", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/improve-codebase-architecture", + "local_package_path": "skills/improve-codebase-architecture", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "b3f5963f06bf0d72166df91fc7ceb99ed6e867c489ff0763f19fdcfbee078bb7", + "files": [ + { + "path": "HTML-REPORT.md", + "sha256": "a1b8f23e710e68c2bba04edc4c6b9001a08af7bdebb8bc01c6964e76c9ba4855", + "bytes": 6808 + }, + { + "path": "SKILL.md", + "sha256": "5408ce415a8610568edaf44bd7a32e35ca2b8a65051bcae7d3ed61801e20088d", + "bytes": 5487 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/improve-codebase-architecture/LICENSE", + "provenance_path": "skills/improve-codebase-architecture/UPSTREAM.md", + "patch_record_path": "skills/improve-codebase-architecture/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 2 + } + }, + { + "package_name": "loop-me", + "source_group": "in-progress", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/in-progress/loop-me", + "local_package_path": "skills/loop-me", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "ef766c16c8888e6bc82b9ac23143e4037d91bae6ad7b4fe18326b64751e586f3", + "files": [ + { + "path": "SKILL.md", + "sha256": "8214df9c466030e90172421d1d26f2a71dc3197ffbc7f354bac20c7d88318169", + "bytes": 2584 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/loop-me/LICENSE", + "provenance_path": "skills/loop-me/UPSTREAM.md", + "patch_record_path": "skills/loop-me/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "prototype", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/prototype", + "local_package_path": "skills/prototype", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "262a21afd7a7c4187bc680615a21953b3e2b6418f0c743c0dfb784490e6e9a80", + "files": [ + { + "path": "LOGIC.md", + "sha256": "3ce34ce7c2d06bcbdac4d846aafc488bbef0b2cd067134eeeda34c3804842f2f", + "bytes": 5673 + }, + { + "path": "SKILL.md", + "sha256": "9c750b700a6396697ddce3bcca04d322179d73c5d4f7d82268309eff84fd1176", + "bytes": 3032 + }, + { + "path": "UI.md", + "sha256": "be9846286540f0db138f7ba02e0b52ac8ba14ee561992be6788e4725284c89b7", + "bytes": 6901 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/prototype/LICENSE", + "provenance_path": "skills/prototype/UPSTREAM.md", + "patch_record_path": "skills/prototype/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 3 + } + }, + { + "package_name": "qa", + "source_group": "deprecated", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/deprecated/qa", + "local_package_path": "skills/qa", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "aa688402bb65f7bcf17a0f538557a88314bbc750b17bbf2139c2402d067a0618", + "files": [ + { + "path": "SKILL.md", + "sha256": "199b4d8cbea7a2b69de091e221f42b7835a3d0b3215d4d1eff53f6e9fd7f3a6c", + "bytes": 5095 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/qa/LICENSE", + "provenance_path": "skills/qa/UPSTREAM.md", + "patch_record_path": "skills/qa/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "research", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/research", + "local_package_path": "skills/research", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "669d1e6de12a0e8516dba1b7648897d559eeb508d7b2b755fc4e56bfa57aedcd", + "files": [ + { + "path": "SKILL.md", + "sha256": "0b6597c453178536b50c044a9e57cbc32dbffa47607a370e40768332f54bf8c2", + "bytes": 811 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/research/LICENSE", + "provenance_path": "skills/research/UPSTREAM.md", + "patch_record_path": "skills/research/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "tdd", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/tdd", + "local_package_path": "skills/tdd", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "c165fe21aeaaad637abe8355699ed410a94f7ebeb3dad0549dbdcacabb900198", + "files": [ + { + "path": "mocking.md", + "sha256": "73a10b6a26b56197c738a764c1e4205af98c74553f4a713795997f6bc35b917d", + "bytes": 1540 + }, + { + "path": "SKILL.md", + "sha256": "2de14b893e7a1bf7030b9eb778a3714a19da70c4284ad18a6e43b2402aa693ef", + "bytes": 3249 + }, + { + "path": "tests.md", + "sha256": "0b401f98bd3684d2fea6440d6946afcf8f5f68ac6a65599dd7a2b90dd9f02eb5", + "bytes": 2291 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/tdd/LICENSE", + "provenance_path": "skills/tdd/UPSTREAM.md", + "patch_record_path": "skills/tdd/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 3 + } + }, + { + "package_name": "teach", + "source_group": "productivity", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/productivity/teach", + "local_package_path": "skills/teach", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "7aadc88d6bc6c8fa71df8c1aba17a43e98b8e789cbe87a1beb68eda0df6e8903", + "files": [ + { + "path": "GLOSSARY-FORMAT.md", + "sha256": "408c96dce06be99b53a6e05b1e3201c900bcbb46ae3cf08ead8aa3e3cb545d8c", + "bytes": 2166 + }, + { + "path": "LEARNING-RECORD-FORMAT.md", + "sha256": "7bbbf6e325370633c77ec772cf4d30da19037ff2892c9e751f23e2696cf80888", + "bytes": 2823 + }, + { + "path": "MISSION-FORMAT.md", + "sha256": "ba1bc536615a6940414d96a1d87562f8f2684f56649d44ba15abaaf1833d0ce9", + "bytes": 1584 + }, + { + "path": "RESOURCES-FORMAT.md", + "sha256": "b5c7f17ce7c7b7f49a3a0007162e5024948c7b5c45c549643cafeb900ed431a6", + "bytes": 1958 + }, + { + "path": "SKILL.md", + "sha256": "99c077a05f66237c95392dc440974e9d144c1267309e978c7a18aaf065ce7fd3", + "bytes": 9647 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/teach/LICENSE", + "provenance_path": "skills/teach/UPSTREAM.md", + "patch_record_path": "skills/teach/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 5 + } + }, + { + "package_name": "to-spec", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/to-spec", + "local_package_path": "skills/to-spec", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "2962348d344be0a09fc8946fc08e358208b79ddcb3a309139d36f9e1bbefd584", + "files": [ + { + "path": "SKILL.md", + "sha256": "a8ffe2ecd1692f012d310dca3f3c9a75f61086df77dbb0a5bc38ddbc0bd2e6bc", + "bytes": 3148 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/to-spec/LICENSE", + "provenance_path": "skills/to-spec/UPSTREAM.md", + "patch_record_path": "skills/to-spec/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "to-tickets", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/to-tickets", + "local_package_path": "skills/to-tickets", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "e830a0046407fd2c393d2bd5d0165266de6e11feab6000742c782105d4a1c8d1", + "files": [ + { + "path": "SKILL.md", + "sha256": "573999404e46537ae441eaefe751fe85cb353b81e630bccbf9af0a2c475356b2", + "bytes": 5902 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/to-tickets/LICENSE", + "provenance_path": "skills/to-tickets/UPSTREAM.md", + "patch_record_path": "skills/to-tickets/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "ubiquitous-language", + "source_group": "deprecated", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/deprecated/ubiquitous-language", + "local_package_path": "skills/ubiquitous-language", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "18b5d153102737e71d92adb3cfeafd966a0d29bdd86934d1a11a4f213294867d", + "files": [ + { + "path": "SKILL.md", + "sha256": "a1efafd7ec7a630ed2b0753be2ddbcf53e50573e5c20a3d43e98056da25afce2", + "bytes": 4983 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/ubiquitous-language/LICENSE", + "provenance_path": "skills/ubiquitous-language/UPSTREAM.md", + "patch_record_path": "skills/ubiquitous-language/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "wayfinder", + "source_group": "engineering", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/engineering/wayfinder", + "local_package_path": "skills/wayfinder", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "4b3ba022e3f5a7617f694fef98a949b543a47bf06f471cb871ce691484df097b", + "files": [ + { + "path": "SKILL.md", + "sha256": "f6b44ce86d9d15c1848a06b6dc89e6237eaebf3c47201aa7263645690719df7a", + "bytes": 11630 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": false, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/wayfinder/LICENSE", + "provenance_path": "skills/wayfinder/UPSTREAM.md", + "patch_record_path": "skills/wayfinder/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 1 + } + }, + { + "package_name": "writing-great-skills", + "source_group": "productivity", + "upstream_repository": "mattpocock/skills", + "upstream_package_path": "skills/productivity/writing-great-skills", + "local_package_path": "skills/writing-great-skills", + "pinned_revision": "v1.1.0", + "resolved_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "checksum": "801ced90a47140b9789cf6a49b0da614e4a79b3d601b1324d6c03536a7ab97c8", + "files": [ + { + "path": "GLOSSARY.md", + "sha256": "7c8b520536aa90fdd5ceeedfbfc5e24e21df0dd480619d9f2bba38c959f3c49e", + "bytes": 18689 + }, + { + "path": "SKILL.md", + "sha256": "8c38389dbcfdb3605690c5ce2fe0fa433e7a2f2371a7f1e697d080d81d15fdea", + "bytes": 9497 + } + ], + "local_modification_state": "metadata-adapter-only", + "local_patch_paths": [ + "agents/openai.yaml", + "UPSTREAM.md", + "PATCHES.md", + "LICENSE" + ], + "upstream_snapshot": true, + "dependency_state": { + "state": "none", + "packages": [], + "writing_great_skills_is_authoring_knowledge_only": true, + "learn_anything_runtime_dependency": false + }, + "license_path": "skills/writing-great-skills/LICENSE", + "provenance_path": "skills/writing-great-skills/UPSTREAM.md", + "patch_record_path": "skills/writing-great-skills/PATCHES.md", + "referenced_resource_check": { + "missing": [], + "source_file_count": 2 + } + } + ] } diff --git a/config/upstream-allowlist.json b/config/upstream-allowlist.json new file mode 100644 index 0000000..8e930bb --- /dev/null +++ b/config/upstream-allowlist.json @@ -0,0 +1,30 @@ +{ + "upstream_repository": "https://github.com/mattpocock/skills.git", + "upstream_tag": "v1.1.0", + "upstream_commit": "d574778f94cf620fcc8ce741584093bc650a61d3", + "packages": [ + { "name": "ask-matt", "upstream_path": "skills/engineering/ask-matt", "source_group": "engineering", "dependencies": [] }, + { "name": "codebase-design", "upstream_path": "skills/engineering/codebase-design", "source_group": "engineering", "dependencies": [] }, + { "name": "code-review", "upstream_path": "skills/engineering/code-review", "source_group": "engineering", "dependencies": [] }, + { "name": "design-an-interface", "upstream_path": "skills/deprecated/design-an-interface", "source_group": "deprecated", "dependencies": [] }, + { "name": "diagnosing-bugs", "upstream_path": "skills/engineering/diagnosing-bugs", "source_group": "engineering", "dependencies": [] }, + { "name": "domain-modeling", "upstream_path": "skills/engineering/domain-modeling", "source_group": "engineering", "dependencies": [] }, + { "name": "grilling", "upstream_path": "skills/productivity/grilling", "source_group": "productivity", "dependencies": [] }, + { "name": "grill-me", "upstream_path": "skills/productivity/grill-me", "source_group": "productivity", "dependencies": ["grilling"] }, + { "name": "grill-with-docs", "upstream_path": "skills/engineering/grill-with-docs", "source_group": "engineering", "dependencies": ["grilling", "domain-modeling"] }, + { "name": "handoff", "upstream_path": "skills/productivity/handoff", "source_group": "productivity", "dependencies": [] }, + { "name": "implement", "upstream_path": "skills/engineering/implement", "source_group": "engineering", "dependencies": [] }, + { "name": "improve-codebase-architecture", "upstream_path": "skills/engineering/improve-codebase-architecture", "source_group": "engineering", "dependencies": [] }, + { "name": "loop-me", "upstream_path": "skills/in-progress/loop-me", "source_group": "in-progress", "dependencies": [] }, + { "name": "prototype", "upstream_path": "skills/engineering/prototype", "source_group": "engineering", "dependencies": [] }, + { "name": "qa", "upstream_path": "skills/deprecated/qa", "source_group": "deprecated", "dependencies": [] }, + { "name": "research", "upstream_path": "skills/engineering/research", "source_group": "engineering", "dependencies": [] }, + { "name": "tdd", "upstream_path": "skills/engineering/tdd", "source_group": "engineering", "dependencies": [] }, + { "name": "teach", "upstream_path": "skills/productivity/teach", "source_group": "productivity", "dependencies": [] }, + { "name": "to-spec", "upstream_path": "skills/engineering/to-spec", "source_group": "engineering", "dependencies": [] }, + { "name": "to-tickets", "upstream_path": "skills/engineering/to-tickets", "source_group": "engineering", "dependencies": [] }, + { "name": "ubiquitous-language", "upstream_path": "skills/deprecated/ubiquitous-language", "source_group": "deprecated", "dependencies": [] }, + { "name": "wayfinder", "upstream_path": "skills/engineering/wayfinder", "source_group": "engineering", "dependencies": [] }, + { "name": "writing-great-skills", "upstream_path": "skills/productivity/writing-great-skills", "source_group": "productivity", "dependencies": [] } + ] +} diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index c6795d8..dc98354 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,64 +1,66 @@ -# Installation - -## Current status - -This repository is the private v0.1.0 governance release. It has no admitted -source group or modified package, so it has no usable local installation command. Use the release for governance, provenance templates, and future -modified-package records; install unchanged Skills directly from upstream. - -The source catalog and empty lock inventory are authoritative: -[CATALOG.md](../CATALOG.md) and [UPSTREAM_LOCK.json](../UPSTREAM_LOCK.json). - -## Select the correct path - -| Need | Install from | Do not | -| --- | --- | --- | -| Original unchanged upstream Skill | Original upstream repository using official instructions | Use this repository as a proxy or expect a local lock entry. | -| Locally modified third-party Skill | Released source-grouped package in this repository | Substitute upstream instructions, which omit local changes. | - -An upstream Skill that works unchanged stays on the original-upstream path. -The existence of a local variant signals an intentional documented -difference, not a preference to avoid upstream. - -## Installer form - -There is no local package command while the catalog is empty. The following -shape remains documentation for a future admitted package, not an instruction -to install anything from this governance-only release: - -~~~ -npx skills add / --skill -~~~ - -The [Skills CLI documentation](https://www.skills.sh/docs/cli) describes the -general syntax. This repository does not publish an owner, repository, -revision, installer version, destination, or verified local command while its -catalog is empty. - -For an original upstream Skill, use the original repository's exact command -and record its revision and host evidence. For a locally modified package, -wait for a completed source-group record and a released immutable local -revision. - -## Manual fallback for a future local package - -When a verified installer is unavailable: - -1. Obtain the exact released local package using its documented release pin. -2. Copy the complete source-grouped package, including SKILL.md, resources, - UPSTREAM.md, PATCHES.md, and license/notices, to the host-supported Skills - location. -3. Follow the host discovery/refresh procedure. -4. Verify package identity, local pin, upstream revision, license/notices, and - documented differences. -5. Run the package's independent installation/runtime check. - -Manual copying is a fallback mechanism, not permission to copy an unchanged -upstream package here. - -## Provenance verification after local installation - -Confirm that the source/package path matches the release record; UPSTREAM.md -names original repository, path, ref, and resolved commit; PATCHES.md accounts -for local changes; license/notices are present; the matching lock entry agrees; -and installation evidence matches host and release. +# Installation and Fresh-Install Verification + +[简体中文](INSTALLATION.zh-CN.md) + +This private collection is installed from the released repository, not from a +source checkout. A consumer must have access to the private GitHub repository +through its configured Git credentials, SSH, or authenticated CLI. + +## Revision semantics + +The official Skills CLI accepts GitHub shorthand and GitHub tree URLs, and its +source parser also accepts a `#ref` fragment. Therefore these commands pin the +local collection release: + +```text +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill grill-me +``` + +The first `v0.1.1` is the local repository tag. The mirrored Matt package +content is independently pinned in `UPSTREAM_LOCK.json` to upstream +`v1.1.0` / `d574778f94cf620fcc8ce741584093bc650a61d3`. A shorthand without +`#v0.1.1` resolves the repository's default revision and is not described as +immutable. + +## Fresh installation procedure + +1. Create an empty destination project with no source checkout of this + repository present. +2. Run the whole-collection or single-package command above with the exact CLI + version recorded in the release evidence. +3. Confirm the destination contains the selected complete package(s), including + `SKILL.md`, `agents/openai.yaml`, references, scripts, templates, assets, + `LICENSE`, and provenance records. +4. Refresh or restart the Agent host and verify discovery from the destination, + not from this repository. +5. Repeat the same command and record whether the installer is idempotent. +6. Smoke-test a successful package, a stopping boundary, a missing peer + dependency, and the explicit invocation policy. + +Record command, CLI version, tag/commit, destination class, discovery result, +smoke result, and limitation in +[release evidence](evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md). + +## Manual fallback + +When the installer cannot authenticate to the private repository, manually +copy a complete released package from a checkout of tag `v0.1.1`: + +```powershell +$sourceRoot = '' +$skillName = '' +$destinationRoot = '' +Copy-Item -LiteralPath (Join-Path $sourceRoot "skills/$skillName") ` + -Destination (Join-Path $destinationRoot $skillName) -Recurse +``` + +Do not copy only `SKILL.md`. If a linked file is absent, discovery or runtime +use is not proven; mark the result `BLOCKED` or `NOT TESTED`. + +## What this repository does not claim + +- The public `skills` repository does not contain these third-party packages. +- The local release pin does not make upstream `v1.1.0` current forever. +- A source-checkout scan is not fresh-host discovery. +- A metadata file is not proof that the host actually loaded the Skill. diff --git a/docs/INSTALLATION.zh-CN.md b/docs/INSTALLATION.zh-CN.md new file mode 100644 index 0000000..59a8a31 --- /dev/null +++ b/docs/INSTALLATION.zh-CN.md @@ -0,0 +1,25 @@ +# 安装与全新环境验证 + +[English](INSTALLATION.md) + +这是 private collection，消费者必须通过 Git 凭据、SSH 或已认证 CLI 访问 +私有 GitHub 仓库。安装应来自 release，而不是 source checkout。 + +官方 CLI 支持 `#ref` 语义，因此使用： + +```text +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 +npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill grill-me +``` + +`v0.1.1` 固定本地集合；`UPSTREAM_LOCK.json` 另行固定 Matt 的 +`v1.1.0`/`d574778f94cf620fcc8ce741584093bc650a61d3`。不带 fragment 的简写 +会跟随默认 revision，不能描述为 immutable。 + +Fresh-install 必须在无 source checkout 的空目录中运行，记录 CLI 版本、命令、 +tag/commit、目标目录、完整资源、刷新后的发现结果、重复安装、成功/边界/缺失 +依赖 smoke 以及限制。结果写入 `docs/evidence/releases/`；未运行标记 +`NOT TESTED`，缺少独立 reviewer 标记 `BLOCKED`。 + +安装器不可用时，必须从 `v0.1.1` checkout 复制完整的 +`skills//`，不能只复制 `SKILL.md`。 diff --git a/docs/MAINTENANCE.md b/docs/MAINTENANCE.md index d823223..93d35df 100644 --- a/docs/MAINTENANCE.md +++ b/docs/MAINTENANCE.md @@ -1,97 +1,45 @@ # Third-Party Maintenance -## Operating rule - -Maintain each admitted package as a documented modification of a specific -immutable upstream revision. A local package must never become an anonymous -snapshot or drift without updated provenance, patch, and synchronization -records. - -The repository is governance-only today. These steps apply once a package has -passed admission. - -## Current synchronization baseline - -There are currently no source groups, modified packages, or lock entries. -CATALOG.md is the human-readable source inventory and UPSTREAM_LOCK.json -remains the authoritative empty machine-readable inventory. Direct-use -upstream Skills stay outside this repository. - -## Upstream change detection - -Each source README and package UPSTREAM.md must state: - -- upstream canonical repository and original package path; -- tracked branch, tag, release feed, or inspection point; -- owner/cadence for checks; -- last checked date; -- last synchronized ref and resolved commit; and -- relevant security, license, compatibility, or deprecation notices. - -Record the resolved commit in UPSTREAM_LOCK.json. A moving branch name alone -does not meet the revision requirement. - -## Synchronization workflow - -1. Read the source README, UPSTREAM.md, PATCHES.md, lock entry, - license/notices, release notes, and existing evidence. -2. Inspect the declared upstream reference and choose a candidate immutable - revision. -3. Re-evaluate the concrete fork reason. If upstream now satisfies it, start - removal instead of synchronization. -4. Obtain a fresh package snapshot without merging upstream Git history into - this repository. -5. Reapply or rebase documented local patches one at a time and update each - patch status. -6. Stop on conflicts or unclear behavior. Record the issue; do not silently - choose a resolution. -7. Review upstream license, notices, package structure, host compatibility, - and behavioral changes. -8. Run defined regression, independent runtime, installation, and relevant - interaction-boundary tests. -9. Update source/package records, license/notices, lock entry, installation - evidence, and release notes together. -10. Obtain required review before publishing. - -## Conflicts and regressions - -A conflict, license change, missing source, failed installation, behavior -regression, or failed independent test blocks release. Preserve the -last-known-good package and records while investigating. A static diff, -Markdown parse, or fixture cannot be reported as runtime validation. - -If the proper resolution materially changes local scope or requirements, return -to admission review rather than treating it as routine rebase work. - -## Documentation synchronization - -For an add, update, rename, deprecation, synchronization, or removal, update -or deliberately review: - -- root README; -- source catalog; -- source README; -- package UPSTREAM.md and PATCHES.md; -- license and notice files; -- UPSTREAM_LOCK.json; -- installation guidance and evidence; -- test/review evidence; and -- release notes. - -Remove stale installer commands and references in the same change. Retain -provenance and release history as required by license obligations and project -retention policy. - -## Release, removal, and rollback - -Before release, confirm matching immutable revisions across human records and -the lock entry; complete compatible license/notices; explicit local patches and -differences; verified modified-installation behavior; original-upstream -installation that is not redirected here; and independent runtime/interaction -evidence where applicable. - -If upstream eliminates the concrete fork need, prefer deprecation/removal and -direct users to upstream. For a faulty local release, preserve provenance, -identify the last known-good release, update installation guidance through the -authorized release process, and document the rollback decision. Do not erase -upstream facts or patch history. +[简体中文](MAINTENANCE.zh-CN.md) + +## Sources of truth + +| Fact | Authority | +| --- | --- | +| Selected allowlist and upstream paths | `config/upstream-allowlist.json` | +| Resolved revision, files, checksums, state, dependencies | `UPSTREAM_LOCK.json` | +| Upstream package behavior | package `SKILL.md` and its referenced resources | +| Package-local difference | package `PATCHES.md` | +| Installation proof | `docs/evidence/releases/` | +| Human catalog and release history | `CATALOG.md`, `CHANGELOG.md` | + +## Synchronization matrix + +| Change | Required checks and records | +| --- | --- | +| Upstream revision update | Review tag/commit, upstream diff, license, resources, metadata adapter, and all package checksums. | +| Package add/remove | Update allowlist, manifest, catalog, source-group record, docs, tests, changelog, and release evidence. | +| Local adapter/patch | Add a patch record, focused behavior/negative test, and independent review. | +| Installation change | Fresh whole and single-package installs, discovery outside source checkout, repeat-install result, and limitation record. | +| Release | `check`, package/resource tests, bilingual/link tests, CI, review verdict, tag/release receipt, and remote verification. | + +## Sync commands + +```powershell +.\scripts\sync-upstream.ps1 -Mode check +.\scripts\sync-upstream.ps1 -Mode dry-run +.\scripts\sync-upstream.ps1 -Mode diff +.\scripts\sync-upstream.ps1 -Mode sync +``` + +`sync` copies only the allowlisted upstream package paths, refreshes the local +metadata adapter and provenance files, and regenerates the manifest. It may +remove stale files previously recorded as upstream-managed, but only inside +the named package directory. It must never silently resolve a conflict. + +## Release discipline + +Keep the repository private. Do not publish a package as first-party. Every +release note names upstream revision, selected packages, local patch state, +dependencies, installation evidence, and limitations. A missing independent +review is `BLOCKED`; an unrun test is `NOT TESTED`. diff --git a/docs/MAINTENANCE.zh-CN.md b/docs/MAINTENANCE.zh-CN.md new file mode 100644 index 0000000..229a279 --- /dev/null +++ b/docs/MAINTENANCE.zh-CN.md @@ -0,0 +1,24 @@ +# 第三方维护 + +[English](MAINTENANCE.md) + +权威关系如下：allowlist 在 `config/upstream-allowlist.json`，revision、资源 +与 checksum 在 `UPSTREAM_LOCK.json`，行为在包内 `SKILL.md`，本地差异在 +`PATCHES.md`，安装证据在 `docs/evidence/releases/`，人类目录和变更历史在 +`CATALOG.md` / `CHANGELOG.md`。 + +同步命令： + +```powershell +.\scripts\sync-upstream.ps1 -Mode check +.\scripts\sync-upstream.ps1 -Mode dry-run +.\scripts\sync-upstream.ps1 -Mode diff +.\scripts\sync-upstream.ps1 -Mode sync +``` + +`check` 发现缺包、资源缺失、revision 漂移或未经授权的 upstream 文件修改时 +必须失败；`dry-run`、`diff` 不写文件。`sync` 只同步 allowlist，并重建 adapter、 +provenance 和 manifest；冲突不得静默解决。 + +发布前须保持 private，并记录 upstream revision、包清单、patch、依赖、安装、 +review 和 limitation。缺独立 review 是 `BLOCKED`，未运行测试是 `NOT TESTED`。 diff --git a/docs/PROVENANCE_POLICY.md b/docs/PROVENANCE_POLICY.md new file mode 100644 index 0000000..d877cd5 --- /dev/null +++ b/docs/PROVENANCE_POLICY.md @@ -0,0 +1,22 @@ +# Provenance Policy + +[简体中文](PROVENANCE_POLICY.zh-CN.md) + +Every third-party package must make it possible to answer: where did this file +come from, which immutable upstream revision was used, what changed locally, +and how can it be updated or removed? + +`UPSTREAM_LOCK.json` is the machine-readable answer. Each entry stores the +source repository, original path, selected tag, resolved commit, per-file +SHA-256 inventory, package checksum, license path, dependency state, and local +modification state. `UPSTREAM.md` is the human-readable explanation; +`PATCHES.md` is the local difference ledger. + +The current mirror uses `metadata-adapter-only`: upstream package files are +hash-checked and unchanged, while `agents/openai.yaml` provides collection +metadata because the selected upstream package does not ship it. This adapter +must not be described as upstream behavior or first-party authorship. + +License files are copied into every package for self-contained installation. +The upstream MIT license remains authoritative. Do not remove, rewrite, or +replace it without a recorded license review. diff --git a/docs/PROVENANCE_POLICY.zh-CN.md b/docs/PROVENANCE_POLICY.zh-CN.md new file mode 100644 index 0000000..17195ee --- /dev/null +++ b/docs/PROVENANCE_POLICY.zh-CN.md @@ -0,0 +1,14 @@ +# Provenance 政策 + +[English](PROVENANCE_POLICY.md) + +每个第三方包都必须回答：文件来自哪里、使用哪个不可变 upstream revision、 +本地改了什么、如何更新或移除。 + +`UPSTREAM_LOCK.json` 保存 repository、原始 path、tag、commit、逐文件 SHA-256、 +包 checksum、license、依赖和本地修改状态；`UPSTREAM.md` 是解释记录， +`PATCHES.md` 是差异台账。 + +当前集合使用 `metadata-adapter-only`：upstream 文件保持 hash 一致， +`agents/openai.yaml` 仅补充主机 discovery 所需的 metadata，不代表 upstream +行为或第一方 authorship。每个包携带 MIT `LICENSE`，不得静默删除或改写。 diff --git a/docs/REVIEW_POLICY.md b/docs/REVIEW_POLICY.md new file mode 100644 index 0000000..b1ea8a3 --- /dev/null +++ b/docs/REVIEW_POLICY.md @@ -0,0 +1,30 @@ +# Third-Party Review Policy + +[简体中文](REVIEW_POLICY.zh-CN.md) + +Third-party review checks provenance and boundaries as well as behavior. + +## Required review axes + +- Standards: package shape, resource containment, metadata, license retention, + source grouping, link integrity, and maintainability. +- Spec: exact allowlist, pinned revision, local modification classification, + dependency declarations, installation semantics, and private boundary. + +The final verdict is owned by `review-loop`: `PASS`, `FAIL`, or `BLOCKED`. +`sync-upstream.ps1`, package tests, and specialist `code-review` findings are +evidence only. A structural scan cannot substitute for fresh installation or +an independent evaluator. + +## Release gate + +No tag or release may claim package readiness until the clean worktree has: + +- a passing sync check and complete-resource assertion; +- a passing allowlist, manifest, checksum, license, and dependency test; +- a failing negative fixture for unauthorized local changes; +- fresh whole-collection and single-package installation evidence; +- discovery without the source checkout and repeat-install results; and +- an independent review record with no unresolved P1/P2 finding. + +Unrun evidence is `NOT TESTED`; missing independent review is `BLOCKED`. diff --git a/docs/REVIEW_POLICY.zh-CN.md b/docs/REVIEW_POLICY.zh-CN.md new file mode 100644 index 0000000..1348697 --- /dev/null +++ b/docs/REVIEW_POLICY.zh-CN.md @@ -0,0 +1,13 @@ +# 第三方 Review 政策 + +[English](REVIEW_POLICY.md) + +Review 同时检查 Standards 与 Spec：包结构、资源 containment、metadata、license、 +source grouping、链接、allowlist、revision、修改状态、依赖、安装语义和 private +边界。 + +最终 verdict 由 `review-loop` 持有：`PASS`、`FAIL` 或 `BLOCKED`。同步脚本、测试和 +`code-review` 只是证据。发布前必须有完整资源与 checksum 检查、负向未授权修改 +fixture、fresh whole/per-Skill install、脱离 source checkout 的 discovery、重复安装 +结果和无未解决 P1/P2 的独立 review。未运行标记 `NOT TESTED`，缺独立 review 标记 +`BLOCKED`。 diff --git a/docs/THIRD_PARTY_ADMISSION.md b/docs/THIRD_PARTY_ADMISSION.md index 416a61c..5b8d375 100644 --- a/docs/THIRD_PARTY_ADMISSION.md +++ b/docs/THIRD_PARTY_ADMISSION.md @@ -1,113 +1,57 @@ -# Third-Party Skill Admission - -## Policy - -A package may enter only as a source-grouped, locally modified third-party -Skill. The proposer must first show that direct use of original upstream is -insufficient for a concrete, reproducible reason. - -Do not accept unmodified copies for convenience, discovery, backup, -centralization, or a preference for one catalog. Passing admission does not -transfer ownership: upstream attribution and licensing remain visible. - -## Direct-upstream gate - -Record one permitted category and concrete evidence: - -| Category | Required evidence | -| --- | --- | -| Compatibility fix | Host/version, observed failure, and why direct upstream cannot work. | -| Additional Agent-host support | Required host behavior, upstream gap, and bounded adaptation. | -| Stable pinned behavior | Required behavior, upstream drift/unavailability, immutable revision, and why upstream cannot provide it. | -| Package repair or repackaging | Broken/incompatible upstream structure and the smallest repair. | -| Behavioral variation | Intentional difference, user value, compatibility cost, and why a wrapper/configuration is insufficient. | - -Reject a proposal based only on convenience, unchanged mirroring, -discoverability, generic future-proofing, or unsubstantiated preference. - -Consider this order before a fork: - -1. use upstream directly; -2. configure or adapt at the boundary; -3. add a local Profile or Layer; -4. create a wrapper only when necessary; then -5. create a local modified variant only when a permitted category remains. - -## Provenance and license gate - -Record all of the following: - -- source identifier and source-group directory; -- upstream owner, repository, canonical URL, and original package path; -- selected upstream tag/ref and immutable resolved commit SHA; -- required upstream author attribution; -- applicable license identifier, license text location, and notices; -- compatibility of that license with planned local distribution; and -- snapshot date and method. - -A missing or incompatible license blocks admission. Carry required license text -and notices with the modified package unless the license requires another -equally visible documented location. - -## Bounded-change gate - -Define the smallest local change set before import: - -- rationale for every local change; -- affected files or package elements; -- behavior preserved from upstream; -- intentional behavior changes and compatibility effects; -- known differences and limitations; -- rollback/removal path; and -- independent runtime and relevant interaction-boundary tests. - -Reject a fork when a Profile, Layer, configuration, boundary adaptation, or -wrapper solves the actual need. - -## Required records - -Before release, complete: - -| Record | Required content | -| --- | --- | -| source README | Source identity, grouped packages, source-wide attribution/licensing, original-upstream versus local-modified installation, synchronization, and release status. | -| package UPSTREAM.md | Original identity/path, immutable revision, license, fork rationale, upstream and local installation, synchronization, and differences. | -| package PATCHES.md | Every local change, rationale, revision, reapplication status, conflict decision, and regression evidence. | -| package license/notices | Applicable license text and notices. | -| UPSTREAM_LOCK.json entry | Source/package identity, immutable revision, license, record paths, sync date, and modified installation reference. | - -Use [templates/UPSTREAM.md](../templates/UPSTREAM.md), -[templates/PATCHES.md](../templates/PATCHES.md), and -[templates/SOURCE_README.md](../templates/SOURCE_README.md). The completed -source and package records are the human-readable provenance authority; the -lock file is the repository-wide inventory. - -## Synchronization and installation gate - -Define upstream change detection, owner/cadence, patch reapplication/rebase, -conflict escalation, post-sync regression and interaction tests, original -upstream installation source, local modified installation source/release pin, -manual fallback, and post-install verification. - -Installer syntax is not evidence. Publish a command only after testing the -actual released package and source group on the intended host. - -## Decision and pre-release checklist - -Independent review must confirm concrete direct-upstream insufficiency, -complete provenance/license/revision, bounded changes, complete records, -feasible synchronization/removal, independent local runtime evidence, and -relevant interaction-boundary evidence. It returns PASS, FAIL, or BLOCKED. - -- [ ] Direct upstream installation was evaluated. -- [ ] Permitted fork category and concrete evidence are recorded. -- [ ] Boundary, Profile/Layer, and wrapper alternatives were considered. -- [ ] Source, path, URL, tag/ref, and resolved commit are recorded. -- [ ] License compatibility, text, and notices are identified. -- [ ] Local changes, known differences, and behavioral effects are recorded. -- [ ] Source README, package records, license/notices, and lock entry exist. -- [ ] Synchronization, conflict, regression, installation, and removal plans - are defined. -- [ ] Original-upstream and local-modified installation paths are distinct. -- [ ] Independent runtime and relevant interaction evidence is recorded before - release. +# Third-Party Admission Policy + +[简体中文](THIRD_PARTY_ADMISSION.zh-CN.md) + +This policy governs what may enter the private third-party collection. It is +deliberately different from the public first-party ownership policy, while +still requiring provenance and evidence. + +## Allowed source states + +Every entry must be exactly one of: + +- **Pinned upstream mirror:** a complete package snapshot at a selected tag/ref + and full resolved commit. A small collection metadata adapter is allowed and + must be listed as a local patch. No upstream behavior may be silently edited. +- **Modified upstream fork:** a package with a concrete compatibility, + repackaging, stable-pin, host-support, or behavior-variation reason that + direct upstream installation cannot meet. The patch and difference must be + reviewed. +- **External direct dependency:** a package deliberately not copied. Record its + authoritative source, revision, and installation guidance instead. + +Convenience, backup, centralization, or an untested preference is not a fork +reason. A pinned mirror is allowed only when the owner explicitly requests the +auditable snapshot or when a reproducible collection boundary is required; it +must not be misrepresented as first-party authorship. + +## Required admission record + +Before release, each package and source group must identify: + +1. upstream repository, URL, original package path, author, and license/notice; +2. selected tag/ref and full resolved commit; +3. source group and local install path; +4. snapshot, adapter, patch, or external-dependency state; +5. complete upstream file inventory and checksum; +6. every local patch and why it exists; +7. declared peer dependencies and whether they are installed or external; +8. installation method, host, discovery result, and known limitations; and +9. update method, conflict owner, and evidence links. + +The 23-package Matt snapshot is admitted by the user-provided T19 scope. Its +allowlist is intentionally closed; `UPSTREAM_LOCK.json` must contain exactly +the names in `config/upstream-allowlist.json`. + +## Boundary rules + +- Do not add these packages to the public first-party `skills` repository. +- Preserve upstream `SKILL.md`, scripts, references, assets, templates, and + other resources; a package is not complete if its referenced resources are + missing. +- Keep `grill-me` → `grilling` and `grill-with-docs` → `grilling` + + `domain-modeling` as declared peer dependencies. +- Keep `ask-matt` as a navigation-only router. +- Treat `writing-great-skills` as authoring knowledge, not a hidden runtime + dependency of `learn-anything`. +- A structural scan is not fresh-install, runtime, or review evidence. diff --git a/docs/THIRD_PARTY_ADMISSION.zh-CN.md b/docs/THIRD_PARTY_ADMISSION.zh-CN.md new file mode 100644 index 0000000..fdb0e3b --- /dev/null +++ b/docs/THIRD_PARTY_ADMISSION.zh-CN.md @@ -0,0 +1,29 @@ +# 第三方准入政策 + +[English](THIRD_PARTY_ADMISSION.md) + +本政策规定哪些内容可以进入私有第三方集合。它不同于公开第一方仓库的 +ownership gate，但同样要求 provenance 与证据。 + +## 允许的来源状态 + +- **Pinned upstream mirror：** 在选定 tag/ref 和完整 commit 上保存完整包； + 主机 metadata adapter 可以存在，但必须标记为本地 patch，不能改写 upstream + 行为。 +- **Modified upstream fork：** 只有兼容性、重打包、稳定 pin、主机支持或 + 行为差异等具体原因，且直接 upstream 不足时才允许；差异必须可审查。 +- **External direct dependency：** 有意不复制，只记录权威来源、revision 和 + 安装方法。 + +便利、备份、集中管理或未经验证的偏好都不是 fork 理由。allowlist 是封闭的， +不得静默追加 Skill。 + +## 必备记录与边界 + +每个包必须记录仓库、URL、原始 path、tag/ref、完整 commit、license、逐文件 +checksum、本地修改状态、依赖、安装结果、更新方式和证据。`grill-me` 与 +`grill-with-docs` 的依赖必须保留；`ask-matt` 只能导航； +`writing-great-skills` 不能成为 `learn-anything` 的隐式运行时依赖。 + +不得把这些包放入公开第一方 `skills` 仓库。缺少实际引用资源时，包不算完整； +结构扫描也不能替代 fresh install、runtime 或独立 review。 diff --git a/docs/UPDATE_POLICY.md b/docs/UPDATE_POLICY.md new file mode 100644 index 0000000..607293f --- /dev/null +++ b/docs/UPDATE_POLICY.md @@ -0,0 +1,20 @@ +# Upstream Update Policy + +[简体中文](UPDATE_POLICY.zh-CN.md) + +Updates are explicit, pinned, and reviewable: + +1. fetch or inspect the proposed upstream tag/ref in a read-only checkout; +2. resolve it to a full commit and update the allowlist only if the package set + remains authorized; +3. run `sync-upstream.ps1 -Mode dry-run` and `-Mode diff`; +4. review removals, additions, references, licenses, metadata, and dependency + changes; +5. run `-Mode sync`, then `-Mode check` and the negative unauthorized-patch + fixture; +6. refresh catalog, bilingual docs, changelog, evidence, and CI; and +7. obtain independent review before tagging a release. + +If an upstream file changes locally without a patch record, `check` must fail. +If a peer dependency is missing, record it as an external dependency and do +not silently add a package outside the allowlist. diff --git a/docs/UPDATE_POLICY.zh-CN.md b/docs/UPDATE_POLICY.zh-CN.md new file mode 100644 index 0000000..660d275 --- /dev/null +++ b/docs/UPDATE_POLICY.zh-CN.md @@ -0,0 +1,11 @@ +# Upstream 更新政策 + +[English](UPDATE_POLICY.md) + +更新必须显式、固定、可审计：先在只读 checkout 中检查 tag/ref 并解析完整 +commit，再运行 `dry-run` 和 `diff`，审查资源、license、metadata、依赖和 +删除；随后才可 `sync`，运行 `check`、负向 unauthorized patch fixture、文档与 +安装测试，并取得独立 review。 + +若 upstream 文件发生本地变更而没有 patch record，`check` 必须失败。缺少 peer +dependency 时记录为 external dependency，不能静默扩大 allowlist。 diff --git a/docs/evidence/releases/v0.1.1/DISCOVERY_VERIFICATION.md b/docs/evidence/releases/v0.1.1/DISCOVERY_VERIFICATION.md new file mode 100644 index 0000000..06334ff --- /dev/null +++ b/docs/evidence/releases/v0.1.1/DISCOVERY_VERIFICATION.md @@ -0,0 +1,16 @@ +# v0.1.1 Discovery Verification + +Status: `NOT TESTED` until discovery is observed outside the source checkout. + +## Required record + +- Host and version: `NOT RECORDED` +- Fresh destination: `NOT RECORDED` +- Whole collection discovered: `NOT TESTED` +- Single `grill-me` discovered: `NOT TESTED` +- Metadata policy observed: `NOT TESTED` +- Peer dependency boundary observed: `NOT TESTED` +- Source checkout excluded from search path: `NOT TESTED` + +The manifest and structural tests prove package completeness only; they do not +prove that a particular Agent host loaded the installed package. diff --git a/docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md b/docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md new file mode 100644 index 0000000..3219852 --- /dev/null +++ b/docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md @@ -0,0 +1,14 @@ +# v0.1.1 Installation Verification + +Status: `NOT TESTED` until a private-repository fresh-destination run succeeds. + +## Required record + +- CLI version: `NOT RECORDED` +- Whole-collection command: `npx skills add LightDevCoder/skills-3rdParty#v0.1.1` +- Single-package command: `npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill grill-me` +- Tag/commit: `NOT RECORDED` +- Destination: `NOT RECORDED` (must not be a source checkout) +- Complete resources: `NOT TESTED` +- Repeated installation behavior: `NOT TESTED` +- Limitation: private-repository authentication and host discovery must be recorded from the actual environment. diff --git a/docs/evidence/releases/v0.1.1/LIMITATIONS.md b/docs/evidence/releases/v0.1.1/LIMITATIONS.md new file mode 100644 index 0000000..6f87e0e --- /dev/null +++ b/docs/evidence/releases/v0.1.1/LIMITATIONS.md @@ -0,0 +1,13 @@ +# v0.1.1 Limitations + +- The collection is private; consumers need repository access credentials. +- The Skills CLI `#ref` pin was confirmed from official source semantics, but a + fresh private-repository install must still be recorded for this release. +- `agents/openai.yaml` is a local metadata adapter because the selected upstream + packages do not provide it; it does not prove host-specific loading. +- Upstream `wayfinder` includes an example Markdown `link` placeholder; it is + preserved as upstream content and is not treated as a local resource. +- Other Agent hosts, global scopes, and host-specific refresh behavior remain + `NOT TESTED` until evidence is captured. +- Independent final review remains `BLOCKED` until a fresh reviewer record is + supplied. diff --git a/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md new file mode 100644 index 0000000..bcf94cb --- /dev/null +++ b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md @@ -0,0 +1,31 @@ +# skills-3rdParty v0.1.1 Release Receipt + +[中文记录](RELEASE_RECEIPT.zh-CN.md) + +Status: `IN PROGRESS` — this record must be updated from actual commands before +the tag or GitHub release is created. + +## Identity + +- Repository: `LightDevCoder/skills-3rdParty` (private) +- Local baseline: `b038ab039b86c66119c392002448ae0d5ef837c4` +- Upstream: `mattpocock/skills` tag `v1.1.0`, commit + `d574778f94cf620fcc8ce741584093bc650a61d3` +- Selected packages: exactly 23; see [UPSTREAM_LOCK.json](../../../../UPSTREAM_LOCK.json) +- Local state: pinned upstream snapshot plus metadata-adapter-only patch +- Intended local tag: `v0.1.1` + +## Evidence links + +- [test summary](TEST_SUMMARY.md) +- [installation verification](INSTALLATION_VERIFICATION.md) +- [discovery verification](DISCOVERY_VERIFICATION.md) +- [limitations](LIMITATIONS.md) +- [first-party collection evidence](https://github.com/LightDevCoder/skills/blob/main/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md) — the two repositories retain separate evidence + +## Release decision + +- Independent reviewer: `BLOCKED` until a fresh read-only review is recorded. +- Tag/release: `NOT TESTED`. +- Private visibility: must remain `private`; any visibility change is out of scope. +- Do not describe this receipt as `PASS` until all required evidence is real. diff --git a/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md new file mode 100644 index 0000000..85aaae8 --- /dev/null +++ b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md @@ -0,0 +1,16 @@ +# skills-3rdParty v0.1.1 发布记录 + +[English](RELEASE_RECEIPT.md) + +状态：`IN PROGRESS`。创建 tag 或 GitHub release 前，必须用真实命令更新本记录。 + +- 仓库：`LightDevCoder/skills-3rdParty`，保持 private +- upstream：`mattpocock/skills` `v1.1.0`，commit + `d574778f94cf620fcc8ce741584093bc650a61d3` +- 收录：严格 23 个指定 Skill +- 本地状态：pinned upstream snapshot + metadata-adapter-only +- 目标 tag：`v0.1.1` + +测试、安装、发现和限制见同目录英文记录。当前 independent reviewer 为 +`BLOCKED`，tag/release 为 `NOT TESTED`；结构检查不能代替 fresh install 或独立 +review。任何可见性变更均不在本次范围内。 diff --git a/docs/evidence/releases/v0.1.1/TEST_SUMMARY.md b/docs/evidence/releases/v0.1.1/TEST_SUMMARY.md new file mode 100644 index 0000000..32229f0 --- /dev/null +++ b/docs/evidence/releases/v0.1.1/TEST_SUMMARY.md @@ -0,0 +1,20 @@ +# v0.1.1 Test Summary + +All rows must contain the actual command, environment, assertion count, and +result. A structural test is not runtime proof. + +| Area | Command / environment | Assertions | Result | +| --- | --- | ---: | --- | +| Pinned sync check | `scripts/sync-upstream.ps1 -Mode check` | NOT RECORDED | NOT TESTED | +| Sync dry-run | `scripts/sync-upstream.ps1 -Mode dry-run` | NOT RECORDED | NOT TESTED | +| Whole package contract | `tests/third-party-collection-tests.ps1` | NOT RECORDED | NOT TESTED | +| Unauthorized local patch negative fixture | included in collection test | NOT RECORDED | NOT TESTED | +| Whole-repository fresh install | Skills CLI, fresh destination | NOT RECORDED | NOT TESTED | +| Single-package fresh install | Skills CLI, fresh destination | NOT RECORDED | NOT TESTED | +| Representative dependency smoke | `grill-me`, `grill-with-docs` | NOT RECORDED | NOT TESTED | +| Private release verification | GitHub release API / remote | NOT RECORDED | NOT TESTED | + +## Non-claims + +No row may be promoted from `NOT TESTED` by copying a source-checkout scan or a +simulated output. diff --git a/scripts/sync-upstream.ps1 b/scripts/sync-upstream.ps1 new file mode 100644 index 0000000..115b111 --- /dev/null +++ b/scripts/sync-upstream.ps1 @@ -0,0 +1,425 @@ +[CmdletBinding()] +param( + [ValidateSet('check', 'dry-run', 'sync', 'diff')] + [string]$Mode = 'check', + [string]$Root = (Split-Path -Parent $PSScriptRoot), + [string]$UpstreamRoot = '' +) + +$ErrorActionPreference = 'Stop' +$Root = (Resolve-Path -LiteralPath $Root).Path +if ([string]::IsNullOrWhiteSpace($UpstreamRoot)) { + $UpstreamRoot = Join-Path $Root '..\..\sources\mattpocock-skills' +} +$UpstreamRoot = (Resolve-Path -LiteralPath $UpstreamRoot).Path +$allowlistPath = Join-Path $Root 'config/upstream-allowlist.json' +$manifestPath = Join-Path $Root 'UPSTREAM_LOCK.json' +$skillRoot = Join-Path $Root 'skills' + +function Write-Utf8 { + param([string]$Path, [string]$Text) + $parent = Split-Path -Parent $Path + if (-not (Test-Path -LiteralPath $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null } + [IO.File]::WriteAllText($Path, $Text, [Text.UTF8Encoding]::new($false)) +} + +function Read-JsonFile { + param([string]$Path) + if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) { throw "JSON file is missing: $Path" } + return Get-Content -Raw -LiteralPath $Path | ConvertFrom-Json +} + +function Get-FullPath { + param([string]$Path) + return [IO.Path]::GetFullPath($Path).TrimEnd('\') +} + +function Test-Contained { + param([string]$Path, [string]$Parent) + $child = Get-FullPath $Path + $root = Get-FullPath $Parent + return $child.Equals($root, [StringComparison]::OrdinalIgnoreCase) -or + $child.StartsWith($root + '\', [StringComparison]::OrdinalIgnoreCase) +} + +function Get-RelativeFiles { + param([string]$Path) + if (-not (Test-Path -LiteralPath $Path -PathType Container)) { return @() } + $base = (Resolve-Path -LiteralPath $Path).Path.TrimEnd('\') + return @(Get-ChildItem -LiteralPath $base -Recurse -File -Force | + ForEach-Object { $_.FullName.Substring($base.Length + 1).Replace('\', '/') } | + Sort-Object) +} + +function Get-Sha256 { + param([string]$Path) + return (Get-FileHash -Algorithm SHA256 -LiteralPath $Path).Hash.ToLowerInvariant() +} + +function Invoke-UpstreamGit { + param([string[]]$Arguments) + $safe = "safe.directory=$UpstreamRoot" + $output = & git -c $safe -C $UpstreamRoot @Arguments 2>&1 + if ($LASTEXITCODE -ne 0) { throw "git failed in upstream checkout: $($output -join "`n")" } + return (($output -join "`n").Trim()) +} + +function Get-UpstreamCommit { + param([string]$Revision) + return Invoke-UpstreamGit @('rev-parse', "$Revision^{commit}") +} + +function Get-ManifestEntries { + if (-not (Test-Path -LiteralPath $manifestPath -PathType Leaf)) { return @() } + $manifest = Read-JsonFile $manifestPath + return @($manifest.entries) +} + +function Get-Frontmatter { + param([string]$Path) + $text = Get-Content -Raw -LiteralPath $Path + $match = [regex]::Match($text, '(?ms)^---\r?\n(?.*?)\r?\n---') + if (-not $match.Success) { throw "SKILL.md has no complete frontmatter: $Path" } + $body = $match.Groups['body'].Value + $nameMatch = [regex]::Match($body, '(?m)^name:\s*(?.+?)\s*$') + $descriptionMatch = [regex]::Match($body, '(?m)^description:\s*(?.+?)\s*$') + if (-not $nameMatch.Success -or -not $descriptionMatch.Success) { throw "SKILL.md frontmatter is incomplete: $Path" } + $name = $nameMatch.Groups['value'].Value.Trim().Trim('"').Trim("'") + $description = $descriptionMatch.Groups['value'].Value.Trim().Trim('"').Trim("'") + [pscustomobject]@{ + name = $name + description = $description + allowImplicitInvocation = -not ($body -match '(?m)^disable-model-invocation:\s*true\s*$') + } +} + +function Get-LocalAllowedPaths { + return @('agents/openai.yaml', 'UPSTREAM.md', 'PATCHES.md', 'LICENSE') +} + +function Get-ReferencedResources { + param([string]$PackagePath) + $body = Get-Content -Raw -LiteralPath (Join-Path $PackagePath 'SKILL.md') + $links = [regex]::Matches($body, '\]\(([^)]+)\)') | + ForEach-Object { $_.Groups[1].Value.Split('#')[0].Split('?')[0] } | + Where-Object { $_ -and $_ -notmatch '^(https?|mailto):' -and $_ -notmatch '^/' -and $_ -notmatch '^<.*>$' -and $_ -notmatch '^(link|path|url)$' } | + Select-Object -Unique + $missing = [System.Collections.Generic.List[string]]::new() + foreach ($link in $links) { + $candidate = Join-Path $PackagePath $link + if (-not (Test-Contained $candidate $PackagePath) -or -not (Test-Path -LiteralPath $candidate -PathType Leaf)) { + $missing.Add($link) + } + } + return @($missing) +} + +function New-AgentMetadata { + param($Package, [string]$Destination) + $front = Get-Frontmatter (Join-Path $Destination 'SKILL.md') + $title = [Globalization.CultureInfo]::InvariantCulture.TextInfo.ToTitleCase(($Package.name -replace '-', ' ')) + $short = $front.description.Replace('"', '\"') + $prompt = ('Use $' + $Package.name + ' when this task matches its upstream contract; preserve its explicit stopping boundary.') + $metadata = @( + 'interface:', + (' display_name: "' + $title + '"'), + (' short_description: "' + $short + '"'), + (' default_prompt: "' + $prompt.Replace('"', '\"') + '"'), + '', + 'policy:', + (' allow_implicit_invocation: ' + ($(if ($front.allowImplicitInvocation) { 'true' } else { 'false' }))) + ) -join "`n" + Write-Utf8 (Join-Path $Destination 'agents/openai.yaml') ($metadata + "`n") +} + +function New-ProvenanceFiles { + param($Package, [string]$Destination, [string]$Revision, [string]$Commit) + $front = Get-Frontmatter (Join-Path $Destination 'SKILL.md') + $deps = if (@($Package.dependencies).Count -gt 0) { (@($Package.dependencies) -join ', ') } else { 'none' } + $upstream = @( + "# Upstream Record: $($Package.name)", + '', + 'This package is a pinned upstream snapshot with a local host-metadata adapter.', + 'The upstream Skill instructions and referenced resources are preserved.', + '', + '## Identity', + '', + "- **Source group:** $($Package.source_group)", + "- **Package:** $($Package.name)", + '- **Upstream repository:** `mattpocock/skills`', + '- **Canonical URL:** https://github.com/mattpocock/skills', + "- **Original package path:** $($Package.upstream_path)", + "- **Selected upstream tag:** $Revision", + "- **Resolved commit:** $Commit", + '- **Applicable license:** MIT; see `LICENSE` in this package.', + '- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license.', + '', + '## Local packaging state', + '', + '- **State:** pinned upstream snapshot with metadata-adapter-only local change.', + '- **Local patch:** `agents/openai.yaml` supplies the host metadata required by', + ' this collection''s discovery checks; it does not alter `SKILL.md` behavior or', + ' upstream resources.', + '- **Why the adapter exists:** the upstream package does not ship this', + ' collection-specific `agents/openai.yaml`; omitting it makes metadata-aware', + ' discovery unable to report invocation policy reliably.', + "- **Dependencies:** $deps. These are declared peer Skills, not hidden runtime", + ' imports. Install them separately when a workflow explicitly needs them.', + '- **Navigation boundary:** `ask-matt` remains a router and does not execute or', + ' install the Skills it mentions.', + '', + '## Installation and update', + '', + "- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#$($Revision)", + "- **Single package:** npx skills add LightDevCoder/skills-3rdParty#$($Revision) --skill $($Package.name)", + "- **Manual fallback:** copy this complete skills/$($Package.name)/ directory", + " into the host's recognized Skills root.", + '- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the', + ' pinned checkout; review upstream diff, then use `-Mode sync` only after the', + ' allowlist and revision are approved.', + '', + '## Differences and evidence', + '', + '- **Upstream behavior preserved:** yes, for the upstream package files listed', + ' in `UPSTREAM_LOCK.json`.', + '- **Local difference:** metadata adapter and this provenance record only.', + '- **Known limitations:** host-specific discovery and private-repository access', + ' remain dependent on the installer and credentials used by the consumer.', + '- **Patch record:** `PATCHES.md`', + "- **Lock entry:** UPSTREAM_LOCK.json entry $($Package.name)" + ) -join "`n" + $patches = @( + "# Local Patch Record: $($Package.name)", + '', + "- **Upstream revision:** $Revision ($Commit)", + '- **Local state:** metadata-adapter-only; no upstream behavior patch.', + '- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE`', + '', + '## P0001 — Collection host metadata adapter', + '', + '- **Status:** active', + '- **Local file:** `agents/openai.yaml`', + '- **Rationale:** make display name, description, default prompt, and explicit', + ' invocation policy available to metadata-aware hosts and `ask-light`.', + '- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets,', + ' and templates are copied without modification.', + '- **Compatibility impact:** none to the upstream Skill contract; the adapter', + ' is ignored by hosts that do not consume it.', + '- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the', + ' release evidence under `docs/evidence/releases/`.', + '', + '## Patch-set review', + '', + '- All upstream file differences are hash-checked by `sync-upstream.ps1`.', + '- Any change to an upstream-managed file fails `-Mode check` until explicitly', + ' reviewed and represented by a new patch record.' + ) -join "`n" + Write-Utf8 (Join-Path $Destination 'UPSTREAM.md') ($upstream.Trim() + "`n") + Write-Utf8 (Join-Path $Destination 'PATCHES.md') ($patches.Trim() + "`n") + Copy-Item -LiteralPath (Join-Path $UpstreamRoot 'LICENSE') -Destination (Join-Path $Destination 'LICENSE') -Force +} + +function Get-FileRecords { + param([string]$Destination, [string[]]$UpstreamFiles) + return @($UpstreamFiles | ForEach-Object { + $filePath = Join-Path $Destination $_ + [ordered]@{ path = $_; sha256 = Get-Sha256 $filePath; bytes = (Get-Item -LiteralPath $filePath).Length } + }) +} + +function Get-EntryChecksum { + param($Files) + $serialized = (@($Files | ForEach-Object { "$($_.path):$($_.sha256)" }) -join "`n") + $bytes = [Text.UTF8Encoding]::new($false).GetBytes($serialized) + $sha = [Security.Cryptography.SHA256]::Create() + try { return ([BitConverter]::ToString($sha.ComputeHash($bytes))).Replace('-', '').ToLowerInvariant() } + finally { $sha.Dispose() } +} + +function Sync-OnePackage { + param($Package, [string]$Revision, [string]$Commit) + $source = Join-Path $UpstreamRoot $Package.upstream_path + $destination = Join-Path $skillRoot $Package.name + if (-not (Test-Contained $source $UpstreamRoot)) { throw "Unsafe upstream path: $($Package.upstream_path)" } + if (-not (Test-Path -LiteralPath $source -PathType Container)) { throw "Upstream package is missing: $($Package.upstream_path)" } + $sourceFiles = Get-RelativeFiles $source + if (-not ($sourceFiles -contains 'SKILL.md')) { throw "Upstream package lacks SKILL.md: $($Package.name)" } + $oldEntry = @(Get-ManifestEntries | Where-Object name -eq $Package.name | Select-Object -First 1) + if ((Test-Path -LiteralPath $destination -PathType Container) -and $oldEntry.Count -gt 0) { + $oldFiles = @($oldEntry[0].files | ForEach-Object path) + foreach ($old in $oldFiles | Where-Object { $sourceFiles -notcontains $_ -and (Get-LocalAllowedPaths) -notcontains $_ }) { + $stale = Join-Path $destination $old + if ((Test-Contained $stale $destination) -and (Test-Path -LiteralPath $stale -PathType Leaf)) { Remove-Item -LiteralPath $stale -Force } + } + } + New-Item -ItemType Directory -Path $destination -Force | Out-Null + foreach ($relative in $sourceFiles) { + $from = Join-Path $source $relative + $to = Join-Path $destination $relative + if (-not (Test-Contained $to $destination)) { throw "Unsafe destination path: $relative" } + $parent = Split-Path -Parent $to + if (-not (Test-Path -LiteralPath $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null } + Copy-Item -LiteralPath $from -Destination $to -Force + } + New-AgentMetadata $Package $destination + New-ProvenanceFiles $Package $destination $Revision $Commit + $missing = Get-ReferencedResources $destination + if ($missing.Count -gt 0) { throw "$($Package.name) has missing referenced resources: $($missing -join ', ')" } + [pscustomobject]@{ name = $Package.name; files = $sourceFiles.Count; destination = $destination } +} + +function Build-Manifest { + param($Config, [string]$Revision, [string]$Commit) + $entries = [System.Collections.Generic.List[object]]::new() + foreach ($package in @($Config.packages)) { + $destination = Join-Path $skillRoot $package.name + $source = Join-Path $UpstreamRoot $package.upstream_path + $sourceFiles = Get-RelativeFiles $source + $files = Get-FileRecords $destination $sourceFiles + $entry = [ordered]@{ + package_name = $package.name + source_group = $package.source_group + upstream_repository = 'mattpocock/skills' + upstream_package_path = $package.upstream_path + local_package_path = ('skills/' + $package.name) + pinned_revision = $Revision + resolved_commit = $Commit + checksum = Get-EntryChecksum $files + files = @($files) + local_modification_state = 'metadata-adapter-only' + local_patch_paths = @('agents/openai.yaml', 'UPSTREAM.md', 'PATCHES.md', 'LICENSE') + upstream_snapshot = $true + dependency_state = [ordered]@{ + state = if (@($package.dependencies).Count -gt 0) { 'declared-peer-dependency' } else { 'none' } + packages = @($package.dependencies) + writing_great_skills_is_authoring_knowledge_only = ($package.name -eq 'writing-great-skills') + learn_anything_runtime_dependency = $false + } + license_path = ('skills/' + $package.name + '/LICENSE') + provenance_path = ('skills/' + $package.name + '/UPSTREAM.md') + patch_record_path = ('skills/' + $package.name + '/PATCHES.md') + referenced_resource_check = [ordered]@{ missing = @(Get-ReferencedResources $destination); source_file_count = $sourceFiles.Count } + } + $entries.Add($entry) + } + $collectionData = (@($entries | ForEach-Object { "$($_.package_name):$($_.checksum)" }) -join "`n") + $collectionBytes = [Text.UTF8Encoding]::new($false).GetBytes($collectionData) + $collectionSha = [Security.Cryptography.SHA256]::Create() + try { $collectionChecksum = ([BitConverter]::ToString($collectionSha.ComputeHash($collectionBytes))).Replace('-', '').ToLowerInvariant() } + finally { $collectionSha.Dispose() } + $manifest = [ordered]@{ + schema_version = 2 + repository = 'LightDevCoder/skills-3rdParty' + visibility = 'private' + source_kind = 'pinned-upstream-mirror-with-collection-metadata-adapter' + upstream = [ordered]@{ + repository = 'mattpocock/skills' + url = 'https://github.com/mattpocock/skills' + selected_tag = $Revision + resolved_commit = $Commit + license = 'MIT' + license_source = 'LICENSE at upstream repository root' + } + allowlist = @($Config.packages | ForEach-Object name) + collection_checksum = $collectionChecksum + generated_utc = (Get-Date).ToUniversalTime().ToString('o') + installation = [ordered]@{ + whole_collection = 'npx skills add LightDevCoder/skills-3rdParty#v0.1.1' + single_skill = 'npx skills add LightDevCoder/skills-3rdParty#v0.1.1 --skill ' + revision_semantics = 'The #v0.1.1 fragment pins the local collection release; the mirrored package content is pinned to upstream v1.1.0 and its resolved commit.' + } + entries = @($entries) + } + Write-Utf8 $manifestPath (($manifest | ConvertTo-Json -Depth 16) + "`n") +} + +function Test-Manifest { + param($Config, [string]$Revision, [string]$Commit) + $failures = [System.Collections.Generic.List[string]]::new() + $manifestEntries = @(Get-ManifestEntries) + if ($manifestEntries.Count -ne @($Config.packages).Count) { $failures.Add("manifest entry count $($manifestEntries.Count) does not equal allowlist count $(@($Config.packages).Count)") } + $manifestNames = @($manifestEntries | ForEach-Object package_name | Sort-Object) + $allowNames = @($Config.packages | ForEach-Object name | Sort-Object) + if (($manifestNames -join ',') -ne ($allowNames -join ',')) { $failures.Add('manifest names do not exactly match the selected allowlist') } + foreach ($package in @($Config.packages)) { + $entry = @($manifestEntries | Where-Object package_name -eq $package.name | Select-Object -First 1) + if ($entry.Count -eq 0) { $failures.Add("missing manifest entry: $($package.name)"); continue } + if ($entry[0].resolved_commit -ne $Commit) { $failures.Add("$($package.name) resolved commit is not $Commit") } + $source = Join-Path $UpstreamRoot $package.upstream_path + $destination = Join-Path $skillRoot $package.name + if (-not (Test-Path -LiteralPath $source -PathType Container)) { $failures.Add("missing upstream package: $($package.upstream_path)"); continue } + if (-not (Test-Path -LiteralPath $destination -PathType Container)) { $failures.Add("missing local package: skills/$($package.name)"); continue } + $sourceFiles = Get-RelativeFiles $source + $manifestFiles = @($entry[0].files | ForEach-Object path | Sort-Object) + if (($sourceFiles -join ',') -ne ($manifestFiles -join ',')) { $failures.Add("$($package.name) manifest resources differ from pinned upstream") } + foreach ($relative in $sourceFiles) { + $path = Join-Path $destination $relative + if (-not (Test-Path -LiteralPath $path -PathType Leaf)) { $failures.Add("$($package.name) missing upstream resource: $relative"); continue } + $expected = @($entry[0].files | Where-Object path -eq $relative | Select-Object -First 1) + $actualHash = Get-Sha256 $path + if ($expected.Count -eq 0 -or $actualHash -ne $expected[0].sha256) { $failures.Add("$($package.name) unauthorized local modification: $relative") } + } + foreach ($required in @('SKILL.md', 'agents/openai.yaml', 'UPSTREAM.md', 'PATCHES.md', 'LICENSE')) { + if (-not (Test-Path -LiteralPath (Join-Path $destination $required) -PathType Leaf)) { $failures.Add("$($package.name) missing required package file: $required") } + } + $missing = Get-ReferencedResources $destination + if ($missing.Count -gt 0) { $failures.Add("$($package.name) missing referenced resources: $($missing -join ', ')") } + $front = Get-Frontmatter (Join-Path $destination 'SKILL.md') + $metadata = Get-Content -Raw -LiteralPath (Join-Path $destination 'agents/openai.yaml') + foreach ($marker in @('display_name:', 'short_description:', 'default_prompt:', 'allow_implicit_invocation:')) { + if ($metadata -notmatch [regex]::Escape($marker)) { $failures.Add("$($package.name) metadata missing $marker") } + } + if ($metadata -notmatch ('allow_implicit_invocation:\s*' + $(if ($front.allowImplicitInvocation) { 'true' } else { 'false' }))) { $failures.Add("$($package.name) metadata invocation policy disagrees with upstream frontmatter") } + } + $actualPackages = @(Get-ChildItem -LiteralPath $skillRoot -Directory -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Name | Sort-Object) + if (($actualPackages -join ',') -ne ($allowNames -join ',')) { $failures.Add('local skills/ package directories do not exactly match the 23-Skill allowlist') } + return @($failures) +} + +$config = Read-JsonFile $allowlistPath +$revision = [string]$config.upstream_tag +$expectedCommit = [string]$config.upstream_commit +$resolvedCommit = Get-UpstreamCommit $revision +if ($resolvedCommit -ne $expectedCommit) { throw "Pinned upstream revision mismatch: expected $expectedCommit, got $resolvedCommit" } + +if ($Mode -eq 'dry-run') { + foreach ($package in @($config.packages)) { + $source = Join-Path $UpstreamRoot $package.upstream_path + if (-not (Test-Path -LiteralPath $source -PathType Container)) { throw "Missing upstream package: $($package.upstream_path)" } + Write-Output ("DRY-RUN sync {0} <= {1} ({2} files)" -f $package.name, $package.upstream_path, (Get-RelativeFiles $source).Count) + } + Write-Output "DRY-RUN revision $revision ($resolvedCommit)" + exit 0 +} + +if ($Mode -eq 'sync') { + foreach ($package in @($config.packages)) { + $result = Sync-OnePackage $package $revision $resolvedCommit + Write-Output ("SYNCED {0}: {1} upstream files" -f $result.name, $result.files) + } + Build-Manifest $config $revision $resolvedCommit +} + +if ($Mode -eq 'diff') { + $manifestEntries = @(Get-ManifestEntries) + foreach ($package in @($config.packages)) { + $entry = @($manifestEntries | Where-Object package_name -eq $package.name | Select-Object -First 1) + $source = Join-Path $UpstreamRoot $package.upstream_path + $destination = Join-Path $skillRoot $package.name + if (-not (Test-Path -LiteralPath $destination)) { Write-Output "DIFF $($package.name): local package missing"; continue } + foreach ($relative in (Get-RelativeFiles $source)) { + $path = Join-Path $destination $relative + if (-not (Test-Path -LiteralPath $path)) { Write-Output "DIFF $($package.name): missing $relative"; continue } + $expected = @($entry[0].files | Where-Object path -eq $relative | Select-Object -First 1) + if ($expected.Count -eq 0 -or (Get-Sha256 $path) -ne $expected[0].sha256) { Write-Output "DIFF $($package.name): changed $relative" } + } + } + exit 0 +} + +$failures = @(Test-Manifest $config $revision $resolvedCommit) +if ($failures.Count -gt 0) { + $failures | ForEach-Object { Write-Output "FAIL: $_" } + throw "UPSTREAM_SYNC=$Mode FAIL ($($failures.Count) failures)" +} +Write-Output "UPSTREAM_SYNC=$Mode PASS ($(@($config.packages).Count) packages, pinned $revision/$resolvedCommit)" diff --git a/skills/ask-matt/LICENSE b/skills/ask-matt/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/ask-matt/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/ask-matt/PATCHES.md b/skills/ask-matt/PATCHES.md new file mode 100644 index 0000000..a8f2ff1 --- /dev/null +++ b/skills/ask-matt/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: ask-matt + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/ask-matt/SKILL.md b/skills/ask-matt/SKILL.md new file mode 100644 index 0000000..cc1866a --- /dev/null +++ b/skills/ask-matt/SKILL.md @@ -0,0 +1,76 @@ +--- +name: ask-matt +description: Ask which skill or flow fits your situation. A router over the skills in this repo. +disable-model-invocation: true +--- + +# Ask Matt + +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, or a vocabulary layer that runs underneath. + +## 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. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.) +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-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's an ordered `tickets.md` you work by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**. + - **No** → **`/implement`** right here, in the same context window. + + Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point. + +### Context hygiene + +Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket. + +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-tickets`, 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. + + Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**. + +- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down. + +- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**. When the way from here to the destination isn't visible yet, it charts a **shared map** of investigation tickets on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Then it merges onto the main flow at **`/to-spec`** (or, if the effort turned out small enough, straight to **`/implement`**). Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't. + +## 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`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on. + +## Vocabulary underneath + +Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in. + +- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary. +- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it. + +## 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. +- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper. +- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it. +- **`/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 before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work. diff --git a/skills/ask-matt/UPSTREAM.md b/skills/ask-matt/UPSTREAM.md new file mode 100644 index 0000000..3c889ab --- /dev/null +++ b/skills/ask-matt/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: ask-matt + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** ask-matt +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/ask-matt +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill ask-matt +- **Manual fallback:** copy this complete skills/ask-matt/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry ask-matt diff --git a/skills/ask-matt/agents/openai.yaml b/skills/ask-matt/agents/openai.yaml new file mode 100644 index 0000000..faddc7f --- /dev/null +++ b/skills/ask-matt/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Ask Matt" + short_description: "Ask which skill or flow fits your situation. A router over the skills in this repo." + default_prompt: "Use $ask-matt when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/code-review/LICENSE b/skills/code-review/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/code-review/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/code-review/PATCHES.md b/skills/code-review/PATCHES.md new file mode 100644 index 0000000..0841f2b --- /dev/null +++ b/skills/code-review/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: code-review + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..2a0b524 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,89 @@ +--- +name: code-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". +--- + +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? +- **Spec** — does the code faithfully implement the originating issue / PRD / spec? + +Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. + +The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing. + +## Process + +### 1. Pin the fixed point + +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`. + +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: + +1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`. +2. A path the user passed as an argument. +3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature. +4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available". + +### 3. Identify the standards sources + +Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`. + +On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it: + +- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell. +- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces. + +Each smell reads *what it is* → *how to fix*; match it against the diff: + +- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky. +- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both. +- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies. +- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that. +- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type. +- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share. +- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module. +- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason. +- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows. +- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object. +- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct. +- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition. + +### 4. Spawn both sub-agents in parallel + +Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both. + +**Standards sub-agent prompt** — include: + +- The full diff command and commit list. +- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it. +- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. 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: "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 (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. + +## Why two axes + +A change can pass one axis and fail the other: + +- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.** +- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.** + +Reporting them separately stops one axis from masking the other. diff --git a/skills/code-review/UPSTREAM.md b/skills/code-review/UPSTREAM.md new file mode 100644 index 0000000..f4fca17 --- /dev/null +++ b/skills/code-review/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: code-review + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** code-review +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/code-review +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill code-review +- **Manual fallback:** copy this complete skills/code-review/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry code-review diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml new file mode 100644 index 0000000..b57c9d7 --- /dev/null +++ b/skills/code-review/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Code Review" + short_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\"." + default_prompt: "Use $code-review when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/codebase-design/DEEPENING.md b/skills/codebase-design/DEEPENING.md new file mode 100644 index 0000000..3938457 --- /dev/null +++ b/skills/codebase-design/DEEPENING.md @@ -0,0 +1,37 @@ +# Deepening + +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 + +When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam. + +### 1. In-process + +Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed. + +### 2. Local-substitutable + +Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface. + +### 3. Remote but owned (Ports & Adapters) + +Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter. + +Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."* + +### 4. True external (Mock) + +Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter. + +## Seam discipline + +- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection. +- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them. + +## Testing strategy: replace, don't layer + +- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them. +- Write new tests at the deepened module's interface. The **interface is the test surface**. +- Tests assert on observable outcomes through the interface, not internal state. +- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface. diff --git a/skills/codebase-design/DESIGN-IT-TWICE.md b/skills/codebase-design/DESIGN-IT-TWICE.md new file mode 100644 index 0000000..49a7c42 --- /dev/null +++ b/skills/codebase-design/DESIGN-IT-TWICE.md @@ -0,0 +1,44 @@ +# 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 [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. + +## Process + +### 1. Frame the problem space + +Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: + +- The constraints any new interface would need to satisfy +- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete + +Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. + +### 2. Spawn sub-agents + +Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. + +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: + +- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." +- Agent 2: "Maximise flexibility — support many use cases and extension." +- 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 [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: + +1. Interface (types, methods, params — plus invariants, ordering, error modes) +2. Usage example showing how callers use it +3. What the implementation hides behind the seam +4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +5. Trade-offs — where leverage is high, where it's thin + +### 3. Present and compare + +Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**. + +After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu. diff --git a/skills/codebase-design/LICENSE b/skills/codebase-design/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/codebase-design/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/codebase-design/PATCHES.md b/skills/codebase-design/PATCHES.md new file mode 100644 index 0000000..f8c0065 --- /dev/null +++ b/skills/codebase-design/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: codebase-design + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/codebase-design/SKILL.md b/skills/codebase-design/SKILL.md new file mode 100644 index 0000000..16620c2 --- /dev/null +++ b/skills/codebase-design/SKILL.md @@ -0,0 +1,114 @@ +--- +name: codebase-design +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 + +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/codebase-design/UPSTREAM.md b/skills/codebase-design/UPSTREAM.md new file mode 100644 index 0000000..67a6467 --- /dev/null +++ b/skills/codebase-design/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: codebase-design + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** codebase-design +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/codebase-design +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill codebase-design +- **Manual fallback:** copy this complete skills/codebase-design/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry codebase-design diff --git a/skills/codebase-design/agents/openai.yaml b/skills/codebase-design/agents/openai.yaml new file mode 100644 index 0000000..934f128 --- /dev/null +++ b/skills/codebase-design/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Codebase Design" + short_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." + default_prompt: "Use $codebase-design when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/design-an-interface/LICENSE b/skills/design-an-interface/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/design-an-interface/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/design-an-interface/PATCHES.md b/skills/design-an-interface/PATCHES.md new file mode 100644 index 0000000..a2f4007 --- /dev/null +++ b/skills/design-an-interface/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: design-an-interface + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/design-an-interface/SKILL.md b/skills/design-an-interface/SKILL.md new file mode 100644 index 0000000..d056bd1 --- /dev/null +++ b/skills/design-an-interface/SKILL.md @@ -0,0 +1,94 @@ +--- +name: design-an-interface +description: Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice". +--- + +# Design an Interface + +Based on "Design It Twice" from "A Philosophy of Software Design": your first idea is unlikely to be the best. Generate multiple radically different designs, then compare. + +## Workflow + +### 1. Gather Requirements + +Before designing, understand: + +- [ ] What problem does this module solve? +- [ ] Who are the callers? (other modules, external users, tests) +- [ ] What are the key operations? +- [ ] Any constraints? (performance, compatibility, existing patterns) +- [ ] What should be hidden inside vs exposed? + +Ask: "What does this module need to do? Who will use it?" + +### 2. Generate Designs (Parallel Sub-Agents) + +Spawn 3+ sub-agents simultaneously using Task tool. Each must produce a **radically different** approach. + +``` +Prompt template for each sub-agent: + +Design an interface for: [module description] + +Requirements: [gathered requirements] + +Constraints for this design: [assign a different constraint to each agent] +- Agent 1: "Minimize method count - aim for 1-3 methods max" +- Agent 2: "Maximize flexibility - support many use cases" +- Agent 3: "Optimize for the most common case" +- Agent 4: "Take inspiration from [specific paradigm/library]" + +Output format: +1. Interface signature (types/methods) +2. Usage example (how caller uses it) +3. What this design hides internally +4. Trade-offs of this approach +``` + +### 3. Present Designs + +Show each design with: + +1. **Interface signature** - types, methods, params +2. **Usage examples** - how callers actually use it in practice +3. **What it hides** - complexity kept internal + +Present designs sequentially so user can absorb each approach before comparison. + +### 4. Compare Designs + +After showing all designs, compare them on: + +- **Interface simplicity**: fewer methods, simpler params +- **General-purpose vs specialized**: flexibility vs focus +- **Implementation efficiency**: does shape allow efficient internals? +- **Depth**: small interface hiding significant complexity (good) vs large interface with thin implementation (bad) +- **Ease of correct use** vs **ease of misuse** + +Discuss trade-offs in prose, not tables. Highlight where designs diverge most. + +### 5. Synthesize + +Often the best design combines insights from multiple options. Ask: + +- "Which design best fits your primary use case?" +- "Any elements from other designs worth incorporating?" + +## Evaluation Criteria + +From "A Philosophy of Software Design": + +**Interface simplicity**: Fewer methods, simpler params = easier to learn and use correctly. + +**General-purpose**: Can handle future use cases without changes. But beware over-generalization. + +**Implementation efficiency**: Does interface shape allow efficient implementation? Or force awkward internals? + +**Depth**: Small interface hiding significant complexity = deep module (good). Large interface with thin implementation = shallow module (avoid). + +## Anti-Patterns + +- Don't let sub-agents produce similar designs - enforce radical difference +- Don't skip comparison - the value is in contrast +- Don't implement - this is purely about interface shape +- Don't evaluate based on implementation effort diff --git a/skills/design-an-interface/UPSTREAM.md b/skills/design-an-interface/UPSTREAM.md new file mode 100644 index 0000000..d9270df --- /dev/null +++ b/skills/design-an-interface/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: design-an-interface + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** deprecated +- **Package:** design-an-interface +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/deprecated/design-an-interface +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill design-an-interface +- **Manual fallback:** copy this complete skills/design-an-interface/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry design-an-interface diff --git a/skills/design-an-interface/agents/openai.yaml b/skills/design-an-interface/agents/openai.yaml new file mode 100644 index 0000000..e2004b4 --- /dev/null +++ b/skills/design-an-interface/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Design An Interface" + short_description: "Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions \"design it twice\"." + default_prompt: "Use $design-an-interface when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/diagnosing-bugs/LICENSE b/skills/diagnosing-bugs/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/diagnosing-bugs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/diagnosing-bugs/PATCHES.md b/skills/diagnosing-bugs/PATCHES.md new file mode 100644 index 0000000..db1b7f4 --- /dev/null +++ b/skills/diagnosing-bugs/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: diagnosing-bugs + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/diagnosing-bugs/SKILL.md b/skills/diagnosing-bugs/SKILL.md new file mode 100644 index 0000000..f400de7 --- /dev/null +++ b/skills/diagnosing-bugs/SKILL.md @@ -0,0 +1,134 @@ +--- +name: diagnosing-bugs +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 + +A discipline for hard bugs. Skip phases only when explicitly justified. + +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 + +**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.** + +### Ways to construct one — try them in roughly this order + +1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e. +2. **Curl / HTTP script** against a running dev server. +3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot. +4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network. +5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation. +6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call. +7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode. +8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it. +9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs. +10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you. + +Build the right feedback loop, and the bug is 90% fixed. + +### Tighten the loop + +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 one is tight — a debugging superpower. + +### Non-deterministic bugs + +The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable. + +### When you genuinely cannot build a loop + +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. + +### Completion criterion — a tight loop that goes red + +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: + +- [ ] **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: + +- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix. +- [ ] 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. + +### 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 + +Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea. + +Each hypothesis must be **falsifiable**: state the prediction it makes. + +> Format: "If is the cause, then will make the bug disappear / will make it worse." + +If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it. + +**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK. + +## Phase 4 — Instrument + +Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.** + +Tool preference: + +1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs. +2. **Targeted logs** at the boundaries that distinguish hypotheses. +3. Never "log everything and grep". + +**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die. + +**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second. + +## Phase 5 — Fix + regression test + +Write the regression test **before the fix** — but only if there is a **correct seam** for it. + +A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence. + +**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase. + +If a correct seam exists: + +1. Turn the minimised repro into a failing test at that seam. +2. Watch it fail. +3. Apply the fix. +4. Watch it pass. +5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario. + +## Phase 6 — Cleanup + post-mortem + +Required before declaring done: + +- [ ] Original repro no longer reproduces (re-run the Phase 1 loop) +- [ ] Regression test passes (or absence of seam is documented) +- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix) +- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location) +- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns + +**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started. diff --git a/skills/diagnosing-bugs/UPSTREAM.md b/skills/diagnosing-bugs/UPSTREAM.md new file mode 100644 index 0000000..f2a216a --- /dev/null +++ b/skills/diagnosing-bugs/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: diagnosing-bugs + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** diagnosing-bugs +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/diagnosing-bugs +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill diagnosing-bugs +- **Manual fallback:** copy this complete skills/diagnosing-bugs/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry diagnosing-bugs diff --git a/skills/diagnosing-bugs/agents/openai.yaml b/skills/diagnosing-bugs/agents/openai.yaml new file mode 100644 index 0000000..38dfb60 --- /dev/null +++ b/skills/diagnosing-bugs/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Diagnosing Bugs" + short_description: "Diagnosis loop for hard bugs and performance regressions. Use when the user says \"diagnose\"/\"debug this\", or reports something broken/throwing/failing/slow." + default_prompt: "Use $diagnosing-bugs when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/diagnosing-bugs/scripts/hitl-loop.template.sh b/skills/diagnosing-bugs/scripts/hitl-loop.template.sh new file mode 100644 index 0000000..40afc46 --- /dev/null +++ b/skills/diagnosing-bugs/scripts/hitl-loop.template.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Human-in-the-loop reproduction loop. +# Copy this file, edit the steps below, and run it. +# The agent runs the script; the user follows prompts in their terminal. +# +# Usage: +# bash hitl-loop.template.sh +# +# Two helpers: +# step "" → show instruction, wait for Enter +# capture VAR "" → show question, read response into VAR +# +# At the end, captured values are printed as KEY=VALUE for the agent to parse. + +set -euo pipefail + +step() { + printf '\n>>> %s\n' "$1" + read -r -p " [Enter when done] " _ +} + +capture() { + local var="$1" question="$2" answer + printf '\n>>> %s\n' "$question" + read -r -p " > " answer + printf -v "$var" '%s' "$answer" +} + +# --- edit below --------------------------------------------------------- + +step "Open the app at http://localhost:3000 and sign in." + +capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)" + +capture ERROR_MSG "Paste the error message (or 'none'):" + +# --- edit above --------------------------------------------------------- + +printf '\n--- Captured ---\n' +printf 'ERRORED=%s\n' "$ERRORED" +printf 'ERROR_MSG=%s\n' "$ERROR_MSG" diff --git a/skills/domain-modeling/ADR-FORMAT.md b/skills/domain-modeling/ADR-FORMAT.md new file mode 100644 index 0000000..da7e78e --- /dev/null +++ b/skills/domain-modeling/ADR-FORMAT.md @@ -0,0 +1,47 @@ +# ADR Format + +ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. + +Create the `docs/adr/` directory lazily — only when the first ADR is needed. + +## Template + +```md +# {Short title of the decision} + +{1-3 sentences: what's the context, what did we decide, and why.} +``` + +That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. + +## Optional sections + +Only include these when they add genuine value. Most ADRs won't need them. + +- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited +- **Considered Options** — only when the rejected alternatives are worth remembering +- **Consequences** — only when non-obvious downstream effects need to be called out + +## Numbering + +Scan `docs/adr/` for the highest existing number and increment by one. + +## When to offer an ADR + +All three of these must be true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will look at the code and wonder "why on earth 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 a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing." + +### What qualifies + +- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres." +- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." +- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out. +- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s. +- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate. +- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract." +- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months. diff --git a/skills/domain-modeling/CONTEXT-FORMAT.md b/skills/domain-modeling/CONTEXT-FORMAT.md new file mode 100644 index 0000000..eaf2a18 --- /dev/null +++ b/skills/domain-modeling/CONTEXT-FORMAT.md @@ -0,0 +1,60 @@ +# CONTEXT.md Format + +## Structure + +```md +# {Context Name} + +{One or two sentence description of what this context is and why it exists.} + +## Language + +**Order**: +{A one or two sentence description of the term} +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request + +**Customer**: +A person or organization that places orders. +_Avoid_: Client, buyer, account +``` + +## Rules + +- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`. +- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. +- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. +- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. + +## Single vs multi-context repos + +**Single context (most repos):** One `CONTEXT.md` at the repo root. + +**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other: + +```md +# Context Map + +## Contexts + +- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders +- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments +- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping + +## Relationships + +- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking +- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices +- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money` +``` + +The skill infers which structure applies: + +- If `CONTEXT-MAP.md` exists, read it to find contexts +- If only a root `CONTEXT.md` exists, single context +- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved + +When multiple contexts exist, infer which one the current topic relates to. If unclear, ask. diff --git a/skills/domain-modeling/LICENSE b/skills/domain-modeling/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/domain-modeling/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/domain-modeling/PATCHES.md b/skills/domain-modeling/PATCHES.md new file mode 100644 index 0000000..9606cb3 --- /dev/null +++ b/skills/domain-modeling/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: domain-modeling + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/domain-modeling/SKILL.md b/skills/domain-modeling/SKILL.md new file mode 100644 index 0000000..d0f7e1a --- /dev/null +++ b/skills/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +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 + +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/domain-modeling/UPSTREAM.md b/skills/domain-modeling/UPSTREAM.md new file mode 100644 index 0000000..e4080fd --- /dev/null +++ b/skills/domain-modeling/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: domain-modeling + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** domain-modeling +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/domain-modeling +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill domain-modeling +- **Manual fallback:** copy this complete skills/domain-modeling/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry domain-modeling diff --git a/skills/domain-modeling/agents/openai.yaml b/skills/domain-modeling/agents/openai.yaml new file mode 100644 index 0000000..069c5ae --- /dev/null +++ b/skills/domain-modeling/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Domain Modeling" + short_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." + default_prompt: "Use $domain-modeling when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/grill-me/LICENSE b/skills/grill-me/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/grill-me/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/grill-me/PATCHES.md b/skills/grill-me/PATCHES.md new file mode 100644 index 0000000..f23a540 --- /dev/null +++ b/skills/grill-me/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: grill-me + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/grill-me/SKILL.md b/skills/grill-me/SKILL.md new file mode 100644 index 0000000..9470cfc --- /dev/null +++ b/skills/grill-me/SKILL.md @@ -0,0 +1,7 @@ +--- +name: grill-me +description: A relentless interview to sharpen a plan or design. +disable-model-invocation: true +--- + +Run a `/grilling` session. diff --git a/skills/grill-me/UPSTREAM.md b/skills/grill-me/UPSTREAM.md new file mode 100644 index 0000000..42cae20 --- /dev/null +++ b/skills/grill-me/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: grill-me + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** productivity +- **Package:** grill-me +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/productivity/grill-me +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** grilling. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill grill-me +- **Manual fallback:** copy this complete skills/grill-me/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry grill-me diff --git a/skills/grill-me/agents/openai.yaml b/skills/grill-me/agents/openai.yaml new file mode 100644 index 0000000..82b40d5 --- /dev/null +++ b/skills/grill-me/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Grill Me" + short_description: "A relentless interview to sharpen a plan or design." + default_prompt: "Use $grill-me when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/grill-with-docs/LICENSE b/skills/grill-with-docs/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/grill-with-docs/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/grill-with-docs/PATCHES.md b/skills/grill-with-docs/PATCHES.md new file mode 100644 index 0000000..16e5f1b --- /dev/null +++ b/skills/grill-with-docs/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: grill-with-docs + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/grill-with-docs/SKILL.md b/skills/grill-with-docs/SKILL.md new file mode 100644 index 0000000..bed05d2 --- /dev/null +++ b/skills/grill-with-docs/SKILL.md @@ -0,0 +1,7 @@ +--- +name: grill-with-docs +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 +--- + +Run a `/grilling` session, using the `/domain-modeling` skill. diff --git a/skills/grill-with-docs/UPSTREAM.md b/skills/grill-with-docs/UPSTREAM.md new file mode 100644 index 0000000..0ecdf0b --- /dev/null +++ b/skills/grill-with-docs/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: grill-with-docs + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** grill-with-docs +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/grill-with-docs +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** grilling, domain-modeling. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill grill-with-docs +- **Manual fallback:** copy this complete skills/grill-with-docs/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry grill-with-docs diff --git a/skills/grill-with-docs/agents/openai.yaml b/skills/grill-with-docs/agents/openai.yaml new file mode 100644 index 0000000..7bd88fa --- /dev/null +++ b/skills/grill-with-docs/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Grill With Docs" + short_description: "A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go." + default_prompt: "Use $grill-with-docs when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/grilling/LICENSE b/skills/grilling/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/grilling/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/grilling/PATCHES.md b/skills/grilling/PATCHES.md new file mode 100644 index 0000000..5ea9775 --- /dev/null +++ b/skills/grilling/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: grilling + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/grilling/SKILL.md b/skills/grilling/SKILL.md new file mode 100644 index 0000000..219930f --- /dev/null +++ b/skills/grilling/SKILL.md @@ -0,0 +1,12 @@ +--- +name: grilling +description: Grill 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. + +Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. + +If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. + +Do not enact the plan until I confirm we have reached a shared understanding. diff --git a/skills/grilling/UPSTREAM.md b/skills/grilling/UPSTREAM.md new file mode 100644 index 0000000..a72b0c3 --- /dev/null +++ b/skills/grilling/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: grilling + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** productivity +- **Package:** grilling +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/productivity/grilling +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill grilling +- **Manual fallback:** copy this complete skills/grilling/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry grilling diff --git a/skills/grilling/agents/openai.yaml b/skills/grilling/agents/openai.yaml new file mode 100644 index 0000000..4db38f8 --- /dev/null +++ b/skills/grilling/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Grilling" + short_description: "Grill 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." + default_prompt: "Use $grilling when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: true diff --git a/skills/handoff/LICENSE b/skills/handoff/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/handoff/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/handoff/PATCHES.md b/skills/handoff/PATCHES.md new file mode 100644 index 0000000..ee53f20 --- /dev/null +++ b/skills/handoff/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: handoff + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/handoff/SKILL.md b/skills/handoff/SKILL.md new file mode 100644 index 0000000..043d9e1 --- /dev/null +++ b/skills/handoff/SKILL.md @@ -0,0 +1,16 @@ +--- +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. + +Include a "suggested skills" section in the document, which suggests skills that the agent should invoke. + +Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. + +Redact any sensitive information, such as API keys, passwords, or personally identifiable information. + +If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly. diff --git a/skills/handoff/UPSTREAM.md b/skills/handoff/UPSTREAM.md new file mode 100644 index 0000000..2e01143 --- /dev/null +++ b/skills/handoff/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: handoff + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** productivity +- **Package:** handoff +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/productivity/handoff +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill handoff +- **Manual fallback:** copy this complete skills/handoff/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry handoff diff --git a/skills/handoff/agents/openai.yaml b/skills/handoff/agents/openai.yaml new file mode 100644 index 0000000..46d2981 --- /dev/null +++ b/skills/handoff/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Handoff" + short_description: "Compact the current conversation into a handoff document for another agent to pick up." + default_prompt: "Use $handoff when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/implement/LICENSE b/skills/implement/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/implement/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/implement/PATCHES.md b/skills/implement/PATCHES.md new file mode 100644 index 0000000..84c0d58 --- /dev/null +++ b/skills/implement/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: implement + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..7a0b11f --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,15 @@ +--- +name: implement +description: "Implement a piece of work based on a spec or set of tickets." +disable-model-invocation: true +--- + +Implement the work described by the user in the spec or tickets. + +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 /code-review to review the work. + +Commit your work to the current branch. diff --git a/skills/implement/UPSTREAM.md b/skills/implement/UPSTREAM.md new file mode 100644 index 0000000..940c451 --- /dev/null +++ b/skills/implement/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: implement + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** implement +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/implement +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill implement +- **Manual fallback:** copy this complete skills/implement/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry implement diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml new file mode 100644 index 0000000..21efafd --- /dev/null +++ b/skills/implement/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Implement" + short_description: "Implement a piece of work based on a spec or set of tickets." + default_prompt: "Use $implement when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/improve-codebase-architecture/HTML-REPORT.md b/skills/improve-codebase-architecture/HTML-REPORT.md new file mode 100644 index 0000000..17f6d2c --- /dev/null +++ b/skills/improve-codebase-architecture/HTML-REPORT.md @@ -0,0 +1,123 @@ +# HTML Report Format + +The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic. + +## Scaffold + +```html + + + + + Architecture review — {{repo name}} + + + + + +
+
...
+
...
+
...
+
+ + +``` + +## Header + +Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates. + +## Candidate card + +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 `
`: + +- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline"). +- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`). +- **Files** — monospaced list, `font-mono text-sm`. +- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below. +- **Problem** — one sentence. What hurts. +- **Solution** — one sentence. What changes. +- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers". +- **ADR callout** (if applicable) — one line in an amber-tinted box. + +No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram. + +## Diagram patterns + +Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point. + +### Mermaid graph (the workhorse for dependencies / call flow) + +Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1." + +```html +
+ 
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+
+
+``` + +### Hand-built boxes-and-arrows (when Mermaid's layout fights you) + +Modules as `
`s with borders and labels. Arrows as inline SVG `` or `` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight. + +### Cross-section (good for layered shallowness) + +Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility. + +### Mass diagram (good for "interface as wide as implementation") + +Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep). + +### Call-graph collapse + +Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it. + +## Style guidance + +- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate). +- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings. +- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling. +- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI. +- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering. + +## Top recommendation section + +One larger card. Candidate name, one sentence on why, anchor link to its card. That's it. + +## Tone + +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. + +**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module). + +**Phrasings that fit the style:** + +- "Order intake module is shallow — interface nearly matches the implementation." +- "Pricing leaks across the seam." +- "Deepen: one interface, one place to test." +- "Two adapters justify the seam: HTTP in prod, in-memory in tests." + +**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 the `/codebase-design` glossary, reach for one that is before inventing a new one. diff --git a/skills/improve-codebase-architecture/LICENSE b/skills/improve-codebase-architecture/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/improve-codebase-architecture/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/improve-codebase-architecture/PATCHES.md b/skills/improve-codebase-architecture/PATCHES.md new file mode 100644 index 0000000..9fe9f8f --- /dev/null +++ b/skills/improve-codebase-architecture/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: improve-codebase-architecture + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/improve-codebase-architecture/SKILL.md b/skills/improve-codebase-architecture/SKILL.md new file mode 100644 index 0000000..a79b493 --- /dev/null +++ b/skills/improve-codebase-architecture/SKILL.md @@ -0,0 +1,66 @@ +--- +name: improve-codebase-architecture +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. + +This command is _informed_ by the project's domain model and built on a shared design vocabulary: + +- 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 (`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: + +- Where does understanding one concept require bouncing between many small modules? +- Where are modules **shallow** — interface nearly as complex as the implementation? +- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)? +- Where do tightly-coupled modules leak across their seams? +- Which parts of the codebase are untested, or hard to test through their current interface? + +Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want. + +### 2. Present candidates as an HTML report + +Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `/architecture-review-.html` so each run gets a fresh file. Open it for the user — `xdg-open ` on Linux, `open ` on macOS, `start ` on Windows — and tell them the absolute path. + +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, render a card with: + +- **Files** — which files/modules are involved +- **Problem** — why the current architecture is causing friction +- **Solution** — plain English description of what would change +- **Benefits** — explained in terms of locality and leverage, and how tests would improve +- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening +- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge + +End the report with a **Top recommendation** section: which candidate you'd tackle first and why. + +**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. + +See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance. + +Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?" + +### 3. Grilling loop + +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 — 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`. 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. +- **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/improve-codebase-architecture/UPSTREAM.md b/skills/improve-codebase-architecture/UPSTREAM.md new file mode 100644 index 0000000..3aabc3f --- /dev/null +++ b/skills/improve-codebase-architecture/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: improve-codebase-architecture + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** engineering +- **Package:** improve-codebase-architecture +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/engineering/improve-codebase-architecture +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill improve-codebase-architecture +- **Manual fallback:** copy this complete skills/improve-codebase-architecture/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry improve-codebase-architecture diff --git a/skills/improve-codebase-architecture/agents/openai.yaml b/skills/improve-codebase-architecture/agents/openai.yaml new file mode 100644 index 0000000..f42b255 --- /dev/null +++ b/skills/improve-codebase-architecture/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Improve Codebase Architecture" + short_description: "Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick." + default_prompt: "Use $improve-codebase-architecture when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/loop-me/LICENSE b/skills/loop-me/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/loop-me/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/loop-me/PATCHES.md b/skills/loop-me/PATCHES.md new file mode 100644 index 0000000..63ba7cd --- /dev/null +++ b/skills/loop-me/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: loop-me + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/loop-me/SKILL.md b/skills/loop-me/SKILL.md new file mode 100644 index 0000000..3a8c52c --- /dev/null +++ b/skills/loop-me/SKILL.md @@ -0,0 +1,32 @@ +--- +name: loop-me +description: Grill me about specs for the workflows I want to build, within this workspace. +disable-model-invocation: true +argument-hint: "A workflow to design, or nothing to go find one" +--- + +Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, one question at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things. + +## The loop lens + +A **loop** is a recurring pattern in the user's life: their career, their week, their morning, a single repeated activity. Picturing a life as loops within loops reveals how predictable its activities really are — which is what makes them worth **delegating**. Use the lens to find loops worth specifying, and propose ones the user hasn't noticed. + +A **workflow** is the spec of one loop, made real. You run a workflow on a loop — the loop is its running instantiation. Workflows live in `workflows/*.md` and are the source of truth. + +## Vocabulary + +A shared language, reached for only when a workflow calls for it — never a checklist. **Mandate nothing structural**: a workflow needs no AI, no checkpoint, and no schedule unless the grilling shows it does. + +- **Trigger** — what fires each run: an **event** (a new email, a new issue) or a **schedule** (every morning). Event-triggering is usually the more efficient. +- **Checkpoint** — a human-in-the-loop point where the user is asked to verify or decide. Some workflows have none and run autonomously; some use no AI at all. +- **Push right** — defer the checkpoint as far as it will go. Do maximal work before involving the human, so they are asked once, late, with everything prepared. +- **Brief** — what a checkpoint presents: a tight, decision-ready summary — what was produced, why, and a link down to the asset itself — never the raw output. The user reads a brief, not a draft. Speed of review is imperative. + +## Definition of done + +A workflow spec is done when an implementer agent could build it without asking a single question. Grill until then; nothing is done while a question remains. + +## The workspace + +- `workflows/*.md` — one spec per workflow. +- `NOTES.md` — raw notes on the user's world: the tools they use, the channels they process, and their own terminology for both. When it is empty or thin, interview them about their world before specifying anything. Sharpen fuzzy terms into canonical ones as they surface, and record them here. diff --git a/skills/loop-me/UPSTREAM.md b/skills/loop-me/UPSTREAM.md new file mode 100644 index 0000000..b7fbd46 --- /dev/null +++ b/skills/loop-me/UPSTREAM.md @@ -0,0 +1,50 @@ +# Upstream Record: loop-me + +This package is a pinned upstream snapshot with a local host-metadata adapter. +The upstream Skill instructions and referenced resources are preserved. + +## Identity + +- **Source group:** in-progress +- **Package:** loop-me +- **Upstream repository:** `mattpocock/skills` +- **Canonical URL:** https://github.com/mattpocock/skills +- **Original package path:** skills/in-progress/loop-me +- **Selected upstream tag:** v1.1.0 +- **Resolved commit:** d574778f94cf620fcc8ce741584093bc650a61d3 +- **Applicable license:** MIT; see `LICENSE` in this package. +- **Upstream author/notice:** Matt Pocock and contributors; preserve the upstream license. + +## Local packaging state + +- **State:** pinned upstream snapshot with metadata-adapter-only local change. +- **Local patch:** `agents/openai.yaml` supplies the host metadata required by + this collection's discovery checks; it does not alter `SKILL.md` behavior or + upstream resources. +- **Why the adapter exists:** the upstream package does not ship this + collection-specific `agents/openai.yaml`; omitting it makes metadata-aware + discovery unable to report invocation policy reliably. +- **Dependencies:** none. These are declared peer Skills, not hidden runtime + imports. Install them separately when a workflow explicitly needs them. +- **Navigation boundary:** `ask-matt` remains a router and does not execute or + install the Skills it mentions. + +## Installation and update + +- **Whole collection:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 +- **Single package:** npx skills add LightDevCoder/skills-3rdParty#v1.1.0 --skill loop-me +- **Manual fallback:** copy this complete skills/loop-me/ directory + into the host's recognized Skills root. +- **Update source:** run `scripts/sync-upstream.ps1 -Mode check` against the + pinned checkout; review upstream diff, then use `-Mode sync` only after the + allowlist and revision are approved. + +## Differences and evidence + +- **Upstream behavior preserved:** yes, for the upstream package files listed + in `UPSTREAM_LOCK.json`. +- **Local difference:** metadata adapter and this provenance record only. +- **Known limitations:** host-specific discovery and private-repository access + remain dependent on the installer and credentials used by the consumer. +- **Patch record:** `PATCHES.md` +- **Lock entry:** UPSTREAM_LOCK.json entry loop-me diff --git a/skills/loop-me/agents/openai.yaml b/skills/loop-me/agents/openai.yaml new file mode 100644 index 0000000..f914d1a --- /dev/null +++ b/skills/loop-me/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Loop Me" + short_description: "Grill me about specs for the workflows I want to build, within this workspace." + default_prompt: "Use $loop-me when this task matches its upstream contract; preserve its explicit stopping boundary." + +policy: + allow_implicit_invocation: false diff --git a/skills/prototype/LICENSE b/skills/prototype/LICENSE new file mode 100644 index 0000000..f1dd2c0 --- /dev/null +++ b/skills/prototype/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Matt Pocock + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/prototype/LOGIC.md b/skills/prototype/LOGIC.md new file mode 100644 index 0000000..526ecb1 --- /dev/null +++ b/skills/prototype/LOGIC.md @@ -0,0 +1,79 @@ +# Logic Prototype + +A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about **business logic, state transitions, or data shape** — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases. + +## When this is the right shape + +- "I'm not sure if this state machine handles the edge case where X then Y." +- "Does this data model actually let me represent the case where..." +- "I want to feel out what the API should look like before writing it." +- Anything where the user wants to **press buttons and watch state change**. + +If the question is "what should this look like" — wrong branch. Use [UI.md](UI.md). + +## Process + +### 1. State the question + +Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK. + +### 2. Pick the language + +Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask. + +Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype. + +### 3. Isolate the logic in a portable module + +Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be. + +The right shape depends on the question: + +- **A pure reducer** — `(state, action) => state`. Good when actions are discrete events and state is a single value. +- **A state machine** — explicit states and transitions. Good when "which actions are even legal right now" is part of the question. +- **A small set of pure functions** over a plain data type. Good when there's no implicit current state — just transformations. +- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state. + +Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction. + +This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted. + +### 4. Build the smallest TUI that exposes the state + +Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback. + +Each frame has two parts, in this order: + +1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project. +2. **Keyboard shortcuts**, listed at the bottom: `[a] add user [d] delete user [t] tick clock [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly. + +Behaviour: + +1. **Initialise state** — a single in-memory object/struct. Render the first frame on start. +2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state. +3. **Re-render** the full frame after every action — don't append, replace. +4. **Loop until quit.** + +The whole frame should fit on one screen. + +### 5. Make it runnable in one command + +Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run ` or equivalent — never need to remember a path. + +If the host project has no task runner, just put the command at the top of the prototype's README. + +### 6. Hand it over + +Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve. + +### 7. Capture the answer + +When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted. + +## Anti-patterns + +- **Don't add tests.** A prototype that needs tests is no longer a prototype. +- **Don't wire it to the real database.** Use an in-memory store unless the question is specifically about persistence. +- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question. +- **Don't blur the logic and the TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module. +- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping. diff --git a/skills/prototype/PATCHES.md b/skills/prototype/PATCHES.md new file mode 100644 index 0000000..a25173f --- /dev/null +++ b/skills/prototype/PATCHES.md @@ -0,0 +1,24 @@ +# Local Patch Record: prototype + +- **Upstream revision:** v1.1.0 (d574778f94cf620fcc8ce741584093bc650a61d3) +- **Local state:** metadata-adapter-only; no upstream behavior patch. +- **Allowed local paths:** `agents/openai.yaml`, `UPSTREAM.md`, `PATCHES.md`, `LICENSE` + +## P0001 — Collection host metadata adapter + +- **Status:** active +- **Local file:** `agents/openai.yaml` +- **Rationale:** make display name, description, default prompt, and explicit + invocation policy available to metadata-aware hosts and `ask-light`. +- **Behavior preserved:** all upstream `SKILL.md`, scripts, references, assets, + and templates are copied without modification. +- **Compatibility impact:** none to the upstream Skill contract; the adapter + is ignored by hosts that do not consume it. +- **Regression evidence:** `tests/third-party-collection-tests.ps1` and the + release evidence under `docs/evidence/releases/`. + +## Patch-set review + +- All upstream file differences are hash-checked by `sync-upstream.ps1`. +- Any change to an upstream-managed file fails `-Mode check` until explicitly + reviewed and represented by a new patch record. diff --git a/skills/prototype/SKILL.md b/skills/prototype/SKILL.md new file mode 100644 index 0000000..9425f7d --- /dev/null +++ b/skills/prototype/SKILL.md @@ -0,0 +1,30 @@ +--- +name: prototype +description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like. +--- + +# Prototype + +A prototype is **throwaway code that answers a question**. The question decides the shape. + +## Pick a branch + +Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around: + +- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper. +- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar. + +The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype. + +## Rules that apply to both + +1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure. +2. **One command to run.** Whatever the project's existing task runner supports — `pnpm `, `python `, `bun `, etc. The user must be able to start it without thinking. +3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name. +4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it. +5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed. +6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo. + +## When done + +The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype. diff --git a/skills/prototype/UI.md b/skills/prototype/UI.md new file mode 100644 index 0000000..f3b6e64 --- /dev/null +++ b/skills/prototype/UI.md @@ -0,0 +1,112 @@ +# UI Prototype + +Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away. + +If the question is about logic/state rather than what something looks like — wrong branch. Use [LOGIC.md](LOGIC.md). + +## When this is the right shape + +- "What should this page look like?" +- "I want to see a few options for this dashboard before committing." +- "Try a different layout for the settings screen." +- Any time the user would otherwise spend a day picking between three vague mockups in their head. + +## Two sub-shapes — strongly prefer sub-shape A + +A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home. + +### Sub-shape A — adjustment to an existing page (preferred) + +The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to. + +If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page. + +### Sub-shape B — a new page (last resort) + +Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible. + +Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern. + +Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose. + +In both sub-shapes the floating bottom bar is identical. + +## Process + +### 1. State the question and pick N + +Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there. + +Write down the plan in one line, in the prototype's location or a top-of-file comment: + +> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route." + +This works whether the user is here to push back or not. + +### 2. Generate radically different variants + +Draft each variant. Hold each one to: + +- The page's purpose and the data it has access to. +- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever). +- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`. + +Variants must be **structurally different** — different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance. + +### 3. Wire them together + +Create a single switcher component on the route: + +```tsx +// pseudo-code — adapt to the project's framework +const variant = searchParams.get('variant') ?? 'A'; +return ( + <> + {variant === 'A' && } + {variant === 'B' && } + {variant === 'C' && } + + +); +``` + +For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant. + +For sub-shape B (new page): the throwaway route under `/prototype/` mounts the same switcher. + +### 4. Build the floating switcher + +A small fixed-position bar at the bottom-centre of the screen with three pieces: + +- **Left arrow** — cycles to the previous variant (wraps around). +- **Variant label** — shows the current variant key and, if the variant exports a name, that name too. e.g. `B — Sidebar layout`. +- **Right arrow** — cycles forward (wraps around). + +Behaviour: + +- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) so the variant is shareable and reload-stable. +- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an ``, `