Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
2 changes: 2 additions & 0 deletions skills/code-cleanup/references/review.md
Original file line number Diff line number Diff line change
Expand Up @@ -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-<unique-id>.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.
Expand Down
2 changes: 1 addition & 1 deletion skills/implement/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
26 changes: 26 additions & 0 deletions skills/select-packages/SKILL.md
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions skills/select-packages/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
interface:
display_name: 'Select Packages'
short_description: 'Delegate read-only package discovery and selection'
34 changes: 34 additions & 0 deletions skills/select-packages/references/selection.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion skills/specify-feature/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<feature-slug>/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.

Expand Down
Loading