From 603a30b76c58e88a2ddd956660bdc708da28321c Mon Sep 17 00:00:00 2001 From: John Osumi <931193+sumitake@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:53:33 -0700 Subject: [PATCH 1/3] skills: add MIT-derived engineering-process pack (decision-map, prototype, architecture-review) v4.7.0 Port three gap-filling skills from mattpocock/skills @2ab95809 with adaptations: tracker feature-detection + write gate (decision-map), worktree isolation + production-safe gating (prototype), inlined deep-module vocabulary + self-contained report (architecture-review). Derived portions remain MIT; SPDX declares the three members MIT; provenance manifest at docs/third-party-skill-provenance.md; NOTICE and both README license boundaries updated with pinned expectations. Co-Authored-By: Claude Fable 5 --- .claude-plugin/marketplace.base.json | 2 +- .claude-plugin/marketplace.json | 4 +- NOTICE | 6 + README.md | 29 +++- ...03-engineering-process-skill-pack-4.7.0.md | 23 +++ docs/third-party-skill-provenance.md | 44 ++++++ .../agent-collab/.claude-plugin/plugin.json | 2 +- .../agent-collab/.codex-plugin/plugin.json | 2 +- plugins/agent-collab/NOTICE | 6 + plugins/agent-collab/README.md | 24 ++- .../skills/agent-readiness/SKILL.md | 2 +- .../skills/agent-runtime-status/SKILL.md | 2 +- .../skills/ai-writing-auditor/SKILL.md | 2 +- .../agent-collab/skills/architect/SKILL.md | 2 +- .../skills/architecture-review/SKILL.md | 125 +++++++++++++++ .../skills/autonomy-readiness/SKILL.md | 2 +- .../agent-collab/skills/brainstorm/SKILL.md | 2 +- .../skills/chain-configurator/SKILL.md | 2 +- plugins/agent-collab/skills/chain/SKILL.md | 2 +- .../agent-collab/skills/code-review/SKILL.md | 2 +- .../skills/compose-skills/SKILL.md | 2 +- .../skills/data-engineer/SKILL.md | 2 +- plugins/agent-collab/skills/debate/SKILL.md | 2 +- .../agent-collab/skills/decision-map/SKILL.md | 145 ++++++++++++++++++ plugins/agent-collab/skills/delegate/SKILL.md | 2 +- .../agent-collab/skills/dev-delegate/SKILL.md | 2 +- .../skills/elixir-engineer/SKILL.md | 2 +- .../skills/eval-engineer/SKILL.md | 2 +- .../agent-collab/skills/go-engineer/SKILL.md | 2 +- .../skills/governance-review/SKILL.md | 2 +- .../hallucination-investigator/SKILL.md | 2 +- .../skills/incident-responder/SKILL.md | 2 +- .../agent-collab/skills/intent-check/SKILL.md | 2 +- .../skills/knowledge-compile/SKILL.md | 2 +- .../skills/kubernetes-specialist/SKILL.md | 2 +- .../skills/llm-architect/SKILL.md | 2 +- .../agent-collab/skills/logic-check/SKILL.md | 2 +- .../agent-collab/skills/long-context/SKILL.md | 2 +- .../skills/merge-resolve/SKILL.md | 2 +- .../skills/migration-doctor/SKILL.md | 2 +- .../skills/mlops-engineer/SKILL.md | 2 +- .../agent-collab/skills/orchestrate/SKILL.md | 2 +- .../skills/postgres-engineer/SKILL.md | 2 +- .../skills/prompt-regression-tester/SKILL.md | 2 +- .../agent-collab/skills/prototype/SKILL.md | 119 ++++++++++++++ .../agent-collab/skills/qa-verify/SKILL.md | 2 +- plugins/agent-collab/skills/red-team/SKILL.md | 2 +- plugins/agent-collab/skills/route/SKILL.md | 2 +- .../skills/rust-engineer/SKILL.md | 2 +- .../skills/second-opinion/SKILL.md | 2 +- .../skills/simulate-user/SKILL.md | 2 +- .../agent-collab/skills/sql-engineer/SKILL.md | 2 +- .../agent-collab/skills/sre-engineer/SKILL.md | 2 +- .../skills/start-inbox-monitor/SKILL.md | 2 +- plugins/agent-collab/skills/teamwork/SKILL.md | 2 +- .../skills/terraform-engineer/SKILL.md | 2 +- .../agent-collab/skills/ui-to-code/SKILL.md | 2 +- .../skills/untrusted-audit/SKILL.md | 2 +- .../skills/visual-review/SKILL.md | 2 +- plugins/agent-collab/skills/worker/SKILL.md | 2 +- scripts/build_release_evidence.py | 8 + scripts/check_release_consistency.py | 7 + scripts/skill-build-config.json | 2 +- skill-specs/architecture-review.md | 125 +++++++++++++++ skill-specs/decision-map.md | 145 ++++++++++++++++++ skill-specs/prototype.md | 119 ++++++++++++++ tests/test_public_distribution_contract.py | 10 +- tests/test_release_evidence.py | 12 ++ 68 files changed, 995 insertions(+), 58 deletions(-) create mode 100644 changelog.d/2026-08-03-engineering-process-skill-pack-4.7.0.md create mode 100644 docs/third-party-skill-provenance.md create mode 100644 plugins/agent-collab/skills/architecture-review/SKILL.md create mode 100644 plugins/agent-collab/skills/decision-map/SKILL.md create mode 100644 plugins/agent-collab/skills/prototype/SKILL.md create mode 100644 skill-specs/architecture-review.md create mode 100644 skill-specs/decision-map.md create mode 100644 skill-specs/prototype.md diff --git a/.claude-plugin/marketplace.base.json b/.claude-plugin/marketplace.base.json index 6a67dc0..65798b6 100644 --- a/.claude-plugin/marketplace.base.json +++ b/.claude-plugin/marketplace.base.json @@ -9,7 +9,7 @@ "plugins": [], "metadata": { "description": "Agent collaboration plugin marketplace", - "version": "4.6.0", + "version": "4.7.0", "repository": "https://github.com/sumitake/agent-collab" } } diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0a34ac3..f9d109d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,7 +10,7 @@ { "name": "agent-collab", "description": "Unified dynamic-host collaboration package. Centralized skills and async coordination work without legacy packages; every model-execution route requires the verified signed plugin artifact.", - "version": "4.6.0", + "version": "4.7.0", "author": { "name": "John Osumi" }, @@ -32,7 +32,7 @@ ], "metadata": { "description": "Agent collaboration plugin marketplace", - "version": "4.6.0", + "version": "4.7.0", "repository": "https://github.com/sumitake/agent-collab" } } diff --git a/NOTICE b/NOTICE index c6fc733..6ed417a 100644 --- a/NOTICE +++ b/NOTICE @@ -1,2 +1,8 @@ Copyright (c) 2026 John Osumi. All rights reserved except as expressly granted. Commercial licensing is administered by Osumi Consulting LLC. + +The decision-map, prototype, and architecture-review skills contain material +derived from the MIT-licensed mattpocock/skills repository +(Copyright (c) 2026 Matt Pocock). Those portions remain MIT-licensed; see +docs/third-party-skill-provenance.md for the pinned upstream commit and +per-file provenance, and each derived SKILL.md for the full MIT notice. diff --git a/README.md b/README.md index 7f36ca9..96c3215 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ trust: primary's identity, model, and session dynamically — no per-host forks to drift out of sync. -This public repository distributes that one package, **agent-collab** (v4.6.0), and is +This public repository distributes that one package, **agent-collab** (v4.7.0), and is the source of truth for the coordinator policy, skills, migration tooling, the fail-closed runtime client, contribution governance, and release-safety checks. The signed and notarized darwin-arm64 native runtime is committed in this @@ -129,7 +129,24 @@ Contributors need no access to the private build/sign system. See | Package | Version | Role | |---|---:|---| -| `agent-collab` | 4.6.0 | Unified skills, dynamic host policy, migration preflight, and verified native-runtime client | +| `agent-collab` | 4.7.0 | Unified skills, dynamic host policy, migration preflight, and verified native-runtime client | + +## What's new - v4.7.0 + +- **Engineering-process skill pack (MIT-derived).** Three self-executed skills + join the package: `decision-map` (multi-session planning as a shared map of + decision tickets on the issue tracker, with an explicit user-approval gate + before any tracker write), `prototype` (throwaway logic/UI prototypes that + answer one design question, isolated from the caller's branch), and + `architecture-review` (a codebase sweep for module-deepening opportunities + with a self-contained visual report, composing with the routed `architect` + consultation). They are derived from the MIT-licensed + [mattpocock/skills](https://github.com/mattpocock/skills) repository at + pinned commit `2ab95809` and adapted for this package; the derived portions + remain MIT-licensed, each generated `SKILL.md` carries the full MIT notice, + release SPDX evidence declares those members `MIT`, and + `docs/third-party-skill-provenance.md` records per-file provenance. No + coordinator, provider, or routing surface is touched. ## What's new - v4.6.0 @@ -801,3 +818,11 @@ material, and their incorporated components under their own terms. The exact, digest-pinned inventory is shipped as `THIRD-PARTY-NOTICES.txt` and `third-party-licenses/` inside the plugin package. Those files are excluded from policy-only archives because no native runtime is present. + +The `decision-map`, `prototype`, and `architecture-review` skills contain +material derived from the MIT-licensed +[mattpocock/skills](https://github.com/mattpocock/skills) repository +(Copyright (c) 2026 Matt Pocock). Those portions are and remain MIT-licensed +in every archive; each derived `SKILL.md` carries the full MIT permission +notice, and [docs/third-party-skill-provenance.md](docs/third-party-skill-provenance.md) +records the pinned upstream commit and per-file provenance. diff --git a/changelog.d/2026-08-03-engineering-process-skill-pack-4.7.0.md b/changelog.d/2026-08-03-engineering-process-skill-pack-4.7.0.md new file mode 100644 index 0000000..72b9c75 --- /dev/null +++ b/changelog.d/2026-08-03-engineering-process-skill-pack-4.7.0.md @@ -0,0 +1,23 @@ +### Added + +- Stamp agent-collab 4.7.0: **engineering-process skill pack (MIT-derived)**. + Three self-executed skills join the package — `decision-map` (multi-session + planning as a shared map of decision tickets on the issue tracker, with an + explicit user-approval gate before any tracker write and a claim discipline + for concurrent sessions), `prototype` (throwaway logic/UI prototypes that + answer one design question, built on an isolated worktree/branch with a + production-safe gate on UI variant mechanisms), and `architecture-review` + (a self-executed sweep for module-deepening opportunities presented as a + fully self-contained visual report, composing with — not replacing — the + routed `architect` consultation). Derived from the MIT-licensed + [mattpocock/skills](https://github.com/mattpocock/skills) repository at + pinned commit `2ab958093e83e0ec752e6c1c5932da465bf23e0c` and adapted for + this package (tracker resolution with feature detection and a local-markdown + fallback, host-neutral sub-skill references, inlined companion references, + no CDN assets, mutation gates). The derived portions remain MIT-licensed: + each generated `SKILL.md` carries the full MIT permission notice, release + SPDX evidence declares those three members `MIT` + (`scripts/build_release_evidence.py`), and + `docs/third-party-skill-provenance.md` records the per-file upstream blob + SHAs and adaptations. `NOTICE` and both README license boundaries name the + exception. No coordinator, provider, routing, or runtime surface is touched. diff --git a/docs/third-party-skill-provenance.md b/docs/third-party-skill-provenance.md new file mode 100644 index 0000000..dcc7f47 --- /dev/null +++ b/docs/third-party-skill-provenance.md @@ -0,0 +1,44 @@ +# Third-party skill provenance — mattpocock/skills (MIT) + +Three skills in this package are derived from Matt Pocock's +[mattpocock/skills](https://github.com/mattpocock/skills) repository, +MIT-licensed (Copyright (c) 2026 Matt Pocock). The derived portions remain +MIT-licensed; the PolyForm Strict License 1.0.0 governs only the rest of this +package. Each derived generated skill carries the full MIT permission notice +in its own `SKILL.md` (§ Attribution and license), so the notice travels with +every archive — policy-only and activation — that ships the skills tree. + +Pinned upstream commit: `2ab958093e83e0ec752e6c1c5932da465bf23e0c` +Upstream license file: `LICENSE` (blob `f1dd2c09108dde1a5f56097cee8461b3ea834499`) + +## File map (local ← upstream @ 2ab9580) + +| Local (spec → generated) | Upstream path | Upstream blob SHA | +|---|---|---| +| `skill-specs/decision-map.md` → `plugins/agent-collab/skills/decision-map/SKILL.md` | `skills/engineering/wayfinder/SKILL.md` | `42e3644cc57e41a1b87482754f25b4d9462d4bbc` | +| `skill-specs/prototype.md` → `plugins/agent-collab/skills/prototype/SKILL.md` | `skills/engineering/prototype/SKILL.md` | `e75d5331ceffd9b2c5a9554c3db124d848afa054` | +| (same, inlined) | `skills/engineering/prototype/LOGIC.md` | `fe9a2c29f77b9b7182ad7fa4bd251f27e506b7d9` | +| (same, inlined) | `skills/engineering/prototype/UI.md` | `76c0f6012b016af04d6105fa696a9a0e29dfa53a` | +| `skill-specs/architecture-review.md` → `plugins/agent-collab/skills/architecture-review/SKILL.md` | `skills/engineering/improve-codebase-architecture/SKILL.md` | `b56969e92f0705d70700f908b8ec929a1edfa782` | +| (same, inlined vocabulary) | `skills/engineering/codebase-design/SKILL.md` | `16620c24528b737408e78d95dd6a0e01a98d3d63` | + +## Adaptations applied (this package is not a verbatim mirror) + +- `decision-map` (from `wayfinder`): renamed; tracker resolved at run time + (GitHub `gh` with feature detection → local markdown → project-documented + workflow) instead of a setup-skill config file; an explicit user-approval + write gate added before any tracker mutation; upstream sub-skill references + (`/grilling`, `/domain-modeling`, `/research`, `/setup-matt-pocock-skills`) + replaced with host-neutral equivalents. +- `prototype`: upstream `LOGIC.md`/`UI.md` companion files inlined (this + package's generated skill directories are `SKILL.md`-only); isolated + worktree/branch requirement and a production-safe gate on the whole UI + variant mechanism added; no auto-commit to the caller's branch. +- `architecture-review` (from `improve-codebase-architecture` + + `codebase-design`): renamed; deep-module vocabulary inlined; report changed + from CDN Tailwind/Mermaid to fully self-contained inline CSS/SVG; grilling + replaced with host-neutral interviewing; composition with this package's + routed `architect` consultation documented. + +Re-pin procedure: when refreshing from upstream, update the pinned commit and +every blob SHA above in the same change, and re-verify the adaptations list. diff --git a/plugins/agent-collab/.claude-plugin/plugin.json b/plugins/agent-collab/.claude-plugin/plugin.json index dc794c9..c100329 100644 --- a/plugins/agent-collab/.claude-plugin/plugin.json +++ b/plugins/agent-collab/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-collab", - "version": "4.6.0", + "version": "4.7.0", "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. The signed runtime artifact is intentionally absent until the private build/sign integration completes.", "author": { "name": "John Osumi" diff --git a/plugins/agent-collab/.codex-plugin/plugin.json b/plugins/agent-collab/.codex-plugin/plugin.json index 6af38f0..1b102ae 100644 --- a/plugins/agent-collab/.codex-plugin/plugin.json +++ b/plugins/agent-collab/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-collab", - "version": "4.6.0", + "version": "4.7.0", "description": "Unified dynamic-host collaboration package with centralized skills, migration preflight, and a verified plugin-relative native runtime boundary. The signed runtime artifact is intentionally absent until the private build/sign integration completes.", "author": { "name": "John Osumi" diff --git a/plugins/agent-collab/NOTICE b/plugins/agent-collab/NOTICE index c6fc733..6ed417a 100644 --- a/plugins/agent-collab/NOTICE +++ b/plugins/agent-collab/NOTICE @@ -1,2 +1,8 @@ Copyright (c) 2026 John Osumi. All rights reserved except as expressly granted. Commercial licensing is administered by Osumi Consulting LLC. + +The decision-map, prototype, and architecture-review skills contain material +derived from the MIT-licensed mattpocock/skills repository +(Copyright (c) 2026 Matt Pocock). Those portions remain MIT-licensed; see +docs/third-party-skill-provenance.md for the pinned upstream commit and +per-file provenance, and each derived SKILL.md for the full MIT notice. diff --git a/plugins/agent-collab/README.md b/plugins/agent-collab/README.md index a373dd0..837140e 100644 --- a/plugins/agent-collab/README.md +++ b/plugins/agent-collab/README.md @@ -7,7 +7,7 @@ verifiable compliance evidence, and operator final-say, delivered as one package for every supported host. This document is the package's technical reference; the repository README carries the purpose and governance narrative. -Current: **4.6.0** +Current: **4.7.0** It resolves `primary_id`, `primary_family`, `active_model`, `host_runtime`, and `session_identifier` from the current host or explicit configuration. On a @@ -54,6 +54,15 @@ Nuitka 4.1.3 runtime material, and incorporated dependencies. Those exact files are digest-pinned by the archive builder and remain outside policy-only archives, which contain none of the corresponding runtime components. +Exception to the PolyForm boundary: the `decision-map`, `prototype`, and +`architecture-review` skills contain material derived from the MIT-licensed +[mattpocock/skills](https://github.com/mattpocock/skills) repository +(Copyright (c) 2026 Matt Pocock). Those portions are and remain MIT-licensed; +each derived `SKILL.md` carries the full MIT permission notice, release SPDX +evidence declares those members `MIT`, and +[docs/third-party-skill-provenance.md](../../docs/third-party-skill-provenance.md) +records the pinned upstream commit, per-file blob SHAs, and adaptations. + ## Runtime and safe mode The package may contain a privately built signed native standalone bundle only @@ -69,7 +78,7 @@ one macOS `LC_BUILD_VERSION` with minimum macOS 14.0 instead of trusting those manifest labels. The broker transport and provider protocol are both version 2. The package carries both `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`; both -identify this same 4.6.0 package. +identify this same 4.7.0 package. Codex, Gemini, OpenCode, Grok, and Composer are broker-only contracts. Their sealed requests cross a mode-`0600`, digest-bound per-user launchd Unix socket; launchd starts the exact @@ -306,6 +315,7 @@ time; a listed skill does not imply that its native route is currently active. | Domain expertise - infrastructure and reliability (pack, v4.4.0) | `kubernetes-specialist`, `terraform-engineer`, `sre-engineer`, `incident-responder` | | Domain expertise - data and AI (pack, v4.4.0) | `mlops-engineer`, `llm-architect`, `postgres-engineer`, `data-engineer` | | Domain expertise - LLM evaluation and writing quality (pack, v4.4.0) | `eval-engineer`, `prompt-regression-tester`, `hallucination-investigator`, `ai-writing-auditor` | +| Engineering process (pack, v4.7.0; MIT-derived) | `decision-map`, `prototype`, `architecture-review` | The sixteen domain-expertise skills were authored for this repository. Their scope selection was informed by two MIT-licensed VoltAgent reference corpora, @@ -313,6 +323,16 @@ reviewed as untrusted input at pinned commits and fully re-authored (zero copied passages, verified by shingle comparison): awesome-claude-code-subagents (commit 947b44ca) and awesome-codex-subagents (commit 5605c9c1). +The three engineering-process skills are self-executed by the active primary +(no coordinator route) and are derived from the MIT-licensed +[mattpocock/skills](https://github.com/mattpocock/skills) repository at pinned +commit `2ab95809`, adapted for this package. Those portions remain +MIT-licensed; each derived `SKILL.md` carries the full MIT permission notice, +and the file-level provenance map is +[docs/third-party-skill-provenance.md](../../docs/third-party-skill-provenance.md). +`architecture-review` is the self-executed sweep; `architect` remains the +routed read-only consultation the sweep can hand its top candidates to. + `visual-review` and `ui-to-code` currently provide primary-only guidance because the managed protocol does not accept image attachments. They never reinterpret binary images as long-context text. Mutation-capable skills still require an diff --git a/plugins/agent-collab/skills/agent-readiness/SKILL.md b/plugins/agent-collab/skills/agent-readiness/SKILL.md index e62572c..df02564 100644 --- a/plugins/agent-collab/skills/agent-readiness/SKILL.md +++ b/plugins/agent-collab/skills/agent-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-readiness -version: 4.6.0 +version: 4.7.0 description: Evaluate whether an agent, model, CLI, plugin, or role is ready for a proposed responsibility. Use when the user says "agent readiness," "is this agent ready," "can Codex be primary," "can Grok handle this role," "promote this agent," "evaluate this worker," "review model readiness," or "/agent-collab:agent-readiness." Also offer this proactively before assigning a new primary, reviewer, worker, delegate, headless, release, or merge-related role to Claude, Codex, Antigravity/Gemini, Grok, or a future agent. --- diff --git a/plugins/agent-collab/skills/agent-runtime-status/SKILL.md b/plugins/agent-collab/skills/agent-runtime-status/SKILL.md index 7baf2ab..6e6eac7 100644 --- a/plugins/agent-collab/skills/agent-runtime-status/SKILL.md +++ b/plugins/agent-collab/skills/agent-runtime-status/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-runtime-status -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md b/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md index 81a6429..28686b1 100644 --- a/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md +++ b/plugins/agent-collab/skills/ai-writing-auditor/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-writing-auditor -version: 4.6.0 +version: 4.7.0 description: Audits prose for the tells of machine-generated writing and rewrites it to read as if a careful human wrote it, without softening the actual content. Use when the user says "de-AI this text", "audit this writing for AI patterns", "make this read human", or "/agent-collab:ai-writing-auditor." Also offer this proactively when a piece of customer-facing or published prose is dense with the stock phrasing and mechanical structure typical of unedited model output. --- diff --git a/plugins/agent-collab/skills/architect/SKILL.md b/plugins/agent-collab/skills/architect/SKILL.md index 5e0beb6..54f2f98 100644 --- a/plugins/agent-collab/skills/architect/SKILL.md +++ b/plugins/agent-collab/skills/architect/SKILL.md @@ -1,6 +1,6 @@ --- name: architect -version: 4.6.0 +version: 4.7.0 description: Request read-only architecture consultation for codebase analysis, system design, implementation planning, decomposition, or long-horizon coding strategy. Use when the user says "ask the architect," "have Grok design this," "architecture consultation," "plan this implementation," "decompose this build," "analyze the system design," or "/agent-collab:architect." Also offer this proactively before a substantial multi-system or long-horizon implementation where an independent architecture pass can reduce rework. This role never edits files, runs shell commands or tests, mutates a worktree, opens PRs, merges, or deploys. --- diff --git a/plugins/agent-collab/skills/architecture-review/SKILL.md b/plugins/agent-collab/skills/architecture-review/SKILL.md new file mode 100644 index 0000000..6d7d3cc --- /dev/null +++ b/plugins/agent-collab/skills/architecture-review/SKILL.md @@ -0,0 +1,125 @@ +--- +name: architecture-review +version: 4.7.0 +description: Self-executed sweep of a codebase for module-deepening opportunities — shallow interfaces, scattered locality, untestable seams — presented as a visual report the user picks a candidate from, then explored interactively. Unlike `architect` (routed consultation) and `code-review` (diff review), this skill is run by the active primary on the whole codebase. Use when the user says "architecture review," "find deepening opportunities," "where is this codebase getting muddy," "improve the architecture," or "/agent-collab:architecture-review." Also offer this proactively when repeated friction in a working session traces to shallow modules — bouncing between many files to follow one concept, or tests that cannot reach behavior through the current interfaces. +--- + +# Architecture review — find and explore deepening opportunities + +Surface architectural friction and propose **deepening opportunities** — +refactors that turn shallow modules into deep ones. The aim is testability and +navigability. This skill is **self-executed by the active primary**: it reads +the codebase directly and produces its own report. It composes with, and does +not replace, the routed skills: for an independent cross-family read on the top +candidates, route them through `architect` afterward. + +## Design vocabulary + +Use these terms exactly in every suggestion — do not drift into "component," +"service," "API," or "boundary": + +- **Module** — anything with an interface and an implementation; deliberately + scale-agnostic (a function, class, package, or tier-spanning slice). +- **Interface** — everything a caller must know to use the module correctly: + types, invariants, ordering constraints, error modes, configuration, + performance characteristics. +- **Implementation** — what is inside the module. +- **Depth** — leverage at the interface: how much behavior a caller or test can + exercise per unit of interface learned. **Deep** = small interface, large + behavior; **shallow** = interface nearly as complex as the implementation. +- **Seam** — a place where behavior can be altered without editing in that + place; where the interface lives. Placing the seam is its own decision. +- **Adapter** — a concrete thing satisfying an interface at a seam (a role, + not a substance). One adapter = hypothetical seam; two = real. +- **Leverage** — what callers get from depth: 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. Fix once, fixed everywhere. +- **Deletion test** — would deleting this module concentrate complexity behind + a real interface, or just move it? "Concentrates" marks a shallow module + worth deepening. + +## Process + +### 1. Explore — scope before you scan + +Deepening pays off by making future changes easier, so weight the parts of the +codebase that actually change. If the user named a direction — a module, a +subsystem, a pain point — take it. Otherwise walk the commit history +(`git log --oneline`) for hot spots and let those paths pull attention first; +widen the net only if changes are scattered. + +Read the project's domain glossary (`CONTEXT.md` or equivalent) and any +architecture decision records in the area first — use the project's own domain +vocabulary in every candidate, and do not re-litigate recorded decisions +unless the friction is real enough to warrant reopening one (then mark the +conflict explicitly in the candidate). + +Explore with the host's bounded read-only exploration facility (a read-only +subagent where available; direct reading otherwise). Note where you experience +friction rather than following rigid heuristics: where does understanding one +concept require bouncing between many small modules; where are modules +shallow; where were pure functions extracted for testability while the real +bugs hide in how they are called; which parts are untestable through their +current interface. Apply the deletion test to anything suspect. + +### 2. Present candidates as a visual report + +Write a **fully self-contained** HTML file to the OS temp directory — resolve +`$TMPDIR` falling back to `/tmp` (`%TEMP%` on Windows), name it +`architecture-review-.html` — and tell the user the absolute path +(open it with the platform opener where available). **Inline all CSS and +hand-drawn SVG; no CDN scripts, no external stylesheets, no remote fonts, no +third-party browser code.** The report must render identically offline. + +For each candidate render a card: **Files** involved; **Problem** (why the +current shape causes friction); **Solution** in plain language; **Benefits** +in terms of locality, leverage, and how tests improve; a **before/after +diagram** (inline SVG or styled divs) showing the shallowness and the +deepening; and a **recommendation strength** badge — `Strong`, +`Worth exploring`, or `Speculative`. End with a **Top recommendation** section +naming the candidate to tackle first and why. Do not propose concrete +interfaces yet. + +Then ask the user which candidate to explore. + +### 3. Explore the picked candidate interactively + +Walk the decision tree with the user one question at a time — constraints, +dependencies, the shape of the deepened module, what sits behind the seam, +which tests survive. Use the host's requirements-interview skill when one is +available; otherwise interview inline: look up facts in the codebase, put +every decision to the user, and do not begin implementation until the user +confirms the shared understanding. As decisions crystallize, keep the +project's domain glossary current (add or sharpen terms in `CONTEXT.md` where +the project keeps one), and when the user rejects a candidate for a +load-bearing reason, offer to record the decision so future reviews do not +re-suggest it. For an independent read on a high-stakes candidate, route it +through `architect` (read-only consultation) before committing. + +This skill produces analysis and an agreed direction — implementation happens +afterward through the normal change workflow, not inside the review. + +## Attribution and license + +Derived from `skills/engineering/improve-codebase-architecture/SKILL.md` and +`skills/engineering/codebase-design/SKILL.md` in +[mattpocock/skills](https://github.com/mattpocock/skills) at commit +`2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package (inlined +vocabulary, self-contained report assets, host-neutral interviewing, +composition with routed consultation). That material is and remains +MIT-licensed: 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/plugins/agent-collab/skills/autonomy-readiness/SKILL.md b/plugins/agent-collab/skills/autonomy-readiness/SKILL.md index e0387ff..d6627cc 100644 --- a/plugins/agent-collab/skills/autonomy-readiness/SKILL.md +++ b/plugins/agent-collab/skills/autonomy-readiness/SKILL.md @@ -1,6 +1,6 @@ --- name: autonomy-readiness -version: 4.6.0 +version: 4.7.0 description: Evaluate whether an autonomous, always-on, scheduled, headless, or self-evolving workflow is ready to run safely. Use when the user says "autonomy readiness," "activation gate review," "is this workflow ready to run autonomously," "go/no-go autonomy," "always-on readiness," "headless operation review," or "/agent-collab:autonomy-readiness." Also offer this proactively before enabling background agents, recurring automations, auto-merge/self-evolution, external actions, unattended host runs, or any workflow that can continue without a human watching. --- diff --git a/plugins/agent-collab/skills/brainstorm/SKILL.md b/plugins/agent-collab/skills/brainstorm/SKILL.md index 4bfb4ee..5d39751 100644 --- a/plugins/agent-collab/skills/brainstorm/SKILL.md +++ b/plugins/agent-collab/skills/brainstorm/SKILL.md @@ -1,6 +1,6 @@ --- name: brainstorm -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/chain-configurator/SKILL.md b/plugins/agent-collab/skills/chain-configurator/SKILL.md index 4cc487a..37e9ff5 100644 --- a/plugins/agent-collab/skills/chain-configurator/SKILL.md +++ b/plugins/agent-collab/skills/chain-configurator/SKILL.md @@ -1,6 +1,6 @@ --- name: chain-configurator -version: 4.6.0 +version: 4.7.0 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/chain/SKILL.md b/plugins/agent-collab/skills/chain/SKILL.md index d468f48..f21ed4c 100644 --- a/plugins/agent-collab/skills/chain/SKILL.md +++ b/plugins/agent-collab/skills/chain/SKILL.md @@ -1,6 +1,6 @@ --- name: chain -version: 4.6.0 +version: 4.7.0 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/code-review/SKILL.md b/plugins/agent-collab/skills/code-review/SKILL.md index b0839e2..1c03940 100644 --- a/plugins/agent-collab/skills/code-review/SKILL.md +++ b/plugins/agent-collab/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/compose-skills/SKILL.md b/plugins/agent-collab/skills/compose-skills/SKILL.md index 36e0c6d..53b7c28 100644 --- a/plugins/agent-collab/skills/compose-skills/SKILL.md +++ b/plugins/agent-collab/skills/compose-skills/SKILL.md @@ -1,6 +1,6 @@ --- name: compose-skills -version: 4.6.0 +version: 4.7.0 description: Select a bounded, token-aware combination of collaboration skills or task lenses before execution. Use when the user says "compose skills," "which skills should I use," "use skill composition," "select a recipe," "combine these skills," or "/agent-collab:compose-skills." Also offer this proactively when a task plausibly needs multiple lenses, reviewers, or agents and would benefit from progressive disclosure, explicit fan-out limits, and a smallest-useful-skill plan before routing or loading full skill bodies. --- diff --git a/plugins/agent-collab/skills/data-engineer/SKILL.md b/plugins/agent-collab/skills/data-engineer/SKILL.md index de49da7..be7082a 100644 --- a/plugins/agent-collab/skills/data-engineer/SKILL.md +++ b/plugins/agent-collab/skills/data-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: data-engineer -version: 4.6.0 +version: 4.7.0 description: Builds and hardens the pipelines and warehouse structures that move data from source systems to the people and systems that consume it. Use when the user says "build the ETL pipeline", "design the dbt models", "orchestrate this pipeline", or "design the warehouse schema", or "/agent-collab:data-engineer." Also offer this proactively when a pipeline lacks idempotency, has no data-quality checks, or moves data through undocumented schema contracts. --- diff --git a/plugins/agent-collab/skills/debate/SKILL.md b/plugins/agent-collab/skills/debate/SKILL.md index 4272cd8..32a89d7 100644 --- a/plugins/agent-collab/skills/debate/SKILL.md +++ b/plugins/agent-collab/skills/debate/SKILL.md @@ -1,6 +1,6 @@ --- name: debate -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/decision-map/SKILL.md b/plugins/agent-collab/skills/decision-map/SKILL.md new file mode 100644 index 0000000..f80e5c5 --- /dev/null +++ b/plugins/agent-collab/skills/decision-map/SKILL.md @@ -0,0 +1,145 @@ +--- +name: decision-map +version: 4.7.0 +description: Plan an effort too large for one session as a shared map of decision tickets on the repo's issue tracker, then resolve them one per session until the way to the destination is clear. Use when the user says "decision map," "chart this effort," "map out this project," "break this fog into tickets," "work the map," or "/agent-collab:decision-map." Also offer this proactively when a request is a loose multi-session idea whose route is not yet visible — where the open questions outnumber the known steps and a single planning pass would either stall or guess. +--- + +# Decision map — multi-session planning on the issue tracker + +A loose idea has arrived — too big for one session, and wrapped in fog: the way +from here to the **destination** is not visible yet. This skill charts the way +as a **shared map** on the repo's issue tracker, then works its **decision +tickets** — questions whose resolution is a decision, not slices of a build to +execute — one at a time until the route is clear. + +The destination varies per effort, and naming it is the first act of charting. +It might be a spec to hand off, a decision to lock before implementation +planning starts, or a change made in place. The map is domain-agnostic. + +## Plan, don't do + +Each ticket resolves a decision; the map is done when nothing is left to decide +before someone goes and does the thing. The pull to just do the work is usually +the signal you have reached the edge of the map and it is time to hand off. An +effort can override this in its Notes — carrying execution into the map — but +absent that, produce decisions, not deliverables. + +## Refer by name + +Every map and ticket is an issue, so it has a name — its title. In everything +the human reads, refer to it by that name, never by a bare id or number; the id +and URL ride inside the name as a link, never stand in for it. + +## Tracker resolution and the write gate + +Resolve the tracker in this order; never assume one: + +1. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote. + Feature-detect sub-issue and dependency support (`gh issue create --parent`, + `gh issue edit --blocked-by`) before relying on it; on older CLI versions + fall back to a `Blocked by: #N` body convention and a task-list of child + links in the map body. +2. **Local markdown** when there is no usable remote tracker: the map at + `.scratch//map.md`, tickets as sibling files, blocking edges as + body text. +3. **Whatever the project's own docs designate**, when they document a + different tracker workflow — follow that documentation. + +**Write gate:** tracker issues are shared, outward-facing state. Before +creating, editing, assigning, commenting on, or closing any tracker item, +present the exact set of writes (titles, bodies, edges) and get the user's +confirmation — unless the user in this conversation already explicitly asked to +publish or update the map. Local-markdown mode needs no confirmation. + +## The map + +The map is one issue labelled `decision-map:map`; its tickets are child issues. +The map is an **index**, not a store: it gists each closed decision in one line +and links the ticket that holds the detail. Open tickets are not listed — they +are found by query. The map body carries four sections: + +- **Destination** — what reaching the end looks like, one or two lines; every + session orients to it before choosing a ticket. +- **Notes** — domain, skills every session should consult, standing preferences. +- **Decisions so far** — one line per closed ticket: `[title](link) — gist`. +- **Not yet specified** and **Out of scope** — see below. + +Each ticket's body is one question, sized to a single session. A session +**claims** a ticket by assigning it before any work — the assignee is the +claim. A ticket is unblocked when every ticket blocking it is closed; the +**frontier** is the open, unblocked, unclaimed children. + +## Ticket types + +Every ticket is either **HITL** — worked with a human who speaks for +themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves +through that live exchange; the agent never stands in for the human's side. + +- **Research** (AFK): read documentation, third-party APIs, or local knowledge + bases to surface a fact a decision waits on. Delegate to a bounded read-only + research subagent when the host provides one; otherwise research inline. + Capture findings as a cited markdown note linked from the ticket. +- **Prototype** (HITL): raise the fidelity of the discussion with a cheap + concrete artifact to react to — via the `prototype` skill in this package + where code is called for. Link the artifact from the ticket. +- **Interview** (HITL): the default. Work the question with the user one + question at a time, resolving dependent decisions in order. Use the host's + requirements-interview or brainstorming skill when one is available; + otherwise interview inline. Either way: look up **facts** in the environment + rather than asking, put every **decision** to the human and wait, and do not + act on the outcome until the user confirms shared understanding. +- **Task** (HITL or AFK): manual work that must happen before a decision can be + made — provisioning access, moving data so its shape can be seen. It earns + its place by unblocking a decision, not by delivering the destination. + +## Fog of war and out of scope + +Do not chart what you cannot yet see. **Not yet specified** holds the dim view +of questions you can tell are coming but cannot yet phrase sharply; resolving +tickets graduates patches of it into fresh tickets. The test for fog vs. +ticket is whether the question can be stated precisely now — not whether it can +be answered now. **Out of scope** holds work consciously ruled beyond the +destination; it never graduates. When an existing ticket turns out to sit past +the destination, close it and leave one line here with the reason. + +## Invocation + +Two modes. Either way, resolve at most one non-research ticket per session. + +**Chart the map** (user arrives with a loose idea): (1) pin the destination via +an interview; (2) interview again breadth-first to surface the open decisions — +if no fog surfaces, the effort fits one session and needs no map: say so and +stop; (3) draft the map and the tickets you can specify now; (4) pass the write +gate, then create the map and tickets, wiring blocking edges in a second pass; +(5) kick off research tickets; (6) stop — charting is one session's work. + +**Work the map** (user arrives with a map reference): (1) load the map body +only; (2) take the named ticket, or the first frontier ticket — claim it +first; (3) resolve it, zooming into related tickets on demand; (4) record the +answer as a resolution comment, close the ticket, append the one-line gist to +Decisions so far; (5) graduate any fog the answer sharpened, and rule anything +the answer exposed as beyond the destination out of scope. Expect concurrent +sessions to be editing the tracker; the claim discipline is what keeps them +from colliding. + +## Attribution and license + +Derived from `skills/engineering/wayfinder/SKILL.md` in +[mattpocock/skills](https://github.com/mattpocock/skills) at commit +`2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package +(tracker resolution, write gate, host-neutral sub-skill references). That +material is and remains MIT-licensed: 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/plugins/agent-collab/skills/delegate/SKILL.md b/plugins/agent-collab/skills/delegate/SKILL.md index 36e47f3..c1e9e90 100644 --- a/plugins/agent-collab/skills/delegate/SKILL.md +++ b/plugins/agent-collab/skills/delegate/SKILL.md @@ -1,6 +1,6 @@ --- name: delegate -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/dev-delegate/SKILL.md b/plugins/agent-collab/skills/dev-delegate/SKILL.md index 4d00161..a7e26a5 100644 --- a/plugins/agent-collab/skills/dev-delegate/SKILL.md +++ b/plugins/agent-collab/skills/dev-delegate/SKILL.md @@ -1,6 +1,6 @@ --- name: dev-delegate -version: 4.6.0 +version: 4.7.0 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/elixir-engineer/SKILL.md b/plugins/agent-collab/skills/elixir-engineer/SKILL.md index e1217bd..78bcd91 100644 --- a/plugins/agent-collab/skills/elixir-engineer/SKILL.md +++ b/plugins/agent-collab/skills/elixir-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: elixir-engineer -version: 4.6.0 +version: 4.7.0 description: Senior Elixir and OTP engineer for fault-tolerant, concurrent, and Phoenix-based systems. Use when the user says "review this supervision tree", "why did this GenServer crash", "help me design this OTP process architecture", or "/agent-collab:elixir-engineer." Also offer this proactively when a change adds a new process, alters a restart strategy, or touches a Phoenix channel or LiveView boundary. --- diff --git a/plugins/agent-collab/skills/eval-engineer/SKILL.md b/plugins/agent-collab/skills/eval-engineer/SKILL.md index 8169dbf..ca543e8 100644 --- a/plugins/agent-collab/skills/eval-engineer/SKILL.md +++ b/plugins/agent-collab/skills/eval-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: eval-engineer -version: 4.6.0 +version: 4.7.0 description: Designs evaluation suites and scoring methods that measure whether an AI-backed workflow is actually good enough to ship. Use when the user says "design evals for this", "build an eval suite", "how should we measure this workflow", or "/agent-collab:eval-engineer." Also offer this proactively when a project ships a prompt, retrieval pipeline, or agent workflow with no structured way to tell whether a change made it better or worse. --- diff --git a/plugins/agent-collab/skills/go-engineer/SKILL.md b/plugins/agent-collab/skills/go-engineer/SKILL.md index 426fc83..62e493a 100644 --- a/plugins/agent-collab/skills/go-engineer/SKILL.md +++ b/plugins/agent-collab/skills/go-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: go-engineer -version: 4.6.0 +version: 4.7.0 description: Senior Go engineer for concurrent, service-oriented, and cloud-native code. Use when the user says "review this Go service for concurrency bugs", "help me design this Go interface", "why is this goroutine leaking", or "/agent-collab:go-engineer." Also offer this proactively when a change adds a goroutine, channel, or context-cancellation path without an obvious termination guarantee. --- diff --git a/plugins/agent-collab/skills/governance-review/SKILL.md b/plugins/agent-collab/skills/governance-review/SKILL.md index ae43cdd..dc1fa48 100644 --- a/plugins/agent-collab/skills/governance-review/SKILL.md +++ b/plugins/agent-collab/skills/governance-review/SKILL.md @@ -1,6 +1,6 @@ --- name: governance-review -version: 4.6.0 +version: 4.7.0 description: Use when the operator says "governance review," "high-stakes review," "tiebreaker," or "second opinion." Also offer this proactively when reviewer-family independence must be enforced. --- diff --git a/plugins/agent-collab/skills/hallucination-investigator/SKILL.md b/plugins/agent-collab/skills/hallucination-investigator/SKILL.md index b74279d..e61589b 100644 --- a/plugins/agent-collab/skills/hallucination-investigator/SKILL.md +++ b/plugins/agent-collab/skills/hallucination-investigator/SKILL.md @@ -1,6 +1,6 @@ --- name: hallucination-investigator -version: 4.6.0 +version: 4.7.0 description: Traces a specific wrong or fabricated AI output back to its root cause in context, retrieval, prompting, or tool use, and recommends the most targeted fix. Use when the user says "why is it hallucinating", "investigate this fabrication", "trace this wrong answer", or "/agent-collab:hallucination-investigator." Also offer this proactively when a factuality failure has been reported but no one has yet reconstructed why the system produced that specific wrong answer. --- diff --git a/plugins/agent-collab/skills/incident-responder/SKILL.md b/plugins/agent-collab/skills/incident-responder/SKILL.md index bd4c21b..8463b32 100644 --- a/plugins/agent-collab/skills/incident-responder/SKILL.md +++ b/plugins/agent-collab/skills/incident-responder/SKILL.md @@ -1,6 +1,6 @@ --- name: incident-responder -version: 4.6.0 +version: 4.7.0 description: Leads live incident response — triage, containment, evidence-driven root-cause analysis, and postmortem writeups for active outages or breaches. Use when the user says "we have an incident", "production is down", or "run the postmortem for this outage", or "/agent-collab:incident-responder." Also offer this proactively when the user is trying to write the incident timeline or communicate status while a service disruption is still unresolved. --- diff --git a/plugins/agent-collab/skills/intent-check/SKILL.md b/plugins/agent-collab/skills/intent-check/SKILL.md index d85666c..cec3d21 100644 --- a/plugins/agent-collab/skills/intent-check/SKILL.md +++ b/plugins/agent-collab/skills/intent-check/SKILL.md @@ -1,6 +1,6 @@ --- name: intent-check -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/knowledge-compile/SKILL.md b/plugins/agent-collab/skills/knowledge-compile/SKILL.md index b9300d3..8a5c7c4 100644 --- a/plugins/agent-collab/skills/knowledge-compile/SKILL.md +++ b/plugins/agent-collab/skills/knowledge-compile/SKILL.md @@ -1,6 +1,6 @@ --- name: knowledge-compile -version: 4.6.0 +version: 4.7.0 description: Compile multiple sources into a durable, cited knowledge dossier without mixing claims, assumptions, and decisions. Use when the user says "compile knowledge," "build a dossier," "create a knowledge base," "synthesize these sources," "preserve research context," "make this reviewable later," or "/agent-collab:knowledge-compile." Also offer this proactively when a task spans several repos, PRs, papers, articles, logs, agent messages, or drafts and future agents need source-separated context for independent review. --- diff --git a/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md b/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md index 9fd3338..2bf39ba 100644 --- a/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md +++ b/plugins/agent-collab/skills/kubernetes-specialist/SKILL.md @@ -1,6 +1,6 @@ --- name: kubernetes-specialist -version: 4.6.0 +version: 4.7.0 description: Designs, hardens, and troubleshoots Kubernetes clusters and the workloads running on them. Use when the user says "review this Kubernetes manifest", "why is my pod crash-looping", or "help me design a multi-tenant cluster", or "/agent-collab:kubernetes-specialist." Also offer this proactively when a change touches Deployment/StatefulSet/DaemonSet specs, RBAC bindings, network policies, or persistent volume claims. --- diff --git a/plugins/agent-collab/skills/llm-architect/SKILL.md b/plugins/agent-collab/skills/llm-architect/SKILL.md index 7213993..b2ef53a 100644 --- a/plugins/agent-collab/skills/llm-architect/SKILL.md +++ b/plugins/agent-collab/skills/llm-architect/SKILL.md @@ -1,6 +1,6 @@ --- name: llm-architect -version: 4.6.0 +version: 4.7.0 description: Designs the structural shape of an LLM-powered system — how context is assembled, how tools and retrieval are wired in, and how output flows to the caller. Use when the user says "design the RAG pipeline", "plan the agent architecture", or "help me structure the prompt pipeline", or "/agent-collab:llm-architect." Also offer this proactively when a project is wiring multiple prompts, tools, and retrieval steps together without a clear contract between them. --- diff --git a/plugins/agent-collab/skills/logic-check/SKILL.md b/plugins/agent-collab/skills/logic-check/SKILL.md index 028f6ba..0ccf8d4 100644 --- a/plugins/agent-collab/skills/logic-check/SKILL.md +++ b/plugins/agent-collab/skills/logic-check/SKILL.md @@ -1,6 +1,6 @@ --- name: logic-check -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: xhigh diff --git a/plugins/agent-collab/skills/long-context/SKILL.md b/plugins/agent-collab/skills/long-context/SKILL.md index 4cdef8c..e303567 100644 --- a/plugins/agent-collab/skills/long-context/SKILL.md +++ b/plugins/agent-collab/skills/long-context/SKILL.md @@ -1,6 +1,6 @@ --- name: long-context -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/merge-resolve/SKILL.md b/plugins/agent-collab/skills/merge-resolve/SKILL.md index 0eff10b..67c55ba 100644 --- a/plugins/agent-collab/skills/merge-resolve/SKILL.md +++ b/plugins/agent-collab/skills/merge-resolve/SKILL.md @@ -1,6 +1,6 @@ --- name: merge-resolve -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/migration-doctor/SKILL.md b/plugins/agent-collab/skills/migration-doctor/SKILL.md index 0aecbb6..e6d9d65 100644 --- a/plugins/agent-collab/skills/migration-doctor/SKILL.md +++ b/plugins/agent-collab/skills/migration-doctor/SKILL.md @@ -1,6 +1,6 @@ --- name: migration-doctor -version: 4.6.0 +version: 4.7.0 description: Use when the user says "migration doctor," "check old collaboration plugins," "verify agent-collab migration," or "/agent-collab:migration-doctor." Also offer this proactively after installing or updating agent-collab, when provider routing is blocked, or when a retired package may still be selected from an installed plugin or cache. --- diff --git a/plugins/agent-collab/skills/mlops-engineer/SKILL.md b/plugins/agent-collab/skills/mlops-engineer/SKILL.md index ba7a4a1..cc8d5c0 100644 --- a/plugins/agent-collab/skills/mlops-engineer/SKILL.md +++ b/plugins/agent-collab/skills/mlops-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: mlops-engineer -version: 4.6.0 +version: 4.7.0 description: Designs and hardens the infrastructure that carries models from training through production serving. Use when the user says "set up a model registry", "build the training pipeline", "deploy this model to production", or "/agent-collab:mlops-engineer." Also offer this proactively when a project trains or serves models but has no versioned artifacts, no promotion gate, or no monitoring for prediction quality. --- diff --git a/plugins/agent-collab/skills/orchestrate/SKILL.md b/plugins/agent-collab/skills/orchestrate/SKILL.md index 072b9a8..142b243 100644 --- a/plugins/agent-collab/skills/orchestrate/SKILL.md +++ b/plugins/agent-collab/skills/orchestrate/SKILL.md @@ -1,6 +1,6 @@ --- name: orchestrate -version: 4.6.0 +version: 4.7.0 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/postgres-engineer/SKILL.md b/plugins/agent-collab/skills/postgres-engineer/SKILL.md index 1017dff..176da7d 100644 --- a/plugins/agent-collab/skills/postgres-engineer/SKILL.md +++ b/plugins/agent-collab/skills/postgres-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: postgres-engineer -version: 4.6.0 +version: 4.7.0 description: Administers and hardens PostgreSQL at the engine level — configuration, replication, vacuum behavior, and locking under real workloads. Use when the user says "tune postgres for this workload", "design a vacuum strategy", "set up replication", or "fix our connection pooling", or "/agent-collab:postgres-engineer." Also offer this proactively when a PostgreSQL deployment shows replication lag, bloat, connection exhaustion, or a failover plan that has never been tested. --- diff --git a/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md b/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md index 7961aa7..2216da4 100644 --- a/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md +++ b/plugins/agent-collab/skills/prompt-regression-tester/SKILL.md @@ -1,6 +1,6 @@ --- name: prompt-regression-tester -version: 4.6.0 +version: 4.7.0 description: Builds and runs comparison suites that catch behavioral drift when a prompt, model, or workflow configuration changes. Use when the user says "did the prompt change regress anything", "compare these prompt versions", "regression-test this prompt change", or "/agent-collab:prompt-regression-tester." Also offer this proactively when someone is about to swap a prompt, model, or tool wiring in a live workflow without a way to check whether existing behavior held. --- diff --git a/plugins/agent-collab/skills/prototype/SKILL.md b/plugins/agent-collab/skills/prototype/SKILL.md new file mode 100644 index 0000000..c423b09 --- /dev/null +++ b/plugins/agent-collab/skills/prototype/SKILL.md @@ -0,0 +1,119 @@ +--- +name: prototype +version: 4.7.0 +description: Build a throwaway prototype that answers one design question — an interactive terminal app to pressure-test a state model or logic shape, or several radically different UI variants on one route. Use when the user says "prototype this," "sanity-check this state model," "show me a few options for this page," "mock up some variations," or "/agent-collab:prototype." Also offer this proactively when a design conversation is circling a question that a runnable artifact would settle in minutes — how a state machine handles an awkward case, or which of several layouts actually works with real data. +--- + +# Prototype — throwaway code that answers a question + +A prototype is **throwaway code that answers a question**. The question decides +the shape: + +- **"Does this logic or state model feel right?"** → 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?"** → several radically different UI variants + on a single route, switchable in the browser. + +Getting the branch wrong wastes the whole prototype. If the question is +ambiguous and the user is not reachable, default to whichever branch better +matches the surrounding code — a backend module suggests logic, a page or +component suggests UI — and state the assumption at the top of the prototype. + +## Rules that apply to both branches + +1. **Isolate the prototype from the caller's work.** Build it on an isolated + worktree or a clearly named throwaway branch. Never commit to, rebase, or + otherwise alter the branch the user was on without their explicit approval. +2. **Throwaway from day one, and clearly marked as such.** Name files and + routes so a casual reader sees "prototype," and follow the project's + existing conventions rather than inventing new top-level structure. +3. **One command to run**, registered with the project's existing task runner + (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`); if there + is none, put the command at the top of the prototype's README. +4. **No persistence by default.** State lives in memory; persistence is the + thing a prototype checks, not something it depends on. If the question + explicitly involves a database, use a scratch store with a clear + "PROTOTYPE — wipe me" name. +5. **Skip the polish.** No tests, no error handling beyond runnability, no + abstractions. The point is to learn something fast. +6. **Surface the state.** After every action (logic) or on every variant switch + (UI), show the full relevant state so the user sees what changed. +7. **Capture it when done.** Fold the validated decision into the real code; + keep the prototype itself as a primary source on its throwaway branch with a + context pointer from the relevant issue or commit. The main branch keeps + only the validated decision. + +## Logic branch — interactive terminal app + +State the question first — one paragraph at the top of the file or README; a +logic prototype that answers the wrong question is pure waste. Then: + +1. **Use the host project's language and tooling.** No new runtimes or package + managers for a prototype. +2. **Isolate the logic behind a small pure interface** that could be lifted + into the real codebase later — a pure reducer `(state, action) → state`, an + explicit state machine when "which actions are legal right now" is part of + the question, a set of pure functions over a plain data type, or a module + with a clear method surface when the logic genuinely owns ongoing state. + Pick the shape that fits the question, not the one easiest to wire to a + terminal. No I/O or terminal code inside the logic module. +3. **Wrap it in the smallest terminal shell that exposes the state**: on every + action, clear the screen and re-render one stable frame — current state + pretty-printed, then the keyboard shortcuts (`[a] add [t] tick [q] quit`). + Read one keystroke, dispatch, re-render, loop until quit. +4. **Hand the run command to the user.** The interesting moments are "wait, + that shouldn't be possible" — bugs in the idea, which is the point. Add + actions as they ask. +5. **On resolution**, the validated logic module lifts into the real code; the + terminal shell rides along to the throwaway branch as a primary source. + +Anti-patterns: adding tests; wiring to the real database; generalizing for +futures the question does not ask about; blurring logic and shell so the +module is no longer portable; shipping the shell toward production. + +## UI branch — radically different variants on one route + +Default to **3 variants**; more than 5 is noise. Two sub-shapes; strongly +prefer the first: + +- **Adjustment to an existing page** (preferred): render variants on the + existing route, gated by a `?variant=` URL parameter — the page's real data, + auth, and surroundings stay, only the rendering swaps. A new section that + would naturally live inside an existing page is still this sub-shape. +- **A new page** (last resort): only when the surface genuinely has no home. + Follow the project's routing conventions and name the route so it is + obviously a prototype. + +Variants must be **structurally different** — different layout, information +hierarchy, primary affordance — not different colors. If two drafts come out +similar, redo one with explicit counter-guidance. Use the project's existing +component and styling system. A floating bottom bar switches variants. + +**Production-safe gate:** the entire variant mechanism — variant components, +switcher bar, and the `?variant=` handling — must be unreachable in production +builds: compile it out via the project's dev-mode conditionals, an explicitly +non-production route guard, or by keeping the prototype on its throwaway +branch. Gating only the switcher UI is not enough. + +## Attribution and license + +Derived from `skills/engineering/prototype/` (`SKILL.md`, `LOGIC.md`, +`UI.md`) in [mattpocock/skills](https://github.com/mattpocock/skills) at +commit `2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package +(worktree isolation, production-safe gating, inlined references). That +material is and remains MIT-licensed: 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/plugins/agent-collab/skills/qa-verify/SKILL.md b/plugins/agent-collab/skills/qa-verify/SKILL.md index c9fffcc..eebb36b 100644 --- a/plugins/agent-collab/skills/qa-verify/SKILL.md +++ b/plugins/agent-collab/skills/qa-verify/SKILL.md @@ -1,6 +1,6 @@ --- name: qa-verify -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/red-team/SKILL.md b/plugins/agent-collab/skills/red-team/SKILL.md index 9dc47c0..2157d26 100644 --- a/plugins/agent-collab/skills/red-team/SKILL.md +++ b/plugins/agent-collab/skills/red-team/SKILL.md @@ -1,6 +1,6 @@ --- name: red-team -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/route/SKILL.md b/plugins/agent-collab/skills/route/SKILL.md index 4e45a20..9721d16 100644 --- a/plugins/agent-collab/skills/route/SKILL.md +++ b/plugins/agent-collab/skills/route/SKILL.md @@ -1,6 +1,6 @@ --- name: route -version: 4.6.0 +version: 4.7.0 description: Use when the operator says "ask Codex," "target=gemini," "target=grok," "target=composer," or explicitly names a managed backend. Also offer this proactively when routing needs dynamic primary-family exclusion. --- diff --git a/plugins/agent-collab/skills/rust-engineer/SKILL.md b/plugins/agent-collab/skills/rust-engineer/SKILL.md index 6c1943e..e4b49c2 100644 --- a/plugins/agent-collab/skills/rust-engineer/SKILL.md +++ b/plugins/agent-collab/skills/rust-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: rust-engineer -version: 4.6.0 +version: 4.7.0 description: Senior Rust engineer for ownership-heavy, performance-sensitive, and systems-level code. Use when the user says "review this Rust code for soundness", "help me fix this borrow checker error", "optimize this Rust hot path", or "/agent-collab:rust-engineer." Also offer this proactively when a diff introduces unsafe blocks, changes lifetime bounds, or touches an async task's cancellation path. --- diff --git a/plugins/agent-collab/skills/second-opinion/SKILL.md b/plugins/agent-collab/skills/second-opinion/SKILL.md index d664d7d..8d3c736 100644 --- a/plugins/agent-collab/skills/second-opinion/SKILL.md +++ b/plugins/agent-collab/skills/second-opinion/SKILL.md @@ -1,6 +1,6 @@ --- name: second-opinion -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/simulate-user/SKILL.md b/plugins/agent-collab/skills/simulate-user/SKILL.md index 20574e3..b2e109b 100644 --- a/plugins/agent-collab/skills/simulate-user/SKILL.md +++ b/plugins/agent-collab/skills/simulate-user/SKILL.md @@ -1,6 +1,6 @@ --- name: simulate-user -version: 4.6.0 +version: 4.7.0 defaults: tier: Fast effort: low diff --git a/plugins/agent-collab/skills/sql-engineer/SKILL.md b/plugins/agent-collab/skills/sql-engineer/SKILL.md index 12aa7a6..120a36d 100644 --- a/plugins/agent-collab/skills/sql-engineer/SKILL.md +++ b/plugins/agent-collab/skills/sql-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: sql-engineer -version: 4.6.0 +version: 4.7.0 description: Senior SQL specialist for query design, query optimization, and schema-aware performance work across relational databases. Use when the user says "optimize this SQL query", "explain this query plan", "design these indexes", or "/agent-collab:sql-engineer." Also offer this proactively when a diff adds a new query against a large table, changes a join or aggregation, or introduces a schema change that could affect an existing access pattern. --- diff --git a/plugins/agent-collab/skills/sre-engineer/SKILL.md b/plugins/agent-collab/skills/sre-engineer/SKILL.md index ffc8ca5..d18415a 100644 --- a/plugins/agent-collab/skills/sre-engineer/SKILL.md +++ b/plugins/agent-collab/skills/sre-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: sre-engineer -version: 4.6.0 +version: 4.7.0 description: Builds and improves system reliability through SLO design, error-budget policy, toil reduction, and resilience architecture. Use when the user says "help me define SLOs for this service", "what's our error budget burn rate", or "reduce the toil in this on-call rotation", or "/agent-collab:sre-engineer." Also offer this proactively when a reliability review, capacity plan, or alert-quality audit is warranted ahead of a launch or growth milestone. --- diff --git a/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md b/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md index 69acaf2..49dc777 100644 --- a/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md +++ b/plugins/agent-collab/skills/start-inbox-monitor/SKILL.md @@ -1,6 +1,6 @@ --- name: start-inbox-monitor -version: 4.6.0 +version: 4.7.0 description: Use when the user says "start the inbox monitor", "keep monitoring agent messages", or "/agent-collab:start-inbox-monitor", or when an active cross-agent thread needs durable session-scoped inbox monitoring. Select the native Codex, Claude, or Antigravity lifecycle instead of inventing a universal polling loop. --- diff --git a/plugins/agent-collab/skills/teamwork/SKILL.md b/plugins/agent-collab/skills/teamwork/SKILL.md index f2449d3..e614091 100644 --- a/plugins/agent-collab/skills/teamwork/SKILL.md +++ b/plugins/agent-collab/skills/teamwork/SKILL.md @@ -1,6 +1,6 @@ --- name: teamwork -version: 4.6.0 +version: 4.7.0 defaults: tier: Standard effort: medium diff --git a/plugins/agent-collab/skills/terraform-engineer/SKILL.md b/plugins/agent-collab/skills/terraform-engineer/SKILL.md index 14673ad..622a461 100644 --- a/plugins/agent-collab/skills/terraform-engineer/SKILL.md +++ b/plugins/agent-collab/skills/terraform-engineer/SKILL.md @@ -1,6 +1,6 @@ --- name: terraform-engineer -version: 4.6.0 +version: 4.7.0 description: Designs, refactors, and reviews Terraform infrastructure-as-code across cloud providers, with a focus on module contracts, state safety, and reviewable plans. Use when the user says "review this Terraform plan", "help me design a reusable module", or "why did this apply want to replace my resource", or "/agent-collab:terraform-engineer." Also offer this proactively when a change touches module interfaces, state backend configuration, or resource lifecycle blocks. --- diff --git a/plugins/agent-collab/skills/ui-to-code/SKILL.md b/plugins/agent-collab/skills/ui-to-code/SKILL.md index ef6120c..8006c18 100644 --- a/plugins/agent-collab/skills/ui-to-code/SKILL.md +++ b/plugins/agent-collab/skills/ui-to-code/SKILL.md @@ -1,6 +1,6 @@ --- name: ui-to-code -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/untrusted-audit/SKILL.md b/plugins/agent-collab/skills/untrusted-audit/SKILL.md index 9b1c2ac..3105c8e 100644 --- a/plugins/agent-collab/skills/untrusted-audit/SKILL.md +++ b/plugins/agent-collab/skills/untrusted-audit/SKILL.md @@ -1,6 +1,6 @@ --- name: untrusted-audit -version: 4.6.0 +version: 4.7.0 description: Audit an external or untrusted source before using it in code, skills, plugins, workflows, prompts, or operations. Use when the user says "audit this untrusted source," "can we use this repo," "review this gist," "prompt injection audit," "is this plugin safe," "evaluate this methodology," or "/agent-collab:untrusted-audit." Also offer this proactively when a task would incorporate third-party instructions, code, scripts, hooks, generated skills, package manifests, install steps, or auto-updated methodology into the workspace or agent environment. --- diff --git a/plugins/agent-collab/skills/visual-review/SKILL.md b/plugins/agent-collab/skills/visual-review/SKILL.md index 80af642..a87df24 100644 --- a/plugins/agent-collab/skills/visual-review/SKILL.md +++ b/plugins/agent-collab/skills/visual-review/SKILL.md @@ -1,6 +1,6 @@ --- name: visual-review -version: 4.6.0 +version: 4.7.0 defaults: tier: Advanced effort: high diff --git a/plugins/agent-collab/skills/worker/SKILL.md b/plugins/agent-collab/skills/worker/SKILL.md index cd00b71..29e81f6 100644 --- a/plugins/agent-collab/skills/worker/SKILL.md +++ b/plugins/agent-collab/skills/worker/SKILL.md @@ -1,6 +1,6 @@ --- name: worker -version: 4.6.0 +version: 4.7.0 description: Use when the operator says "delegate this implementation," "use Gemini for this corpus," "ask Codex to build," or "use Composer for codegen." Also offer this proactively when a bounded non-governance task benefits from a managed worker. --- diff --git a/scripts/build_release_evidence.py b/scripts/build_release_evidence.py index ab0eac2..a1bc8d5 100644 --- a/scripts/build_release_evidence.py +++ b/scripts/build_release_evidence.py @@ -24,6 +24,12 @@ PLUGIN_NAME = "agent-collab" MANIFEST_LICENSE = "PolyForm-Strict-1.0.0" SPDX_LICENSE = "LicenseRef-PolyForm-Strict-1.0.0" +# Skills derived from MIT-licensed mattpocock/skills material remain MIT; +# the file map lives in docs/third-party-skill-provenance.md. +MIT_DERIVED_SKILL_MEMBERS = frozenset( + f"skills/{name}/SKILL.md" + for name in ("architecture-review", "decision-map", "prototype") +) LICENSE_SHA256 = "9eb48619fbc193ab7bb327b090cfcc703000265b83e670f81f231d0b1c43c56e" COPYRIGHT_TEXT = ( "Copyright (c) 2026 John Osumi. All rights reserved except as expressly granted." @@ -197,6 +203,8 @@ def _manifest(files: dict[str, bytes], path: str) -> dict[str, object]: def _file_license(name: str, *, mode: str) -> str: + if name in MIT_DERIVED_SKILL_MEMBERS: + return "MIT" if mode == "activation" and ( name.startswith(archive_builder.RUNTIME_BUNDLE_REL.as_posix() + "/") or name == archive_builder.THIRD_PARTY_NOTICE_REL.as_posix() diff --git a/scripts/check_release_consistency.py b/scripts/check_release_consistency.py index b48a78d..74a50dd 100644 --- a/scripts/check_release_consistency.py +++ b/scripts/check_release_consistency.py @@ -45,6 +45,13 @@ NOTICE_TEXT = ( "Copyright (c) 2026 John Osumi. All rights reserved except as expressly " "granted.\nCommercial licensing is administered by Osumi Consulting LLC.\n" + "\n" + "The decision-map, prototype, and architecture-review skills contain " + "material\nderived from the MIT-licensed mattpocock/skills repository\n" + "(Copyright (c) 2026 Matt Pocock). Those portions remain MIT-licensed; " + "see\ndocs/third-party-skill-provenance.md for the pinned upstream " + "commit and\nper-file provenance, and each derived SKILL.md for the " + "full MIT notice.\n" ) LEGAL_FILES = ("LICENSE", "NOTICE", "COMMERCIAL-LICENSING.md") diff --git a/scripts/skill-build-config.json b/scripts/skill-build-config.json index 62e7e44..8a08d82 100644 --- a/scripts/skill-build-config.json +++ b/scripts/skill-build-config.json @@ -20,7 +20,7 @@ "tier_flash_resolves_to_claude": "an asynchronous Anthropic inbox review; never a synchronous invocation", "tier_pro_resolves_to_gemini": "an eligible managed Google-family reviewer at high effort", "tier_flash_resolves_to_gemini": "an eligible managed Google-family reviewer at low effort", - "skill_version": "4.6.0", + "skill_version": "4.7.0", "agent_runtime_status_defaults_block": "defaults:\n tier: Fast\n effort: low\n", "merge_resolve_defaults_block": "defaults:\n tier: Advanced\n effort: high\n", "merge_resolve_call_params": "`effort='high'` in every eligible advisory row and no `tier` request field", diff --git a/skill-specs/architecture-review.md b/skill-specs/architecture-review.md new file mode 100644 index 0000000..6f8c5e5 --- /dev/null +++ b/skill-specs/architecture-review.md @@ -0,0 +1,125 @@ +--- +name: architecture-review +version: {{ skill_version }} +description: Self-executed sweep of a codebase for module-deepening opportunities — shallow interfaces, scattered locality, untestable seams — presented as a visual report the user picks a candidate from, then explored interactively. Unlike `architect` (routed consultation) and `code-review` (diff review), this skill is run by the active primary on the whole codebase. Use when the user says "architecture review," "find deepening opportunities," "where is this codebase getting muddy," "improve the architecture," or "/agent-collab:architecture-review." Also offer this proactively when repeated friction in a working session traces to shallow modules — bouncing between many files to follow one concept, or tests that cannot reach behavior through the current interfaces. +--- + +# Architecture review — find and explore deepening opportunities + +Surface architectural friction and propose **deepening opportunities** — +refactors that turn shallow modules into deep ones. The aim is testability and +navigability. This skill is **self-executed by the active primary**: it reads +the codebase directly and produces its own report. It composes with, and does +not replace, the routed skills: for an independent cross-family read on the top +candidates, route them through `architect` afterward. + +## Design vocabulary + +Use these terms exactly in every suggestion — do not drift into "component," +"service," "API," or "boundary": + +- **Module** — anything with an interface and an implementation; deliberately + scale-agnostic (a function, class, package, or tier-spanning slice). +- **Interface** — everything a caller must know to use the module correctly: + types, invariants, ordering constraints, error modes, configuration, + performance characteristics. +- **Implementation** — what is inside the module. +- **Depth** — leverage at the interface: how much behavior a caller or test can + exercise per unit of interface learned. **Deep** = small interface, large + behavior; **shallow** = interface nearly as complex as the implementation. +- **Seam** — a place where behavior can be altered without editing in that + place; where the interface lives. Placing the seam is its own decision. +- **Adapter** — a concrete thing satisfying an interface at a seam (a role, + not a substance). One adapter = hypothetical seam; two = real. +- **Leverage** — what callers get from depth: 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. Fix once, fixed everywhere. +- **Deletion test** — would deleting this module concentrate complexity behind + a real interface, or just move it? "Concentrates" marks a shallow module + worth deepening. + +## Process + +### 1. Explore — scope before you scan + +Deepening pays off by making future changes easier, so weight the parts of the +codebase that actually change. If the user named a direction — a module, a +subsystem, a pain point — take it. Otherwise walk the commit history +(`git log --oneline`) for hot spots and let those paths pull attention first; +widen the net only if changes are scattered. + +Read the project's domain glossary (`CONTEXT.md` or equivalent) and any +architecture decision records in the area first — use the project's own domain +vocabulary in every candidate, and do not re-litigate recorded decisions +unless the friction is real enough to warrant reopening one (then mark the +conflict explicitly in the candidate). + +Explore with the host's bounded read-only exploration facility (a read-only +subagent where available; direct reading otherwise). Note where you experience +friction rather than following rigid heuristics: where does understanding one +concept require bouncing between many small modules; where are modules +shallow; where were pure functions extracted for testability while the real +bugs hide in how they are called; which parts are untestable through their +current interface. Apply the deletion test to anything suspect. + +### 2. Present candidates as a visual report + +Write a **fully self-contained** HTML file to the OS temp directory — resolve +`$TMPDIR` falling back to `/tmp` (`%TEMP%` on Windows), name it +`architecture-review-.html` — and tell the user the absolute path +(open it with the platform opener where available). **Inline all CSS and +hand-drawn SVG; no CDN scripts, no external stylesheets, no remote fonts, no +third-party browser code.** The report must render identically offline. + +For each candidate render a card: **Files** involved; **Problem** (why the +current shape causes friction); **Solution** in plain language; **Benefits** +in terms of locality, leverage, and how tests improve; a **before/after +diagram** (inline SVG or styled divs) showing the shallowness and the +deepening; and a **recommendation strength** badge — `Strong`, +`Worth exploring`, or `Speculative`. End with a **Top recommendation** section +naming the candidate to tackle first and why. Do not propose concrete +interfaces yet. + +Then ask the user which candidate to explore. + +### 3. Explore the picked candidate interactively + +Walk the decision tree with the user one question at a time — constraints, +dependencies, the shape of the deepened module, what sits behind the seam, +which tests survive. Use the host's requirements-interview skill when one is +available; otherwise interview inline: look up facts in the codebase, put +every decision to the user, and do not begin implementation until the user +confirms the shared understanding. As decisions crystallize, keep the +project's domain glossary current (add or sharpen terms in `CONTEXT.md` where +the project keeps one), and when the user rejects a candidate for a +load-bearing reason, offer to record the decision so future reviews do not +re-suggest it. For an independent read on a high-stakes candidate, route it +through `architect` (read-only consultation) before committing. + +This skill produces analysis and an agreed direction — implementation happens +afterward through the normal change workflow, not inside the review. + +## Attribution and license + +Derived from `skills/engineering/improve-codebase-architecture/SKILL.md` and +`skills/engineering/codebase-design/SKILL.md` in +[mattpocock/skills](https://github.com/mattpocock/skills) at commit +`2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package (inlined +vocabulary, self-contained report assets, host-neutral interviewing, +composition with routed consultation). That material is and remains +MIT-licensed: 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/skill-specs/decision-map.md b/skill-specs/decision-map.md new file mode 100644 index 0000000..3fa9c9a --- /dev/null +++ b/skill-specs/decision-map.md @@ -0,0 +1,145 @@ +--- +name: decision-map +version: {{ skill_version }} +description: Plan an effort too large for one session as a shared map of decision tickets on the repo's issue tracker, then resolve them one per session until the way to the destination is clear. Use when the user says "decision map," "chart this effort," "map out this project," "break this fog into tickets," "work the map," or "/agent-collab:decision-map." Also offer this proactively when a request is a loose multi-session idea whose route is not yet visible — where the open questions outnumber the known steps and a single planning pass would either stall or guess. +--- + +# Decision map — multi-session planning on the issue tracker + +A loose idea has arrived — too big for one session, and wrapped in fog: the way +from here to the **destination** is not visible yet. This skill charts the way +as a **shared map** on the repo's issue tracker, then works its **decision +tickets** — questions whose resolution is a decision, not slices of a build to +execute — one at a time until the route is clear. + +The destination varies per effort, and naming it is the first act of charting. +It might be a spec to hand off, a decision to lock before implementation +planning starts, or a change made in place. The map is domain-agnostic. + +## Plan, don't do + +Each ticket resolves a decision; the map is done when nothing is left to decide +before someone goes and does the thing. The pull to just do the work is usually +the signal you have reached the edge of the map and it is time to hand off. An +effort can override this in its Notes — carrying execution into the map — but +absent that, produce decisions, not deliverables. + +## Refer by name + +Every map and ticket is an issue, so it has a name — its title. In everything +the human reads, refer to it by that name, never by a bare id or number; the id +and URL ride inside the name as a link, never stand in for it. + +## Tracker resolution and the write gate + +Resolve the tracker in this order; never assume one: + +1. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote. + Feature-detect sub-issue and dependency support (`gh issue create --parent`, + `gh issue edit --blocked-by`) before relying on it; on older CLI versions + fall back to a `Blocked by: #N` body convention and a task-list of child + links in the map body. +2. **Local markdown** when there is no usable remote tracker: the map at + `.scratch//map.md`, tickets as sibling files, blocking edges as + body text. +3. **Whatever the project's own docs designate**, when they document a + different tracker workflow — follow that documentation. + +**Write gate:** tracker issues are shared, outward-facing state. Before +creating, editing, assigning, commenting on, or closing any tracker item, +present the exact set of writes (titles, bodies, edges) and get the user's +confirmation — unless the user in this conversation already explicitly asked to +publish or update the map. Local-markdown mode needs no confirmation. + +## The map + +The map is one issue labelled `decision-map:map`; its tickets are child issues. +The map is an **index**, not a store: it gists each closed decision in one line +and links the ticket that holds the detail. Open tickets are not listed — they +are found by query. The map body carries four sections: + +- **Destination** — what reaching the end looks like, one or two lines; every + session orients to it before choosing a ticket. +- **Notes** — domain, skills every session should consult, standing preferences. +- **Decisions so far** — one line per closed ticket: `[title](link) — gist`. +- **Not yet specified** and **Out of scope** — see below. + +Each ticket's body is one question, sized to a single session. A session +**claims** a ticket by assigning it before any work — the assignee is the +claim. A ticket is unblocked when every ticket blocking it is closed; the +**frontier** is the open, unblocked, unclaimed children. + +## Ticket types + +Every ticket is either **HITL** — worked with a human who speaks for +themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves +through that live exchange; the agent never stands in for the human's side. + +- **Research** (AFK): read documentation, third-party APIs, or local knowledge + bases to surface a fact a decision waits on. Delegate to a bounded read-only + research subagent when the host provides one; otherwise research inline. + Capture findings as a cited markdown note linked from the ticket. +- **Prototype** (HITL): raise the fidelity of the discussion with a cheap + concrete artifact to react to — via the `prototype` skill in this package + where code is called for. Link the artifact from the ticket. +- **Interview** (HITL): the default. Work the question with the user one + question at a time, resolving dependent decisions in order. Use the host's + requirements-interview or brainstorming skill when one is available; + otherwise interview inline. Either way: look up **facts** in the environment + rather than asking, put every **decision** to the human and wait, and do not + act on the outcome until the user confirms shared understanding. +- **Task** (HITL or AFK): manual work that must happen before a decision can be + made — provisioning access, moving data so its shape can be seen. It earns + its place by unblocking a decision, not by delivering the destination. + +## Fog of war and out of scope + +Do not chart what you cannot yet see. **Not yet specified** holds the dim view +of questions you can tell are coming but cannot yet phrase sharply; resolving +tickets graduates patches of it into fresh tickets. The test for fog vs. +ticket is whether the question can be stated precisely now — not whether it can +be answered now. **Out of scope** holds work consciously ruled beyond the +destination; it never graduates. When an existing ticket turns out to sit past +the destination, close it and leave one line here with the reason. + +## Invocation + +Two modes. Either way, resolve at most one non-research ticket per session. + +**Chart the map** (user arrives with a loose idea): (1) pin the destination via +an interview; (2) interview again breadth-first to surface the open decisions — +if no fog surfaces, the effort fits one session and needs no map: say so and +stop; (3) draft the map and the tickets you can specify now; (4) pass the write +gate, then create the map and tickets, wiring blocking edges in a second pass; +(5) kick off research tickets; (6) stop — charting is one session's work. + +**Work the map** (user arrives with a map reference): (1) load the map body +only; (2) take the named ticket, or the first frontier ticket — claim it +first; (3) resolve it, zooming into related tickets on demand; (4) record the +answer as a resolution comment, close the ticket, append the one-line gist to +Decisions so far; (5) graduate any fog the answer sharpened, and rule anything +the answer exposed as beyond the destination out of scope. Expect concurrent +sessions to be editing the tracker; the claim discipline is what keeps them +from colliding. + +## Attribution and license + +Derived from `skills/engineering/wayfinder/SKILL.md` in +[mattpocock/skills](https://github.com/mattpocock/skills) at commit +`2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package +(tracker resolution, write gate, host-neutral sub-skill references). That +material is and remains MIT-licensed: 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/skill-specs/prototype.md b/skill-specs/prototype.md new file mode 100644 index 0000000..4c22c40 --- /dev/null +++ b/skill-specs/prototype.md @@ -0,0 +1,119 @@ +--- +name: prototype +version: {{ skill_version }} +description: Build a throwaway prototype that answers one design question — an interactive terminal app to pressure-test a state model or logic shape, or several radically different UI variants on one route. Use when the user says "prototype this," "sanity-check this state model," "show me a few options for this page," "mock up some variations," or "/agent-collab:prototype." Also offer this proactively when a design conversation is circling a question that a runnable artifact would settle in minutes — how a state machine handles an awkward case, or which of several layouts actually works with real data. +--- + +# Prototype — throwaway code that answers a question + +A prototype is **throwaway code that answers a question**. The question decides +the shape: + +- **"Does this logic or state model feel right?"** → 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?"** → several radically different UI variants + on a single route, switchable in the browser. + +Getting the branch wrong wastes the whole prototype. If the question is +ambiguous and the user is not reachable, default to whichever branch better +matches the surrounding code — a backend module suggests logic, a page or +component suggests UI — and state the assumption at the top of the prototype. + +## Rules that apply to both branches + +1. **Isolate the prototype from the caller's work.** Build it on an isolated + worktree or a clearly named throwaway branch. Never commit to, rebase, or + otherwise alter the branch the user was on without their explicit approval. +2. **Throwaway from day one, and clearly marked as such.** Name files and + routes so a casual reader sees "prototype," and follow the project's + existing conventions rather than inventing new top-level structure. +3. **One command to run**, registered with the project's existing task runner + (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`); if there + is none, put the command at the top of the prototype's README. +4. **No persistence by default.** State lives in memory; persistence is the + thing a prototype checks, not something it depends on. If the question + explicitly involves a database, use a scratch store with a clear + "PROTOTYPE — wipe me" name. +5. **Skip the polish.** No tests, no error handling beyond runnability, no + abstractions. The point is to learn something fast. +6. **Surface the state.** After every action (logic) or on every variant switch + (UI), show the full relevant state so the user sees what changed. +7. **Capture it when done.** Fold the validated decision into the real code; + keep the prototype itself as a primary source on its throwaway branch with a + context pointer from the relevant issue or commit. The main branch keeps + only the validated decision. + +## Logic branch — interactive terminal app + +State the question first — one paragraph at the top of the file or README; a +logic prototype that answers the wrong question is pure waste. Then: + +1. **Use the host project's language and tooling.** No new runtimes or package + managers for a prototype. +2. **Isolate the logic behind a small pure interface** that could be lifted + into the real codebase later — a pure reducer `(state, action) → state`, an + explicit state machine when "which actions are legal right now" is part of + the question, a set of pure functions over a plain data type, or a module + with a clear method surface when the logic genuinely owns ongoing state. + Pick the shape that fits the question, not the one easiest to wire to a + terminal. No I/O or terminal code inside the logic module. +3. **Wrap it in the smallest terminal shell that exposes the state**: on every + action, clear the screen and re-render one stable frame — current state + pretty-printed, then the keyboard shortcuts (`[a] add [t] tick [q] quit`). + Read one keystroke, dispatch, re-render, loop until quit. +4. **Hand the run command to the user.** The interesting moments are "wait, + that shouldn't be possible" — bugs in the idea, which is the point. Add + actions as they ask. +5. **On resolution**, the validated logic module lifts into the real code; the + terminal shell rides along to the throwaway branch as a primary source. + +Anti-patterns: adding tests; wiring to the real database; generalizing for +futures the question does not ask about; blurring logic and shell so the +module is no longer portable; shipping the shell toward production. + +## UI branch — radically different variants on one route + +Default to **3 variants**; more than 5 is noise. Two sub-shapes; strongly +prefer the first: + +- **Adjustment to an existing page** (preferred): render variants on the + existing route, gated by a `?variant=` URL parameter — the page's real data, + auth, and surroundings stay, only the rendering swaps. A new section that + would naturally live inside an existing page is still this sub-shape. +- **A new page** (last resort): only when the surface genuinely has no home. + Follow the project's routing conventions and name the route so it is + obviously a prototype. + +Variants must be **structurally different** — different layout, information +hierarchy, primary affordance — not different colors. If two drafts come out +similar, redo one with explicit counter-guidance. Use the project's existing +component and styling system. A floating bottom bar switches variants. + +**Production-safe gate:** the entire variant mechanism — variant components, +switcher bar, and the `?variant=` handling — must be unreachable in production +builds: compile it out via the project's dev-mode conditionals, an explicitly +non-production route guard, or by keeping the prototype on its throwaway +branch. Gating only the switcher UI is not enough. + +## Attribution and license + +Derived from `skills/engineering/prototype/` (`SKILL.md`, `LOGIC.md`, +`UI.md`) in [mattpocock/skills](https://github.com/mattpocock/skills) at +commit `2ab958093e83e0ec752e6c1c5932da465bf23e0c`, adapted for this package +(worktree isolation, production-safe gating, inlined references). That +material is and remains MIT-licensed: 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/tests/test_public_distribution_contract.py b/tests/test_public_distribution_contract.py index 5c462fd..ff0e5cf 100644 --- a/tests/test_public_distribution_contract.py +++ b/tests/test_public_distribution_contract.py @@ -36,7 +36,15 @@ def test_public_licensing_identifies_owner_and_approval_boundary(self) -> None: notice, "Copyright (c) 2026 John Osumi. All rights reserved except as " "expressly granted.\nCommercial licensing is administered by " - "Osumi Consulting LLC.\n", + "Osumi Consulting LLC.\n" + "\n" + "The decision-map, prototype, and architecture-review skills " + "contain material\nderived from the MIT-licensed " + "mattpocock/skills repository\n(Copyright (c) 2026 Matt Pocock). " + "Those portions remain MIT-licensed; see\n" + "docs/third-party-skill-provenance.md for the pinned upstream " + "commit and\nper-file provenance, and each derived SKILL.md for " + "the full MIT notice.\n", ) for phrase in ( "explicit written approval", diff --git a/tests/test_release_evidence.py b/tests/test_release_evidence.py index 3ff9625..5ddcaf6 100644 --- a/tests/test_release_evidence.py +++ b/tests/test_release_evidence.py @@ -256,11 +256,23 @@ def test_policy_only_spdx_output_preserves_project_only_license_contract(self) - ["agent-collab"], ) self.assertTrue(sbom["files"]) + mit_members = { + "skills/architecture-review/SKILL.md", + "skills/decision-map/SKILL.md", + "skills/prototype/SKILL.md", + } + observed_mit = { + item["fileName"] + for item in sbom["files"] + if item["licenseConcluded"] == "MIT" + } + self.assertEqual(observed_mit, mit_members) self.assertTrue( all( item["licenseConcluded"] == "LicenseRef-PolyForm-Strict-1.0.0" for item in sbom["files"] + if item["fileName"] not in mit_members ) ) From 64de34dc3345e19033e930ae36d699b026a19c74 Mon Sep 17 00:00:00 2001 From: John Osumi <931193+sumitake@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:09:15 -0700 Subject: [PATCH 2/3] fix: smoke-test workflow headings + consistency-fixture NOTICE sync Rename process headings in the three new skills to the smoke test's accepted set (Workflow), and make the release-consistency test fixture consume check_release_consistency.NOTICE_TEXT instead of a duplicated literal so legal-text updates cannot drift the fixture again. Co-Authored-By: Claude Fable 5 --- plugins/agent-collab/skills/architecture-review/SKILL.md | 2 +- plugins/agent-collab/skills/decision-map/SKILL.md | 2 +- plugins/agent-collab/skills/prototype/SKILL.md | 2 +- scripts/test_check_release_consistency.py | 6 +----- skill-specs/architecture-review.md | 2 +- skill-specs/decision-map.md | 2 +- skill-specs/prototype.md | 2 +- 7 files changed, 7 insertions(+), 11 deletions(-) diff --git a/plugins/agent-collab/skills/architecture-review/SKILL.md b/plugins/agent-collab/skills/architecture-review/SKILL.md index 6d7d3cc..4581b1d 100644 --- a/plugins/agent-collab/skills/architecture-review/SKILL.md +++ b/plugins/agent-collab/skills/architecture-review/SKILL.md @@ -39,7 +39,7 @@ Use these terms exactly in every suggestion — do not drift into "component," a real interface, or just move it? "Concentrates" marks a shallow module worth deepening. -## Process +## Workflow ### 1. Explore — scope before you scan diff --git a/plugins/agent-collab/skills/decision-map/SKILL.md b/plugins/agent-collab/skills/decision-map/SKILL.md index f80e5c5..92168bc 100644 --- a/plugins/agent-collab/skills/decision-map/SKILL.md +++ b/plugins/agent-collab/skills/decision-map/SKILL.md @@ -102,7 +102,7 @@ be answered now. **Out of scope** holds work consciously ruled beyond the destination; it never graduates. When an existing ticket turns out to sit past the destination, close it and leave one line here with the reason. -## Invocation +## Workflow Two modes. Either way, resolve at most one non-research ticket per session. diff --git a/plugins/agent-collab/skills/prototype/SKILL.md b/plugins/agent-collab/skills/prototype/SKILL.md index c423b09..2403606 100644 --- a/plugins/agent-collab/skills/prototype/SKILL.md +++ b/plugins/agent-collab/skills/prototype/SKILL.md @@ -20,7 +20,7 @@ ambiguous and the user is not reachable, default to whichever branch better matches the surrounding code — a backend module suggests logic, a page or component suggests UI — and state the assumption at the top of the prototype. -## Rules that apply to both branches +## Workflow rules that apply to both branches 1. **Isolate the prototype from the caller's work.** Build it on an isolated worktree or a clearly named throwaway branch. Never commit to, rebase, or diff --git a/scripts/test_check_release_consistency.py b/scripts/test_check_release_consistency.py index 1387fc1..ac8a136 100644 --- a/scripts/test_check_release_consistency.py +++ b/scripts/test_check_release_consistency.py @@ -133,11 +133,7 @@ def setUp(self): encoding="utf-8", ) license_bytes = (Path(__file__).resolve().parents[1] / "LICENSE").read_bytes() - notice = ( - "Copyright (c) 2026 John Osumi. All rights reserved except as " - "expressly granted.\nCommercial licensing is administered by " - "Osumi Consulting LLC.\n" - ).encode() + notice = crc.NOTICE_TEXT.encode() commercial = ( "PolyForm Strict License 1.0.0\nexplicit written approval\n" "Osumi Consulting LLC\nRepository access\ninstallation\n" diff --git a/skill-specs/architecture-review.md b/skill-specs/architecture-review.md index 6f8c5e5..8143060 100644 --- a/skill-specs/architecture-review.md +++ b/skill-specs/architecture-review.md @@ -39,7 +39,7 @@ Use these terms exactly in every suggestion — do not drift into "component," a real interface, or just move it? "Concentrates" marks a shallow module worth deepening. -## Process +## Workflow ### 1. Explore — scope before you scan diff --git a/skill-specs/decision-map.md b/skill-specs/decision-map.md index 3fa9c9a..62de4c6 100644 --- a/skill-specs/decision-map.md +++ b/skill-specs/decision-map.md @@ -102,7 +102,7 @@ be answered now. **Out of scope** holds work consciously ruled beyond the destination; it never graduates. When an existing ticket turns out to sit past the destination, close it and leave one line here with the reason. -## Invocation +## Workflow Two modes. Either way, resolve at most one non-research ticket per session. diff --git a/skill-specs/prototype.md b/skill-specs/prototype.md index 4c22c40..7817698 100644 --- a/skill-specs/prototype.md +++ b/skill-specs/prototype.md @@ -20,7 +20,7 @@ ambiguous and the user is not reachable, default to whichever branch better matches the surrounding code — a backend module suggests logic, a page or component suggests UI — and state the assumption at the top of the prototype. -## Rules that apply to both branches +## Workflow rules that apply to both branches 1. **Isolate the prototype from the caller's work.** Build it on an isolated worktree or a clearly named throwaway branch. Never commit to, rebase, or From ea6e8f084146f74287bd23c58c5e6dd7314cf67c Mon Sep 17 00:00:00 2001 From: John Osumi <931193+sumitake@users.noreply.github.com> Date: Mon, 3 Aug 2026 13:14:25 -0700 Subject: [PATCH 3/3] review: aggregate MIT into package-level SPDX expression; docs-designated tracker precedes GitHub default Integrate the two live Codex review threads: the agent-collab SPDX package record now declares 'LicenseRef-PolyForm-Strict-1.0.0 AND MIT' (policy-only concluded likewise), and decision-map's tracker resolution puts a project-documented tracker ahead of the GitHub-remote default. Co-Authored-By: Claude Fable 5 --- .../agent-collab/skills/decision-map/SKILL.md | 18 ++++++++++-------- scripts/build_release_evidence.py | 9 +++++++-- skill-specs/decision-map.md | 18 ++++++++++-------- tests/test_release_evidence.py | 2 +- 4 files changed, 28 insertions(+), 19 deletions(-) diff --git a/plugins/agent-collab/skills/decision-map/SKILL.md b/plugins/agent-collab/skills/decision-map/SKILL.md index 92168bc..86814a3 100644 --- a/plugins/agent-collab/skills/decision-map/SKILL.md +++ b/plugins/agent-collab/skills/decision-map/SKILL.md @@ -34,16 +34,18 @@ and URL ride inside the name as a link, never stand in for it. Resolve the tracker in this order; never assume one: -1. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote. - Feature-detect sub-issue and dependency support (`gh issue create --parent`, - `gh issue edit --blocked-by`) before relying on it; on older CLI versions - fall back to a `Blocked by: #N` body convention and a task-list of child - links in the map body. -2. **Local markdown** when there is no usable remote tracker: the map at +1. **Whatever the project's own docs designate**: when the repository's + documentation records a tracker workflow (an issue-tracker doc, a + contributing guide naming Jira/Linear/GitLab, or equivalent), follow that + documentation — it wins even when a GitHub remote exists. +2. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote and no + documented tracker says otherwise. Feature-detect sub-issue and dependency + support (`gh issue create --parent`, `gh issue edit --blocked-by`) before + relying on it; on older CLI versions fall back to a `Blocked by: #N` body + convention and a task-list of child links in the map body. +3. **Local markdown** when neither applies: the map at `.scratch//map.md`, tickets as sibling files, blocking edges as body text. -3. **Whatever the project's own docs designate**, when they document a - different tracker workflow — follow that documentation. **Write gate:** tracker issues are shared, outward-facing state. Before creating, editing, assigning, commenting on, or closing any tracker item, diff --git a/scripts/build_release_evidence.py b/scripts/build_release_evidence.py index a1bc8d5..9530a4c 100644 --- a/scripts/build_release_evidence.py +++ b/scripts/build_release_evidence.py @@ -30,6 +30,9 @@ f"skills/{name}/SKILL.md" for name in ("architecture-review", "decision-map", "prototype") ) +# The package as a whole contains PolyForm-owned material AND the MIT-derived +# skill members above, so the package-level expression aggregates both. +PACKAGE_LICENSE_EXPRESSION = f"{SPDX_LICENSE} AND MIT" LICENSE_SHA256 = "9eb48619fbc193ab7bb327b090cfcc703000265b83e670f81f231d0b1c43c56e" COPYRIGHT_TEXT = ( "Copyright (c) 2026 John Osumi. All rights reserved except as expressly granted." @@ -460,9 +463,11 @@ def build_evidence( {"algorithm": "SHA256", "checksumValue": archive_digest} ], "licenseConcluded": ( - SPDX_LICENSE if mode == "policy-only" else "NOASSERTION" + PACKAGE_LICENSE_EXPRESSION + if mode == "policy-only" + else "NOASSERTION" ), - "licenseDeclared": SPDX_LICENSE, + "licenseDeclared": PACKAGE_LICENSE_EXPRESSION, "copyrightText": COPYRIGHT_TEXT, "supplier": "Person: John Osumi", }, diff --git a/skill-specs/decision-map.md b/skill-specs/decision-map.md index 62de4c6..c8c63cf 100644 --- a/skill-specs/decision-map.md +++ b/skill-specs/decision-map.md @@ -34,16 +34,18 @@ and URL ride inside the name as a link, never stand in for it. Resolve the tracker in this order; never assume one: -1. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote. - Feature-detect sub-issue and dependency support (`gh issue create --parent`, - `gh issue edit --blocked-by`) before relying on it; on older CLI versions - fall back to a `Blocked by: #N` body convention and a task-list of child - links in the map body. -2. **Local markdown** when there is no usable remote tracker: the map at +1. **Whatever the project's own docs designate**: when the repository's + documentation records a tracker workflow (an issue-tracker doc, a + contributing guide naming Jira/Linear/GitLab, or equivalent), follow that + documentation — it wins even when a GitHub remote exists. +2. **GitHub Issues via the `gh` CLI** when the repo has a GitHub remote and no + documented tracker says otherwise. Feature-detect sub-issue and dependency + support (`gh issue create --parent`, `gh issue edit --blocked-by`) before + relying on it; on older CLI versions fall back to a `Blocked by: #N` body + convention and a task-list of child links in the map body. +3. **Local markdown** when neither applies: the map at `.scratch//map.md`, tickets as sibling files, blocking edges as body text. -3. **Whatever the project's own docs designate**, when they document a - different tracker workflow — follow that documentation. **Write gate:** tracker issues are shared, outward-facing state. Before creating, editing, assigning, commenting on, or closing any tracker item, diff --git a/tests/test_release_evidence.py b/tests/test_release_evidence.py index 5ddcaf6..2d12a4b 100644 --- a/tests/test_release_evidence.py +++ b/tests/test_release_evidence.py @@ -235,7 +235,7 @@ def test_spdx_inventory_contains_exact_legal_files_and_license(self) -> None: self.assertEqual(package["versionInfo"], PACKAGE_VERSION) self.assertEqual( package["licenseDeclared"], - "LicenseRef-PolyForm-Strict-1.0.0", + "LicenseRef-PolyForm-Strict-1.0.0 AND MIT", ) self.assertEqual(package["licenseConcluded"], package["licenseDeclared"]) files = {item["fileName"]: item for item in sbom["files"]}