From ab0592427c92648ab4e81adb55cce59cc03337cd Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Sat, 10 Oct 2026 21:56:46 +0100 Subject: [PATCH] feat(skills): add package selection workflow --- GLOSSARY.md | 2 ++ README.md | 1 + skills/code-cleanup/references/review.md | 2 ++ skills/implement/SKILL.md | 2 +- skills/select-packages/SKILL.md | 26 ++++++++++++++ skills/select-packages/agents/openai.yaml | 3 ++ .../select-packages/references/selection.md | 34 +++++++++++++++++++ skills/specify-feature/SKILL.md | 2 +- 8 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 skills/select-packages/SKILL.md create mode 100644 skills/select-packages/agents/openai.yaml create mode 100644 skills/select-packages/references/selection.md diff --git a/GLOSSARY.md b/GLOSSARY.md index 3dbdcb2..aa4b8e2 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -18,6 +18,8 @@ **Duplicated procedure**: A composing skill or supporting resource repeats execution rules owned by a skill it delegates to. Caller-specific inputs, sequencing, authority boundaries and outcome checks define composition rather than duplicated procedure. +**Package selection**: A supporting capability that delegates read-only discovery and evaluation of packages for a requested problem or feature to a fresh agent. It returns a succinct package recommendation or an explicit recommendation to use no package, without installations, scratch files or a detailed report. + ### Software quality **Deterministic measurement**: A reproducible tool-produced observation of one named property of a fixed software candidate, with its scope, components, configuration, limitations, and comparison basis preserved. An attention threshold requires appraisal but is not by itself a defect, an overall quality score, or permission to weaken behaviour or design. diff --git a/README.md b/README.md index 057f708..99a124f 100644 --- a/README.md +++ b/README.md @@ -113,6 +113,7 @@ Lifecycle entry points invoke these focused capabilities when needed. You can al | [$elicit](skills/elicit/SKILL.md) | Resolve material questions and decisions through a confirmed dialogue. | | [$elicit-with-context](skills/elicit-with-context/SKILL.md) | Clarify a software task while maintaining project terminology and qualifying decision records. | | [$research](skills/research/SKILL.md) | Produce a durable cited research report. | +| [$select-packages](skills/select-packages/SKILL.md) | Delegate read-only discovery and return a succinct package recommendation. | | [$modular-design](skills/modular-design/SKILL.md) | Design simple interfaces that hide domain knowledge and complexity. | | [$test-design](skills/test-design/SKILL.md) | Design minimal tests for observable behaviour. | | [$measure-code-complexity](skills/measure-code-complexity/SKILL.md) | Measure code complexity and interpret signals that warrant attention. | diff --git a/skills/code-cleanup/references/review.md b/skills/code-cleanup/references/review.md index 7ed7eb2..ac8b0fb 100644 --- a/skills/code-cleanup/references/review.md +++ b/skills/code-cleanup/references/review.md @@ -12,6 +12,8 @@ Find ambitious, concrete simplifications in the supplied candidate. Review read- Apply **YAGNI** to speculative machinery and **DRY** to repeated knowledge. Prefer deletion, consolidation and direct code before extraction. Keep a new boundary only when it removes more reader burden than it adds. Count layers to trace and mutable state to hold. A lower line count or metric cannot justify dense code or displaced complexity. +Flag common, reusable machinery that could be replaced by an established package when the code demonstrates a concrete maintenance burden. Identify the supported behaviour and preservation gaps, then refer candidate selection to the caller through [$select-packages](../../select-packages/SKILL.md). Leave package discovery and installation outside this review. + ## Build the report Use [the report template](../assets/cleanup-report.md). Create a unique file such as `code-cleanup-.md` in the OS temporary directory. Record a compact candidate identity rather than a table of file hashes. Put a file path and verified line or symbol in every candidate index row. Use repository-relative paths in the index and absolute paths in the details. Keep one candidate per coherent transformation, including all related-file changes. Merge overlapping observations. Order by maintenance benefit, then strength of preservation evidence. Include every justified candidate without a quota. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 61ae531..f6453fe 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -13,7 +13,7 @@ Use the requested change or ticket and any supplied acceptance criteria. Invoke ## Method -1. **Prepare.** Read repository documentation and official documentation for the installed packages and frameworks involved in the change. Follow their recommended APIs and patterns unless an explicit project decision requires a different approach. Load and apply [$modular-design](../modular-design/SKILL.md). +1. **Prepare.** Read repository documentation and official documentation for the installed packages and frameworks involved in the change. Follow their recommended APIs and patterns unless an explicit project decision requires a different approach. Before writing meaningful bespoke code for a common, reusable application capability, invoke [$select-packages](../select-packages/SKILL.md) unless a known adequate solution already covers it. Use the recommendation to install and integrate justified packages within the authorised change. Resolve material evidence gaps before dependent work. Load and apply [$modular-design](../modular-design/SKILL.md). 2. **Implement.** Load [$test-design](../test-design/SKILL.md) and follow its applicability decision and method. Implement the confirmed change and simplify locally as it takes shape. When new tests are ineligible, use existing checks and direct verification. 3. **Improve.** Once the change works, invoke [$measure-code-complexity](../measure-code-complexity/SKILL.md) on the changed production files, using the branch base for file selection. Pass its saved report and interpretation to [$code-cleanup](../code-cleanup/SKILL.md) with the fixed candidate and affected capability. Read the returned report file and adjudicate every candidate, including changes in related unchanged files. Resolve preservation gaps before applying accepted transformations. 4. **Verify and review.** Run required repository checks and the complete relevant existing suite. Invoke [$code-review](../code-review/SKILL.md) on the resulting candidate with its behavioural authorities and quality evidence. Read the returned report file. Check its assessment status and coverage before resolving its findings. Refresh an incomplete or stale review before treating the candidate as independently reviewed. diff --git a/skills/select-packages/SKILL.md b/skills/select-packages/SKILL.md new file mode 100644 index 0000000..bb5e2bb --- /dev/null +++ b/skills/select-packages/SKILL.md @@ -0,0 +1,26 @@ +--- +name: select-packages +description: Recommend packages when a common, reusable application capability could otherwise require meaningful bespoke code. +--- + +# Select packages + +Delegate **read-only package selection** to a fresh agent. Return a succinct recommendation that avoids unnecessary owned code and dependency burden. Keep candidate research outside the caller's context. + +If explicitly assigned as the selector, follow [candidate evaluation](references/selection.md) directly without further delegation. + +## Inputs + +Take the problem or feature, required behaviour and project constraints from the request or caller handoff. A known adequate project, framework or native capability needs no new search. Routine edits, trivial helpers and project-specific business rules usually do not warrant invocation. + +## Method + +1. **Brief fresh.** Give a fresh agent this skill's path, the requirement, relevant project paths, constraints and source access. Use fresh context rather than inheriting the conversation. Authorise only read-only inspection and browsing. Request the recommendation defined below, with no report or scratch files. +2. **Keep the boundary.** The selector owns discovery, evaluation and source verification. Relay material user-held questions through the caller. Continue independent work where possible, then wait for the result before dependent implementation. +3. **Check the handoff.** Require a clear recommendation tied to the requirement, with canonical links and any material limitation. Return unsupported claims or missing coverage to the selector. Leave installation, integration and behaviour verification to the caller. + +## Finish + +Return one short bullet per recommended package, with its name, canonical link and requirement-specific reason, or `No packages recommended.` with a brief reason. Add only material caveats or evidence gaps. Omit implementation instructions, supporting-link inventories, candidate catalogues and research narratives. + +**Done only when** the fresh agent has completed candidate evaluation and returned a supported succinct recommendation, or identified the exact missing evidence or constraint preventing one. An incomplete search cannot establish that no suitable package exists. diff --git a/skills/select-packages/agents/openai.yaml b/skills/select-packages/agents/openai.yaml new file mode 100644 index 0000000..72ed987 --- /dev/null +++ b/skills/select-packages/agents/openai.yaml @@ -0,0 +1,3 @@ +interface: + display_name: 'Select Packages' + short_description: 'Delegate read-only package discovery and selection' diff --git a/skills/select-packages/references/selection.md b/skills/select-packages/references/selection.md new file mode 100644 index 0000000..bbad18f --- /dev/null +++ b/skills/select-packages/references/selection.md @@ -0,0 +1,34 @@ +# Candidate evaluation + +Perform this assignment directly. Use read-only project inspection and browsing. Preserve files, dependencies and Git state. Do not install or execute candidate code, run probes, create scratch files or save reports. Return material user-held questions to the caller before dependent conclusions. + +## Discover relevant solutions + +1. Establish the required behaviour, decisive edge cases and target environment. Inspect supplied project paths for constraints, existing usage, manifests and lockfiles. Resolve discoverable facts before asking questions. +2. Check project, framework and native capabilities first. If one already meets the requirement with less burden, conclude without external discovery. Date formatting supported by the runtime needs no new library. A robust document parser may warrant one. A short rule unique to the product can remain local. +3. Search relevant ecosystem registries, official integrations and upstream documentation by capability and likely synonyms. Verify remembered names against the canonical project and registry entry. Check plausible alternatives rather than accepting the first result. Broaden the search while a material requirement or viable alternative remains unresolved. Stop when the leading options can be judged and further discovery is unlikely to change the recommendation. An unavailable source or empty query is not evidence that no package exists. + +## Evaluate on evidence + +Read current primary sources for every criterion that could change the choice. Evaluate the relevant package version and intended use. Keep documented claims distinct from verified facts and inference. + +| Criterion | What to establish | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Functional fit | Required semantics, edge cases, failure behaviour and API coverage. A feature name alone does not establish fit. | +| Compatibility | Runtime, language, platform, framework peers, build system, module format and types. Check documented support against project constraints. | +| Maintenance and maturity | Support policy, releases, deprecations and responses to relevant defects. Infrequent releases can indicate finished software. Unresolved consequential defects and unsupported targets matter more than frequency. | +| Identity and security | Canonical registry coordinates, upstream ownership, relevant version advisories and installation or build behaviour. Check available provenance where relevant. No advisory match or security score guarantees safety. | +| Licence | Applicable terms and notices against project policy and intended distribution. Unclear rights remain a material gap. | +| Dependency burden | Incremental direct, transitive, peer and build dependencies, conflicts and relevant size, runtime, service or deployment costs. | +| Integration quality | Public API, version-specific documentation, types, relevant upstream tests and required configuration or adapters. | +| Local alternative | The code, edge cases, tests and expertise the project would own, compared with package integration, upgrade and replacement work. | + +Use stars, downloads and release frequency as contextual signals. Apply no universal popularity thresholds or numeric eligibility score. Reject a material incompatibility or unacceptable constraint rather than averaging it into a favourable result. Do not claim installed compatibility, measured performance or tested behaviour from documentation alone. + +## Choose and return + +Recommend packages only when the evidence supports the requirement and they reduce total justified implementation and maintenance burden. Include multiple packages only when they serve necessary complementary roles. Select a solution rather than returning competing candidates for the caller to evaluate again. Prefer adequate existing capabilities or small local rules when a dependency adds more burden than it removes. Do not prescribe a wrapper without a real integration need. + +Follow the succinct output format in the skill's Finish section. Include a supported version or range when it materially affects the choice. For `No packages recommended.`, briefly identify the adequate existing capability, justified local approach or disqualifying constraint. If evidence is insufficient, identify the exact gap instead of implying that no suitable package exists or endorsing an unsupported local implementation. + +**Done only when** relevant existing capabilities and leading plausible candidates have been assessed against all decisive criteria, sources have been checked, and the succinct result states the supported recommendation or its exact blocker. Leave installation and behavioural verification with the caller. diff --git a/skills/specify-feature/SKILL.md b/skills/specify-feature/SKILL.md index 0145dc9..98dc951 100644 --- a/skills/specify-feature/SKILL.md +++ b/skills/specify-feature/SKILL.md @@ -15,7 +15,7 @@ Take the feature from the request and its supplied context, including confirmed 1. **Prepare coverage.** Read [feature discovery](references/discovery.md) and [the specification template](assets/specification-template.md) before mapping the decision tree. Resolve discoverable facts through inspection or [$research](../research/SKILL.md). 2. **Elicit intent.** Invoke [$elicit-with-context](../elicit-with-context/SKILL.md) for the feature's scoped behaviour and constraints, using the discovery guidance. Use **goal-oriented use cases** and **Example Mapping** to connect flows, rules, examples and open questions. -3. **Settle the consequential solution.** Resolve choices that change observable behaviour, shared contracts, state ownership, safeguards, migration, verification or ticket dependencies. Invoke [$modular-design](../modular-design/SKILL.md) for material ownership and interface choices. Record the selected approach, load-bearing contracts, reasons and relevant rejected alternatives. Leave reversible internal coding choices and the per-slice implementation plan to tickets. Reopen intent when design exposes a gap. +3. **Settle the consequential solution.** Resolve choices that change observable behaviour, shared contracts, state ownership, safeguards, migration, verification or ticket dependencies. Invoke [$select-packages](../select-packages/SKILL.md) when a package choice affects the consequential solution. Invoke [$modular-design](../modular-design/SKILL.md) for material ownership and interface choices. Record the selected approach, load-bearing contracts, reasons and relevant rejected alternatives. Leave reversible internal coding choices and the per-slice implementation plan to tickets. Reopen intent when design exposes a gap. 4. **Check the complete specification.** Check rules against concrete acceptance examples and inherited constraints. Supply feature intent and the consequential solution to the active dialogue for confirmation. 5. **Write and connect.** Invoke [$write-prose](../write-prose/SKILL.md) with confirmed decisions, evidence and template. Follow project document conventions, defaulting to `docs/features//specification.md`. Link precise authorities and give referenced requirements stable IDs. When a matching product-index entry exists, fill its specification link. Preserve existing ticket checklists during revisions and report affected tickets when a decision changes.