diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 553cf6c..37348b3 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -2,7 +2,7 @@ "$schema": "./node_modules/oxfmt/configuration_schema.json", "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], "printWidth": 80, - "proseWrap": "never", + "proseWrap": "preserve", "tabWidth": 4, "singleQuote": true, "sortImports": { diff --git a/AGENTS.md b/AGENTS.md index 38f53f3..4321b5f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,7 @@ -- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. -- When authoring or reviewing a skill, justify its behaviour using only context available to the agent at runtime. +- When a user correction establishes a reusable repository-wide rule, ask whether to invoke `$maintain-agents` to add it. +- When authoring or reviewing a skill, include only runtime instructions and knowledge for its agent; exclude authoring rationale, evaluation history, and composition discussion, and justify behaviour only with runtime-available context. +- When eliciting within a software project, invoke `$elicit-with-context` instead of `$elicit`; use `$elicit` directly only for non-software work or as part of `$elicit-with-context`. +- When composing skills, rely on each invoked skill's public contract; do not restate or steer its internal logic. +- Default to a user-agent workflow; introduce team roles, named accountable people, approval bodies, or third-party coordination only when the user or project evidence requires them. +- Assume the execution harness supports fresh agents; do not add fallback handling for their unavailability. - After implementing changes run `bun run checks` before handoff. diff --git a/CONTEXT.md b/CONTEXT.md deleted file mode 100644 index fa2742b..0000000 --- a/CONTEXT.md +++ /dev/null @@ -1,135 +0,0 @@ -# Propulsion - -Propulsion is an agentic coding workflow composed of skills that steer a coding agent through repeatable engineering work. - -## Language - -**Predictability**: The degree to which a skill makes the agent follow the same process on every run, without requiring the same output.\ -_Avoid_: Consistency, output determinism - -**User-invoked skill**: A skill the user selects explicitly. This is the default skill type in Propulsion.\ -_Avoid_: Manual skill, command - -**Model-invoked skill**: A skill the agent may select autonomously or invoke from another skill. Use this exception only when autonomous discovery would naturally help during ordinary coding work often enough to earn its permanent context cost.\ -_Avoid_: Automatic skill - -**Invocation policy**: Client-specific metadata within a skill bundle that controls whether an agent may select that skill implicitly. The same intent may require different policy fields in different clients.\ -_Avoid_: Invocation flag, frontmatter setting - -**Skill-only distribution**: Distributing Propulsion directly as Agent Skills, using the skills installer for remote sources and filesystem links for local sources. Propulsion does not require client-specific plugin packaging.\ -_Avoid_: Plugin distribution - -**Elicitation**: Requirements elicitation adapted to establish discoverable facts, resolve a dependency-ordered decision tree with the user, and confirm shared understanding before downstream action.\ -_Avoid_: Interrogation, clarification - -**Theoretical saturation**: The point at which further elicitation within the agreed scope reveals no new material decisions, allowing the shared understanding to be presented for confirmation.\ -_Avoid_: Question limit, exhaustive questioning - -**Main success scenario**: The representative invocation path that delivers a skill's intended outcome and remains dominant during design, refinement, and forward testing.\ -_Avoid_: Every possible path, exhaustive scenario set - -**Material exception**: A non-common path that earns explicit skill behaviour because representative evidence, the main success scenario, or a necessary safety or permission boundary requires it. Speculative variation remains agent judgement.\ -_Avoid_: Edge case, hypothetical branch - -### Skill anatomy - -**Authoring workflow**: A skill that guides an agent through creating or updating another skill with an explicit process. It makes execution predictable without prescribing the authored skill's outcome.\ -_Avoid_: Design guide, skill reference - -**Composable skill**: An independently useful skill that may be invoked alone or coordinated by another skill without requiring the rest of a prescribed workflow.\ -_Avoid_: Workflow stage, mandatory step - -**Router skill**: A lightweight skill that invokes other skills to produce a combined outcome. It contains only coordination unique to that outcome; called skills remain authoritative and the router neither repeats nor overrides their context.\ -_Avoid_: Pipeline skill - -**Implement skill**: The user-invoked workflow that coordinates a confirmed implementation through TDD and independent code review. It technically adjudicates review findings, remediates required corrections, accepts optional improvements only when proportionate, and elicits user intent when a finding would change behaviour, contracts, architecture, or scope. - -**TDD skill**: The model-invoked workflow that applies red-green-refactor when an existing runnable test suite can exercise the behaviour change through a stable public seam. It uses Test Desiderata to favour valuable tests that respond to behaviour without coupling to code structure. - -**Code-review skill**: The model-invoked workflow that assesses a scoped code change independently for requirements and code health, then reports evidence-validated findings including code smells and refactor opportunities without changing the code.\ -_Avoid_: Review skill - -**Review-architecture skill**: The user-invoked workflow that analyses a project's architecture and produces an HTML report of high-value, context-aware redesign opportunities without changing the implementation.\ -_Avoid_: Improve-architecture skill - -**Architecture review report**: A single-file interactive artifact named `docs/architecture/YYYYMMDD-{scope}-architecture-review.html` that guides the user through a small set of prioritised recommendations in concise plain language. It uses visualisation and progressive disclosure to explain affected architecture, expected improvements, evidence, and trade-offs without presenting a wall of technical detail. Verified CDN dependencies may supply scripts, styles, fonts, and diagram libraries.\ -_Avoid_: Static architecture audit - -**Architecture module**: A cohesive capability with a small explicit contract and a hidden implementation. Other modules depend on the contract rather than its internal classes, adapters, or framework wiring.\ -_Avoid_: Directory, namespace - -**Deep module**: An architecture module whose small, stable interface hides substantial cohesive implementation. The implementation may be decomposed into focused internal actions for reuse and maintainability without exposing that decomposition to consumers.\ -_Avoid_: Large class, shallow module - -**Debug skill**: The model-invoked workflow that reproduces a code issue, establishes its root cause, applies the smallest correction, and verifies the result. An explicit diagnosis-only request stops before mutation.\ -_Avoid_: Diagnose skill - -**Maintain-agents skill**: The user-invoked workflow that creates or aggressively compresses the root `AGENTS.md` into project-wide runtime guidance and one canonical completion check. It removes narrower workflows from permanent context and reports their appropriate destinations. - -**Define-product skill**: The user-invoked workflow that inspects existing product knowledge, composes contextual elicitation and conditional research, and maintains a root `PRODUCT.md` plus canonical language in `CONTEXT.md`. Concise strategic framing leads into a journey-organised catalogue of high-level feature descriptions without becoming a delivery plan. - -**Primary source**: Original high-trust evidence such as official documentation, source code, standards, publications, first-party APIs, or first-party data. Secondary sources may aid discovery but findings trace their claims back to primary evidence.\ -_Avoid_: Trusted write-up - -**Research report**: A cited Markdown snapshot named `docs/research/YYYYMMDD-{research-title}.md` that answers a research question from primary evidence and records its scope, findings, and unresolved limitations. Substantive re-research creates a linked superseding snapshot; minor corrections update the existing report and its metadata.\ -_Avoid_: Research answer - -**Research skill**: The model-invoked rapid evidence assessment workflow that gives a fresh agent ownership of primary-source discovery, appraisal, synthesis, and report writing. The caller verifies the cited research report and receives its concise findings; other skills invoke it only when the evidence warrants that durable record.\ -_Avoid_: Web search - -**Description**: A concise statement of what a skill does and the conditions under which it should be invoked.\ -_Avoid_: Summary, tagline - -**Skill name**: A short command that states the skill's action and fits naturally into a user instruction. Prefer one imperative verb, then a short imperative phrase, with established nouns reserved for operations they already name clearly.\ -_Avoid_: Title, label - -**Branch**: A distinct route through a skill for a particular use case or condition. Branches share the skill's common process without duplicating it.\ -_Avoid_: Separate workflow, mode - -**Process section**: The required `## Process` section that contains a skill's instructions. It uses numbered subheadings only when order matters and descriptive subheadings or direct prose otherwise.\ -_Avoid_: Steps section, instructions section - -**Leading word**: A recognised term from an established method, principle, theory, or technique, specific enough to invoke the agent's existing knowledge without further explanation. A skill explains only its context-specific adaptation or constraints.\ -_Avoid_: Coined term, theme, slogan - -**Governing methodology**: An established methodology selected through research to determine a skill's process when one credibly fits. Research may conclude that none is suitable; a selected methodology appears by canonical name in the skill without source attribution.\ -_Avoid_: Core concept, main theme - -**Supporting concept**: An established principle, theory, or technique that reinforces the governing methodology for a distinct concern without competing with it.\ -_Avoid_: Secondary concept - -**Skills plan**: The self-contained high-level handoff for Propulsion's fixed v1 skill suite. It records suite principles, the skill catalogue and standard briefs, composition and invocation, implementation order, and acceptance criteria without carrying source citations, discarded scope, or finished skill instructions.\ -_Avoid_: Skill specification, backlog - -**Lossless compression**: Reducing a skill to the fewest words and structures that preserve its behaviour, conditions, constraints, and technical meaning.\ -_Avoid_: Trimming, shortening, minimalism - -**Degrees of freedom**: The amount of judgement a skill leaves to the agent. Match it to the work's fragility so the process is predictable without predetermining valid outcomes.\ -_Avoid_: Flexibility, strictness - -**Ironic process theory**: The tendency for a negated concept to become more salient. Skills state the positive target behaviour and pair an essential safety boundary with the safe action that satisfies it.\ -_Avoid_: Prohibition-only rule, negative prompting - -**Prerequisite**: A condition that must be true before a skill can begin. Its failure stops the skill or routes the work elsewhere.\ -_Avoid_: Setup step, pre-flight check - -**Step**: A numbered subheading used when actions within a process or branch must occur in order. It isolates one coherent behavioural concern, describes the action, and ends in an observable postcondition.\ -_Avoid_: Instruction, rule - -**Postcondition**: An observable state that marks a step complete without requiring a separate completion section.\ -_Avoid_: Completion criterion, completion gate - -**Rule**: A cross-cutting invariant that constrains multiple instructions or the finished output.\ -_Avoid_: Step, reminder - -**Handoff**: A transfer or route that becomes available after the skill's process is complete.\ -_Avoid_: Next step, final step - -**Reference**: Conditional or extensive runtime guidance linked once beside a precise loading condition. The agent loads it only when that branch or decision needs the additional depth.\ -_Avoid_: Background, resource - -**Acceptance testing**: A semantic validation that traces every elicited invocation through a finished skill's branches, resource pointers, and observable postconditions.\ -_Avoid_: Checklist, structural validation - -**Characterization testing**: Capturing an existing skill's observable invocation and process before improvement so intentional changes remain distinct from regressions.\ -_Avoid_: Snapshot, preservation rule diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..984a19d --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,39 @@ +# Propulsion Glossary + +## Language + +### Skill model + +**Predictability**: The degree to which a skill makes the agent follow the same process on every run, without requiring the same output. + +**User-invoked skill**: A skill the user selects explicitly. This is Propulsion's default invocation mode. + +**Model-invoked skill**: A skill the agent may select autonomously or invoke from another skill. Use this exception only when autonomous discovery would naturally help during ordinary coding work often enough to earn its permanent context cost. + +**Invocation policy**: Client-specific metadata within a skill bundle that controls whether an agent may select that skill implicitly. The same intent may require different policy fields in different clients. + +### Skill types + +**Skill type**: The authority category recorded in a skill's frontmatter as `metadata.type`. Propulsion uses exactly `performer`, `router`, `teaching`, or `utility`. + +**Performer skill**: Owns one bounded requested outcome end to end, including its actions, artefacts, verification, handoff, and stopping boundary. + +**Router skill**: Resolves the inputs needed to coordinate other skills and returns their results. It contains only routing unique to that outcome; called skills remain authoritative and the router neither repeats nor overrides their context. + +**Teaching skill**: Supplies knowledge and decision rules inside a caller's workflow. It does not own an independent operation, mutation, artefact, verification, handoff, or stopping decision. + +**Utility skill**: Owns one bounded reusable operation and returns its result, whether the operation runs in the calling agent, a fresh agent, or a deterministic tool. + +### 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. + +### Skill benchmarking + +**Authentic workflow arm**: One isolated benchmark run that gives a skill set the same implementation task, starting repository, model, tools, permissions, and environment as the other arms while allowing it to load and follow its own required skills and workflow. + +**Adaptive single-run comparison**: One fresh run per benchmark arm, followed by another run only for an arm whose result is tied, failed, or surprising enough that run-to-run variation could materially change the conclusion. + +**Skill-context tokens**: The exact tokenizer count of a benchmark arm's skill discovery metadata and every skill or reference file loaded during the run, reported separately from whole-run model usage. + +**Runtime token usage**: The execution harness's complete input, cached-input, output, and reasoning-output token counts for one benchmark arm, excluding the independent quality evaluator. diff --git a/README.md b/README.md index 5bc3e80..9a95d7d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,11 @@ # Propulsion -Propulsion is a compact skill set for agentic coding. It gives coding agents a stronger workflow. +Propulsion is a compact, composable set of Agent Skills for practical software delivery. It supports the realistic lifecycle around coding—from establishing a product and defining features to creating tickets, implementation, and debugging. + +Each skill runs one bounded working session and stops with an independently useful outcome. You can enter wherever the necessary inputs already exist and leave when that outcome is complete. + +Substantial work narrows breadth-first over several sessions: product intent becomes a decision-complete feature specification, then implementation-ready tickets, and finally one implemented body of work per ticket. Small, understood work can begin directly with `$implement`. ## Installation @@ -27,51 +31,143 @@ ln -s /absolute/path/to/propulsion/skills/elicit ~/.agents/skills/elicit Repeat the link for each selected skill. Codex and OpenCode both discover skills from `~/.agents/skills`; edits in the clone are available through the links without reinstalling or publishing a new version. -## Usage +## Lifecycle skills + +The lifecycle areas below are independent entry points, not mandatory phase gates. Invoke the skill for the outcome you need, later stages do not start automatically. + +### Establish + +#### `$define-product` + +Enter here to establish or deliberately revise the product and system requirements foundation: + +```text +$define-product +``` + +The session produces a user-confirmed `PRODUCT.md` and the corresponding project language in `GLOSSARY.md`. It stops before defining individual features, selecting feature-specific architecture, or creating tickets. + +### Define + +#### `$specify-feature` + +Enter here when a high-level feature request needs enough behavioural and technical definition for planning: + +```text +$specify-feature +``` + +The session produces one approved, decision-complete feature specification containing visibly distinct feature intent and selected solution sections. No earlier lifecycle artefact is mandatory, and the skill stops before ticket creation or implementation. + +### Plan + +#### `$create-tickets` + +Enter here when an approved document or confirmed conversation is complete enough to decompose without inventing behaviour or material solution decisions: + +```text +$create-tickets +``` -Propulsion skills are independently invocable. For most feature and change requests, use this recommended workflow: +The session creates and verifies small, vertically sliced, dependency-aware tickets with Fibonacci complexity in the destination named by the project's root `AGENTS.md`. It stops before scheduling or implementing them. -1. Shape the idea with `$elicit-with-context` until the request is understood and confirmed. +Local Markdown destinations use one file per ticket under `docs/features//tickets/`. External destinations use their native items, estimates, relationships, and statuses. If `AGENTS.md` does not name the destination, the skill asks and records it. - ```text - $elicit-with-context Help me work through an idea for . - ``` +### Refine -2. Implement the confirmed request with `$implement`. +#### `$review-architecture` - ```text - $implement the request we just confirmed. - ``` +Enter here to assess an explicitly bounded part of the current architecture: -3. Review the working-tree changes yourself. Ask the agent to explain or adjust anything necessary, and repeat until you are satisfied with the result. +```text +$review-architecture +``` -4. Commit the reviewed changes, then create the pull request. +The session produces an evidence-backed report containing a small number of prioritised, high-value improvements and their trade-offs. It does not refactor the code or create speculative tickets. - ```text - $commit the reviewed changes. - Create a $pr for the current branch. - ``` +### Deliver -### Alternative entry points +#### `$implement` -For a bug, start with `$debug` instead of elicitation and implementation: +Enter here with one ticket or another small, confirmed body of work: ```text -$debug Fix . +$implement ``` -After the repair, rejoin the recommended workflow at human review, followed by `$commit` and `$pr`. +The session produces a minimal local change with retained tests, applicable quality evidence, and completed independent review. Small, understood work can begin here without a product definition, feature specification, or ticket. Implementation does not commit or publish the change. -For codebase improvements, start with `$review-architecture` to produce an architecture report: +`$implement` applies `$modular-design`, uses `$tdd` for behaviour-changing work when a usable suite can exercise it, and requires an independent `$code-review`. `$tdd` applies the reusable `$test-design` teaching for durable behavioural tests. Implementation uses existing project infrastructure and reports unavailable evidence instead of installing unrelated tooling or manufacturing confidence. + +#### `$commit` + +Enter here when eligible reviewed work is ready to be recorded: ```text -$review-architecture Review for high-value architecture improvements. +$commit ``` -Review the report, then take each accepted recommendation through the recommended workflow separately, beginning with `$elicit-with-context`. +The session creates and verifies coherent Conventional Commits while preserving unrelated staged, unstaged, and untracked work. It does not push or open a pull request. + +#### `$pull-request` + +Enter here when the current branch is ready to publish for human review: + +```text +$pull-request +``` + +The session commits eligible remaining work when needed, pushes the branch, and creates or updates one pull request describing the complete branch. It does not merge, release, or deploy the work. + +A substantial feature commonly moves through separate sessions: + +```text +$specify-feature + → later $create-tickets + → $implement each selected ticket + → $commit whenever a coherent unit is ready + → $pull-request when the branch is ready +``` + +A small, understood change may start later: + +```text +$implement → $commit → $pull-request +``` + +### Debug + +#### `$debug` + +Enter here with observed and expected behaviour or another usable failure signal: + +```text +$debug +``` + +The session establishes an evidence-backed root cause and stops there when diagnosis is the requested outcome. When repair is authorised, it produces a minimal, reviewed local change with regression evidence and stops before commit or publication. + +```text +$debug → $commit → $pull-request +``` + +## Supporting skills + +These utilities and routers are independently invokable outside the main lifecycle path and may also be composed by lifecycle skills when their trigger applies. + +| Skill | Type | Invoke it to… | +| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `$review-pull-request` | Router | Independently assess someone else's pinned pull request without changing their branch or publishing a review unless requested | +| `$elicit` | Utility | Resolve material user-held information and decisions one question at a time | +| `$elicit-with-context` | Router | Resolve software-project questions through `$elicit`, always maintaining shared language and preserving qualifying decisions | +| `$research` | Utility | Investigate a material subject with high-trust evidence and persist a trusted cited report | +| `$maintain-agents` | Utility | Keep confirmed repository-wide agent guidance lean and current | + +Use `$elicit-with-context` to work through questions or decisions within a software project. For non-software work, use `$elicit`. ## Acknowledgements -Propulsion is heavily inspired by: +Propulsion is heavily inspired by other great skill sets: -- [mattpocock/skills](https://github.com/mattpocock/skills) for brevity, wording discipline, and the question-by-question discovery style +- [obra/superpowers](https://github.com/obra/superpowers) +- [mattpocock/skills](https://github.com/mattpocock/skills) diff --git a/bun.lock b/bun.lock index 050f596..8d0c7df 100644 --- a/bun.lock +++ b/bun.lock @@ -8,6 +8,8 @@ "oxfmt": "^0.59.0", "oxlint": "^1.74.0", "oxlint-tsgolint": "^0.24.0", + "semver": "7.8.5", + "tiktoken": "1.0.22", }, }, }, @@ -106,6 +108,10 @@ "oxlint-tsgolint": ["oxlint-tsgolint@0.24.0", "", { "optionalDependencies": { "@oxlint-tsgolint/darwin-arm64": "0.24.0", "@oxlint-tsgolint/darwin-x64": "0.24.0", "@oxlint-tsgolint/linux-arm64": "0.24.0", "@oxlint-tsgolint/linux-x64": "0.24.0", "@oxlint-tsgolint/win32-arm64": "0.24.0", "@oxlint-tsgolint/win32-x64": "0.24.0" }, "bin": { "tsgolint": "bin/tsgolint.js" } }, "sha512-giCk5sEvG02d5tzPmFMX3hem8ndzEEu1xvGYS5OwNfO2WGl6ZVxt5LjE0yiMDoz94INI7XkXwgFAQiydPvVHDw=="], + "semver": ["semver@7.8.5", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA=="], + + "tiktoken": ["tiktoken@1.0.22", "", {}, "sha512-PKvy1rVF1RibfF3JlXBSP0Jrcw2uq3yXdgcEXtKTYn3QJ/cBRBHDnrJ5jHky+MENZ6DIPwNUGWpkVx+7joCpNA=="], + "tinypool": ["tinypool@2.1.0", "", {}, "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw=="], } } diff --git a/package.json b/package.json index 55f6f9c..13a19a5 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,9 @@ "devDependencies": { "oxfmt": "^0.59.0", "oxlint": "^1.74.0", - "oxlint-tsgolint": "^0.24.0" + "oxlint-tsgolint": "^0.24.0", + "semver": "7.8.5", + "tiktoken": "1.0.22" }, "packageManager": "bun@1.3.11" } diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 083740b..b0a8565 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,63 +1,79 @@ --- name: code-review -description: Reviews scoped code changes against a specification and applicable standards. Use when assessing a diff, branch, pull request, or completed implementation. +description: Reviews a fixed code change through isolated specification and engineering-standards agents. Use when a fixed candidate needs independent diagnostic review. metadata: - invocation: model -disable-model-invocation: false + type: utility +disable-model-invocation: true --- # Code Review -**Tailored software formal inspection** prepares fixed evidence packets for independent Standards and Spec inspectors, then presents their diagnostic findings without changing the reviewed work. +Independently diagnoses one fixed code change against intended behaviour and engineering standards, returning falsifiable suggestions for its caller to adjudicate. ## Process -### 1. Fix the inspection scope +### 1. Fix the candidate and authorities -Use the caller-supplied scope, whether uncommitted work, a revision range, a branch comparison, a pull request, or another exact change set. Resolve every revision, capture the patch and changed-path list once through read-only inspection, and include the complete contents of in-scope untracked files. Confirm that the captured change set is non-empty. Ask the user when the scope is missing or ambiguous; report the exact blocker and stop when it is invalid or empty. The inspection has one fixed work product. +Use the caller's pinned candidate when supplied; otherwise resolve one exact non-empty diff, revision range, branch comparison, pull-request revision, repair, or local candidate. Capture its patch, changed and in-scope untracked paths, complete changed files, relevant source and tests, repository state, and exact revision identifiers where available. Ask when the target is materially ambiguous. Return the exact blocker when it is empty or cannot be fixed. -### 2. Resolve the inspection sources +Resolve intended behaviour from an implementation-independent authority such as a specification, ticket, acceptance criteria, confirmed request, contract, or another project source. When none is reasonably available, omit Spec and continue Standards without inferring intent from code, commits, or implementation rationale. -Find the specification from caller context, supplied paths or tickets, issue references and change history, then relevant repository documentation. When none is found, ask the user; omit the Spec inspection only after the user confirms that no specification exists. Independently identify applicable repository instructions, architecture decisions, coding standards, language policies, configured checks, and local conventions. Read the changed files in full, relevant tests, and enough surrounding code to judge the patch. The specification and Standards authorities are explicit. +Resolve applicable repository instructions, conventions, architecture decisions, configured checks, affected contracts and consumers, and supplied quality evidence. The review basis is explicit and sufficient to understand every changed line in context. -### 3. Prepare the work aids +### 2. Prepare isolated review packets -Create one self-contained packet per applicable axis with the fixed patch, changed paths, relevant source context, authority sources, priority definitions, output schema, and read-only verification boundary. Exclude conversation history and the other inspector's materials. +Give both applicable packets the fixed candidate, complete changed files and necessary surrounding source, their own authorities and criteria, the consequence ranking and finding format below, and a read-only boundary. -The Spec packet applies **bidirectional requirements traceability**: trace every applicable requirement into the changed implementation and relevant tests, and every introduced behaviour back to specification authority. It investigates missing, partial, incorrect, conflicting, and unrequested behaviour and relevant unhandled cases. +Direct the Spec reviewer to account for every applicable requirement in code and retained tests, account for every introduced behaviour against authority, and follow affected contracts, states, data shapes, errors, effects, and consumers far enough to find missing, partial, conflicting, excessive, or regressed behaviour. Trace distinct success, failure, retry, and concurrent paths when the authority distinguishes them. When an external effect precedes durable state or acknowledgement, trace failure after the effect and before that record or response, including what a retry repeats. Report separate suggestions when a different triggering state, violated requirement, consequence, or narrow corrective outcome survives review, even if the evidence overlaps another suggestion. -The Standards packet applies repository standards first, then residual **Google code-review criteria** across whole-change understanding, correctness and concurrency risks, test presence and validity, comments, and affected documentation. Include the complete [Fowler code-smell work aid](references/CODE-SMELLS.md). Add **Test Desiderata** when tests change; the relevant **ISO/IEC 25010:2023** characteristic when the repository adopts it or the change exposes a concrete residual product-quality concern; an applicable **SEI CERT** rule when supported-language code exposes its construct; and the relevant frozen **OWASP ASVS 5.0.0** requirement when Web code crosses that security boundary. Load only the implicated part of a conditional benchmark. +Direct the Standards reviewer to understand every changed line in its necessary context and assess: -When the fixed change alters modular architecture, invoke `$modular-design` and include the applicable standard in the Standards packet. +- correctness and regression risk; +- the smallest coherent scope and absence of speculative or superseded work; +- repository, language, and framework conventions; +- changed-test validity, independent oracles, behavioural durability, and meaningful failure detection; +- modular ownership, interface depth, dependencies, and change locality; +- repository-required and changed-risk harness selection, measurement-path integrity, and honest evidence limits; and +- recognised maintainability shapes and specialist risks exposed by the change. -Within Standards, repository rules and demonstrably configured tooling govern the concerns they cover. General work aids fill uncovered diagnostic roles and yield to an explicit repository choice. A smell or benchmark cue begins an investigation; it becomes a finding only when the scoped code supplies exact evidence and a concrete consequence. +Require the Standards reviewer to load and apply `$modular-design` and `$test-design`. When a concrete maintainability shape needs recognised vocabulary, load [Code Smells](references/CODE-SMELLS.md); use it to investigate a mechanism and consequence, never as finding authority or a removal checklist. -### 4. Assign the inspections +Require the Standards reviewer to invoke `$measure-code-complexity` against the fixed candidate and comparison base with read-only authority. Treat its current output as diagnostic evidence: inspect each trigger in source and test context, and retain a review suggestion only when a concrete maintainability consequence survives falsification. Report unavailable or incomplete measurement in the review limitations. -Give each packet to a separate fresh agent and run the Standards and Spec inspections in parallel when both apply. Each inspector owns candidate discovery, **falsification**, authority and code-evidence validation, consequence analysis, and priority validation for its axis. It may run a targeted check only when the command and execution boundary demonstrate that it cannot mutate the checkout, repository state, external systems, or durable project data; otherwise it records the limitation. Each inspector returns only findings that survive its validation. +### 3. Run independent reviews -Use **risk-based prioritisation** within each axis: `critical` for immediate data loss, security compromise, or production failure; `high` for incorrect requirements or major behaviour, security, reliability, or maintenance risk; `medium` for a concrete defect or significant code, design, or test weakness; and `low` for a local but worthwhile issue. +Give each applicable packet to a separate fresh agent and run them in parallel where possible. Do not substitute coordinator self-review. If fresh-agent execution is unavailable, mark the affected axis not performed and state the exact limitation. -### 5. Present the inspection report +Each reviewer may run a safe, focused, non-mutating command only to confirm or falsify a concrete concern. It does not repeat the implementation's whole quality portfolio, edit code or tests, update snapshots or baselines, install dependencies, modify durable data, or repair a finding. -Check that each assigned packet produced the required output fields, returning an incomplete report to its originating inspector for completion from the same packet. Present the Standards and Spec outputs separately without substantive re-review, merging, deduplication, or cross-axis reranking. Preserve each inspector's findings and ordering. The caller receives the two independent inspection results. +Before retaining a suggestion, try to disprove it through contradicting authority, existing handling, repository-sanctioned exceptions, surrounding code, a focused counterexample, and the strongest benign interpretation. Omit unsupported generic advice, tooling-enforced trivia, speculative best practice, and a pre-existing issue unless the candidate introduces, worsens, or makes it newly consequential. -## Rules +Rank each surviving suggestion by consequence: -- Keep the inspection read-only and return evidence for the caller's implementation process. -- Report only issues introduced by or materially relevant to the fixed change. -- Prefer specification, repository, and code evidence over general guidance or personal preference. -- Hold structural, test, security, and product-quality findings to the same evidence, consequence, and priority standard as behavioural defects. +- **High:** a credible path to materially wrong required behaviour, including a duplicated, lost, or misdirected external effect; security or privacy compromise; data loss or corruption; major production or reliability failure; or a structural, test, or evidence defect that makes the change untrustworthy. +- **Medium:** a concrete defect, regression risk, or significant maintainability, modularity, test-quality, or harness-integrity weakness with a bounded material consequence. +- **Low:** a local evidenced issue whose narrow correction has a concrete benefit. + +Priority orders attention only; it does not direct remediation. + +### 4. Preserve the results and candidate + +Validate only that each result uses the required fields. Return an incomplete result to that same reviewer for structural completion from its original packet. Do not substantively re-review, merge, deduplicate, suppress, or cross-axis rerank the independent results. + +Reinspect the fixed revisions, diff, paths, and in-scope untracked content. When the candidate drifted, preserve each affected frozen result, prefix it with `Status: stale`, state the changed paths and basis mismatch, and stop without retargeting it. ## Handoff -State the exact scope, specification source or user-confirmed absence, Standards sources, and any check that could not run. Return `## Standards` and `## Spec`; use `No findings.` for a clean axis and state when the Spec inspection was omitted. Format each finding as: +State the exact frozen scope, behavioural authority or reason Spec was omitted, Standards authorities, probes and limitations, unperformed axes, and scope drift. Return `## Standards` and `## Spec` separately; for an applicable current clean axis use `No findings.` and for an omitted, unperformed, or stale axis state that status explicitly. + +Format each suggestion as: ```markdown -### [priority] Concise finding +### [high|medium|low] Concise finding -- Evidence: exact code `path:line`, applicable authority, and observed fact -- Consequence: concrete behaviour or code-health impact +- Evidence: exact code location, applicable authority or criterion, and observed fact +- Consequence: concrete behavioural or code-health impact +- Suggested direction: narrow outcome that addresses the concern without prescribing an unverified patch ``` -End with `## Summary` and the finding count for each axis. When neither axis contains a material finding, say the fixed change is clean plainly. +End with axis-specific counts and review scope. Return the reviewers' substance and ordering unchanged. Do not repair the candidate, adjudicate suggestions, issue a verification, completion, or approval verdict, publish comments, or alter pull-request state. The caller owns validation, adjudication, remediation, re-review, verification, and publication. diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml index a243ba1..6c2a385 100644 --- a/skills/code-review/agents/openai.yaml +++ b/skills/code-review/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Code Review' - short_description: 'Review code against standards and specification' + short_description: 'Independently review a fixed code change' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/code-review/references/CODE-SMELLS.md b/skills/code-review/references/CODE-SMELLS.md index 38e2b5d..3185738 100644 --- a/skills/code-review/references/CODE-SMELLS.md +++ b/skills/code-review/references/CODE-SMELLS.md @@ -1,6 +1,6 @@ # Fowler Code Smells -Use this complete second-edition catalogue as a diagnostic work aid for the Standards inspection. Each cue identifies a code shape to investigate, not a finding by itself. Test the relevant benign interpretation against the scoped code, repository authorities, and concrete consequence. +Load this complete second-edition catalogue only when a concrete maintainability shape needs recognised diagnostic vocabulary. Each cue identifies a code shape to investigate, not a finding or authority by itself. Test the relevant benign interpretation against the scoped code, repository authorities, and concrete consequence. 1. **Mysterious Name** — An identifier does not communicate its role, meaning, or unit in the surrounding domain. A repository-defined term or tightly conventional local name may already be precise. 2. **Duplicated Code** — Materially similar behaviour appears in multiple locations that may need to evolve together. Superficially similar code may represent different responsibilities or change for different reasons. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 8756033..907fd6a 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,29 +1,17 @@ --- name: commit -description: Creates coherent Conventional Commits from eligible changed work. Use to commit reviewed changes. +description: Creates atomic Conventional Commits for eligible reviewed work while preserving unrelated changes. Use when completed local work is ready to record. metadata: - invocation: user + type: utility disable-model-invocation: true --- # Commit -**Conventional Commits** turns eligible changed work into coherent commits whose messages state each change's intent. +Records eligible local work in coherent commits without disturbing unrelated changes. ## Process -### 1. Inspect the changed work +Assign the entire process below to one fresh agent with the user's request and repository path; when already inside the fresh agent for an enclosing operation, perform it there. Use only repository evidence to inspect the complete Git state and diffs, group eligible work by intent into atomic **Conventional Commits**, preserve unrelated staged, unstaged, and untracked work, and let commit hooks run. The work is already reviewed and verified; do not run tests, project checks, or implementation verification. Verify only each commit and the final Git status, then return only the hashes, titles, and remaining work. Retain only that result. -Inspect repository instructions, the current Git state, staged, unstaged, and untracked changes, and recent commit subjects. Apply any requested scope or message constraint. When no eligible change remains, report it and stop; otherwise the complete candidate work is explicit. - -### 2. Group coherent changes - -Partition the candidate work into **atomic commits** by coherent intent. Keep changes together when they serve the same purpose and leave unrelated or ambiguous work untouched. Each group has one explainable purpose. - -### 3. Create the commits - -For each group, stage its exact files or hunks, inspect the staged diff, and commit it with an accurate `type[(scope)][!]: description` message using the repository's Git setup. Ask before altering ambiguous user-staged work. On failure, preserve the resulting Git state and report the blocker. - -### 4. Verify the result - -Verify each created commit and inspect the remaining status. Return each hash and subject plus any work left uncommitted. +Stop without changing the implementation, pushing, or opening a pull request. diff --git a/skills/commit/agents/openai.yaml b/skills/commit/agents/openai.yaml index 9eca7b4..e9c29a0 100644 --- a/skills/commit/agents/openai.yaml +++ b/skills/commit/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Commit' - short_description: 'Create coherent conventional commits' + short_description: 'Create atomic conventional commits' policy: allow_implicit_invocation: false diff --git a/skills/create-tickets/SKILL.md b/skills/create-tickets/SKILL.md new file mode 100644 index 0000000..f2906ab --- /dev/null +++ b/skills/create-tickets/SKILL.md @@ -0,0 +1,49 @@ +--- +name: create-tickets +description: Creates implementation-ready tickets from approved work. Use when a complete work definition needs vertical decomposition in the project's configured ticket system. +metadata: + type: performer +disable-model-invocation: true +--- + +# Create Tickets + +Turns one **approved work definition** into a confirmed, verified set of small vertical tickets. A work definition may be a document or confirmed conversation whose outcome, scope, behaviour or obligations, material constraints, and solution decisions are complete enough to decompose without invention. + +## Prerequisites + +Read the root `AGENTS.md` for an explicit ticket destination such as `The project uses Linear for tickets.` or `The project uses local Markdown for tickets.` When absent, ask the user which destination the project uses, invoke `$maintain-agents` with the answer, and resume from its result. For an external destination, require its installed integration and writable account; otherwise stop with the exact access needed. Never guess or silently fall back. + +## Process + +### 1. Establish the work and destination + +Use the already-loaded root guidance. Inspect the request, approved work definition, and only the additional linked product, context, decision, research, and current-system evidence needed to understand the work. Treat the definition as authority for intended outcomes and settled constraints, and the repository as evidence of the current system. + +For an external destination, inspect its native item, body, status, estimate, parent, dependency, and read-back capabilities before planning writes. For local Markdown, use one file per ticket under `docs/features//tickets/`. + +### 2. Agree the vertical ticket set + +Map every material requirement, obligation, constraint, solution responsibility, transition, and acceptance boundary in both directions between the work definition and proposed tickets. Form the smallest coherent set in which each ticket delivers one observable outcome or fulfilled contract across every layer it needs. Absorb shared setup into the earliest outcome that needs it. Create separate enabling, migration, or refactor work only when it has an independently necessary, verifiable boundary or preserves a valid compatible intermediate state. + +Size each ticket for one fresh implementation session. Assign one project-local **complexity** bucket from `1`, `2`, `3`, `5`, or `8` by comparing the affected behaviour, technical difficulty, integrations, data or migration work, applicable quality constraints, and bounded uncertainty with the other proposed tickets. The buckets are ordered comparisons, not ratios, hours, dates, or duration promises. Split any outcome that would exceed `8`, then estimate the resulting slices again. + +Add a blocker only when one ticket cannot honestly begin or meet acceptance before another reaches its accepted outcome. Keep display order, likely sequence, user-journey order, and merely related work out of the dependency graph. State dependency direction explicitly and reject cycles. + +Present only a compact numbered proposal containing each ticket's stable title, vertical outcome, complexity, and `Blocked by` references. Invoke `$elicit-with-context` when supported alternatives require a user decomposition decision. Iterate the compact set until the user confirms the whole proposal; do not synthesize full bodies first. Confirmation authorises the agreed synthesis and writes without another application prompt. If synthesis exposes a material gap, leave the destination unchanged and reopen the affected proposal. + +### 3. Synthesize and write the tickets + +Use the [Ticket Template](assets/ticket-template.md) as the minimum semantic body, omitting only inapplicable conditional content. Embed the necessary confirmed intent and solution context when no durable authority exists; never tell a fresh implementation agent to recover an unavailable conversation. Explain what must be delivered at stable boundaries without prescribing files, classes, framework wiring, code, or an exhaustive test inventory. + +For local Markdown, allocate stable sequential identifiers such as `TKT-001`, use `-.md`, set new tickets to `Todo`, and write reciprocal `Blocked by` and `Blocks` references. The local status vocabulary is `Todo`, `In Progress`, `Done`, and `Cancelled`. + +For an external destination, use the closest established initial native status and map complexity, blocker, blocked, and parent meanings to exact native fields when available. When an exact capability is absent, retain the meaning explicitly in the body and surface the limitation; never substitute a different relation. Do not set priority, assignee, sprint or cycle, milestone, release, or dates unless the approved definition or user supplies them. + +Create and relate exactly the confirmed set. + +### 4. Read back, verify, and stop + +Read every created ticket and relationship back from its destination. Verify the confirmed titles, outcomes, authority or embedded context, requirements, applicable constraints, acceptance criteria, complexity values and ceiling, status, relationship meanings and directions, acyclic dependencies, resolved local references, and two-way work-definition coverage. Correct an exact in-scope discrepancy when the agreed value and target are unambiguous; otherwise stop with the mismatch and required decision or capability. + +Return the created ticket links or local paths, verification performed, capability limitations, source limitations, and unresolved external state. Stop without changing the approved work definition, scheduling or prioritising work, implementing, committing, publishing, releasing, or deploying. diff --git a/skills/create-tickets/agents/openai.yaml b/skills/create-tickets/agents/openai.yaml new file mode 100644 index 0000000..4f7072c --- /dev/null +++ b/skills/create-tickets/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: 'Create Tickets' + short_description: 'Create implementation-ready vertical tickets' + default_prompt: 'Use $create-tickets to turn this approved work definition into confirmed, implementation-ready tickets.' +policy: + allow_implicit_invocation: false diff --git a/skills/create-tickets/assets/ticket-template.md b/skills/create-tickets/assets/ticket-template.md new file mode 100644 index 0000000..52a9413 --- /dev/null +++ b/skills/create-tickets/assets/ticket-template.md @@ -0,0 +1,29 @@ +# {TKT-001} — {Ticket title} + +- **Status:** {Todo or destination-native status} +- **Complexity:** {1, 2, 3, 5, or 8} +- **Blocked by:** {Ticket references or None} +- **Blocks:** {Ticket references or None} +- **Authority:** {Durable work-definition link and identifiers, or concise embedded authority context} + +## Outcome + +{One independently observable vertical result or fulfilled contract.} + +## Context + +{Only the bounded actors, current state, settled solution constraints, non-goals, and source details a fresh implementation session cannot infer safely.} + +## Functional requirements + +- {Approved behaviour or rule owned by this ticket.} + +## Non-functional requirements + + + +- {Constraint in its operating context with an observable response or measure where established.} + +## Acceptance criteria + +- [ ] {Observable pass/fail condition at a user, assistive-technology, contract, event, migration, persistence, provider, or operating boundary.} diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 0e125e7..6de1def 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -1,37 +1,67 @@ --- name: debug -description: Reproduces, isolates, repairs, and verifies code issues. Use when debugging failures, regressions, runtime errors, or incorrect behaviour. +description: Diagnoses software defects and conditionally makes causal, verified repairs. Use for failures, regressions, runtime errors, flaky behaviour, or performance faults. metadata: - invocation: model -disable-model-invocation: false + type: performer +disable-model-invocation: true --- # Debug -**Scientific debugging** turns a repeatable failing signal into a verified causal repair through falsifiable hypotheses, predicted observations, and discriminating experiments. +Diagnoses a defect through discriminating evidence and, when requested, produces one minimal reviewed local repair. ## Process -### 1. Establish a repeatable signal +### 1. Fix the outcome and signal -Read repository instructions and establish the authorised scope, expected behaviour, observed behaviour, and exact verdict that distinguishes them. Run the smallest reliable reproduction and record its invocation or probe, input, environment, expected verdict, and observed verdict. A failing test, benchmark, trace, log pattern, captured artefact, or targeted external probe may supply the signal when a local reproduction cannot. Use [Debugging Techniques](references/TECHNIQUES.md) when the signal or next experiment is not obvious; for an intermittent or concurrent fault, component or production boundary, or performance regression, load [Nondeterministic Faults](references/NONDETERMINISTIC.md), [Boundary Evidence](references/BOUNDARY-EVIDENCE.md), or [Performance Faults](references/PERFORMANCE.md) respectively. Preserve pre-existing user work and identify the mutation boundary for later repair attempts. When no reliable signal can be established, leave the implementation unchanged and report the evidence, blocker, and next discriminating experiment. The original fault has a repeatable red signal or an explicit evidence boundary. +Read the request, repository instructions, expected and observed behaviour, failing evidence, environment, relevant authorities, current code, and tests. Resolve whether the requested outcome is diagnosis only or diagnosis plus repair. Invoke `$elicit-with-context` only when a material user-held fact or decision remains. -### 2. Isolate the root cause +Keep production and external systems read-only and within explicit authority. When diagnosis or mitigation needs external mutation, report the required action and stop; production mitigation, deployment, and monitoring remain outside this skill. -Gather evidence and state falsifiable causal hypotheses in evidence-supported order. For the leading hypothesis, state the observation it predicts, then run the cheapest experiment that distinguishes it from the credible alternatives. Change one variable and record the hypothesis, prediction, experiment, and observation. Treat an observation that does not discriminate as an incomplete experiment and sharpen it before continuing. Repeat until the evidence supports one leading cause strongly enough to justify a minimal repair experiment. The cause, causal mechanism, and evidence against symptom-level alternatives are explicit. +Define the best available **signal**: a focused test, command, error, trace, captured artefact, controlled benchmark, safe observation, or measured failure rate. Record its invocation or provenance, input, environment, expected result, observed result, and fidelity limits. Run it before changing implementation when safe. Prefer a sharp repeatable reproduction, but accept authorised captured, external, or probabilistic evidence when that is the honest boundary. Preserve the original unminimised signal through the investigation. If no evidence can distinguish the reported defect, leave implementation unchanged and return the exact gap and next smallest experiment. -### 3. Test one repair +### 2. Narrow the cause -When the user requested diagnosis only, stop before mutation and follow the Handoff. Invoke `$modular-design` when the supported repair changes modular architecture. Invoke `$tdd` when its runnable-suite and stable-seam prerequisite applies; preserve the established reproduction as its Red signal and let it own the minimal Green repair and regression protection. When TDD is not applicable, apply one smallest change that would repair the leading cause if the hypothesis is correct. Keep the attempt within the authorised mutation boundary and leave unrelated cleanup or refactoring outside it. One evidence-led repair is ready for a causal verdict. +Build a small model of the relevant path, contracts, state, boundaries, and recent code, configuration, dependency, environment, data, or workload changes. Treat recent change, suspicious location, correlation, and a passing retry as hypotheses or observations, never as proof. -### 4. Accept or revert the repair +Maintain one compact investigation record containing observations, a small ranked set of causal hypotheses, the active prediction, the experiment, its result, its implication, and contradictory evidence. Test one prediction at a time with the smallest safe experiment that distinguishes credible alternatives. Prefer changing one factor while preserving the signal's material conditions. -Run the original signal. When it changes as predicted, retain the repair provisionally and continue to verification. When it remains red or changes for a different reason, record the contradictory evidence and revert only the production, configuration, and throwaway-test changes introduced by that attempt; preserve the established reproduction and all pre-existing user work. Reconsider the hypotheses, experiment, system boundary, or architecture whenever the observations no longer support the causal model, then return to isolation without stacking another repair onto the failed one. The working tree contains either one supported repair or no residue from an unsuccessful attempt. +Select the reference whose trigger matches the current uncertainty and load only that reference. Return its evidence to this causal loop before selecting another: -### 5. Verify and clean up +| Evidence shape | Load | +| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| Multiple plausible explanations remain | [Hypothesis-Driven Experiments](references/HYPOTHESIS-EXPERIMENTS.md) | +| A component, pipeline, request, or data path has observable boundaries | [Boundary Isolation](references/BOUNDARY-ISOLATION.md) | +| Reliable known-good and known-bad ordered states exist | [Change Bisection](references/CHANGE-BISECTION.md) | +| A large input, state, sequence, trace, or change set can be reduced | [Delta Debugging](references/DELTA-DEBUGGING.md) | +| Invalid state appears downstream of where it originated | [Origin Tracking](references/ORIGIN-TRACKING.md) | +| A credible working case can be compared with the failing case | [Comparative Debugging](references/COMPARATIVE-DEBUGGING.md) | +| Existing evidence cannot distinguish the active hypotheses | [Instrumentation and Debuggers](references/INSTRUMENTATION-DEBUGGERS.md) | +| Outcome depends on timing, order, randomness, load, or shared state | [Nondeterministic and Concurrent Faults](references/NONDETERMINISTIC-CONCURRENT.md) | +| The signal is latency, throughput, contention, exhaustion, leakage, or resource cost | [Performance and Resource Faults](references/PERFORMANCE-RESOURCE.md) | -Re-run the original unminimised reproduction, focused regression coverage, relevant nearby checks, and the repository-prescribed wider checks. Remove temporary instrumentation and throwaway harnesses, or retain them deliberately as documented diagnostics. Separate unrelated pre-existing failures from repair regressions. The original fault and causal account are confirmed by the evidence, the smallest supported repair remains, and relevant checks pass; otherwise the exact remaining failure and uncertainty are explicit. +When the shape is unclear, verify the signal and inspect recent changes, then compare a working case, isolate boundaries, reduce the reproducer, trace the first invalid state, and finally add targeted probes. Enter nondeterministic or performance guidance immediately when its trigger applies. Combine techniques only when each answers a distinct unresolved question. + +Continue until the evidence explains the causal mechanism and accounts proportionately for the strongest alternatives. A root cause may be a set of jointly necessary conditions rather than one deepest line. If the next discriminating experiment is unsafe, unavailable, outside authority, or no longer economical, stop with the supported findings, uncertainty, and exact next experiment. Invoke `$research` only when a material external-knowledge question requires a durable cited report. + +### 3. Close diagnosis or repair one cause + +Remove owned temporary probes, captures, fixtures, and experimental edits, retaining a diagnostic only when project authority makes it durable and safe. State the supported cause, mechanism, trigger conditions, evidence for and against the material alternatives, contradictions, confidence boundary, and remaining unknowns. For diagnosis-only work, state that implementation was not changed and stop. + +For an authorised repair, apply `$modular-design` to keep the change with the natural owner and limit propagation. Select one minimal change directed at the supported cause; exclude unrelated cleanup, broad refactoring, speculative hardening, and other plausible defects. + +Apply `$tdd` when its prerequisites hold. The established signal supplies Red only when it independently specifies the desired observable behaviour and fails for that reason; a crash, trace, log, profile, or implementation-derived expectation does not automatically qualify. Otherwise use the strongest existing project-native feedback without claiming TDD or creating project-wide test infrastructure. + +Run the original signal against the repair. Retain the attempt only when the result changes as the causal account predicted. When it does not, record the contradiction, revert only the exact changes owned by that attempt without disturbing pre-existing work, and return to the causal loop. Do not stack another unsupported fix. + +### 4. Review and verify the local repair + +Freeze the complete candidate, intended-behaviour authority, causal account, original signal, regression evidence, selected quality evidence, changed and untracked paths, and repository state. Invoke `$code-review` on that exact candidate. Adjudicate every finding against the request, authorities, causal evidence, and current code. Correct supported required findings, ask the user about material behaviour, architecture, or scope decisions, and reject unsupported or out-of-scope findings with concrete evidence. + +After any candidate change, rerun the original signal and affected harnesses, re-freeze the candidate, and repeat independent review. Complete only when the current candidate has no unresolved required finding; the focused regression passes; the original unminimised signal changes as predicted; applicable repository and risk-triggered checks have been run; and unavailable or inconclusive evidence remains explicit. Do not turn green checks into universal proof. ## Handoff -Report the expected and observed behaviour, original failing signal, hypotheses, predictions, experiments and observations, root cause and causal mechanism, reverted attempts, retained change, regression protection, verification commands and results, and any blocker or unresolved uncertainty. For diagnosis-only work, state plainly that no implementation was changed. +Return the requested outcome; expected and observed behaviour; authority and environment boundary; original signal; hypotheses, predictions, experiments, contradictions, and reverted attempts; causal mechanism or exact evidence gap; retained change and regression protection; quality evidence and limitations; review scope and dispositions; residual risk; and next discriminating experiment or follow-up. Include one brief prevention observation only when it follows directly from the established cause; do not create an automatic postmortem or wider programme. + +For diagnosis-only work, state that implementation was unchanged. Stop after the diagnosis or reviewed verified local repair without committing, changing tracker state, publishing, deploying, mutating production, or monitoring. diff --git a/skills/debug/agents/openai.yaml b/skills/debug/agents/openai.yaml index bac6c82..412d7c6 100644 --- a/skills/debug/agents/openai.yaml +++ b/skills/debug/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Debug' - short_description: 'Debug issues through verified repair' + short_description: 'Find causal defects and verify local repairs' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/debug/references/BOUNDARY-EVIDENCE.md b/skills/debug/references/BOUNDARY-EVIDENCE.md deleted file mode 100644 index 35ad9aa..0000000 --- a/skills/debug/references/BOUNDARY-EVIDENCE.md +++ /dev/null @@ -1,23 +0,0 @@ -# Boundary Evidence - -Use this reference when the fault crosses components, processes, services, environments, or an authorised production boundary. The goal is to identify the earliest boundary whose observed output or invariant diverges, using the least sensitive evidence that distinguishes the hypotheses. - -## Trace one event - -Map the smallest relevant path and select one request, event, job, or transaction. Preserve its correlation identifier and environment or version context. At only the boundaries that distinguish the leading hypotheses, record applicable input, output, state, configuration, timing, status, and correlation. - -Apply **backward causal tracing** from the symptom until the earliest invalid transition is visible. Continue inside that component rather than widening instrumentation across the whole system. Treat missing, sampled, or uncorrelated telemetry as an evidence limitation rather than a healthy verdict. - -## Capture and replay safely - -Capture the smallest authorised request, event, trace, payload, or state slice. Redact secrets and unnecessary personal or production data before retaining it; preserve an external pointer or correlation identifier when the workspace is not authorised to store the artefact. - -Replay at the nearest stable seam only when the replay preserves the hypothesis-relevant environment, ordering, dependencies, identity, and state. Record every fidelity gap. When replay would erase the suspected cause, prefer a targeted external probe or temporary boundary instrumentation within the user's authority. - -When the next discriminating observation requires new access, privileged instrumentation, or production mutation, leave implementation unchanged and report the required evidence and authority as a blocker. - -## Clean up and verify - -Tag temporary probes so they can be found mechanically. Remove them after diagnosis, or retain them deliberately as documented diagnostics with an explicit data and access boundary. Re-run the original correlated event or nearest faithful reproduction after repair, then verify focused regression and repository checks. - -If a repair does not move the earliest divergent boundary as predicted, record the result and revert the attempt before revising the causal path. diff --git a/skills/debug/references/BOUNDARY-ISOLATION.md b/skills/debug/references/BOUNDARY-ISOLATION.md new file mode 100644 index 0000000..0809d81 --- /dev/null +++ b/skills/debug/references/BOUNDARY-ISOLATION.md @@ -0,0 +1,17 @@ +# Boundary Isolation + +Use this reference when a failure crosses a short component, process, service, pipeline, request, or data path with observable boundaries. The result is the earliest boundary where a valid state or invariant becomes invalid. + +## Narrow the path + +Map the smallest relevant path and define the expected input, output, state, and invariant at each material boundary. Follow one request, event, job, transaction, or datum using its correlation identity and environment or version context. + +For a short path, walk boundaries in order. For a large path with trustworthy midpoints, observe the midpoint, keep the failing half, and repeat. Inject or replay known data only when doing so preserves the conditions relevant to the hypothesis. + +Capture only the fields needed to distinguish the current hypotheses. Treat absent, sampled, delayed, or uncorrelated telemetry as an evidence limitation rather than a healthy result. Redact secrets and unnecessary personal or production data; retain an external pointer when the workspace cannot store the artefact safely. + +## Transfer the result + +A divergent boundary localises the fault but does not explain the internal cause. Record the last valid state, first invalid state, correlation evidence, replay fidelity gaps, and components excluded. Then return to the main causal loop and use origin tracking, comparison, or a targeted experiment inside the remaining boundary. + +Stop when one component or transition remains, or when the next observation needs unavailable access or external mutation. Remove owned temporary boundary probes after use. If a repair does not move the earliest divergence as predicted, reject the repair hypothesis. diff --git a/skills/debug/references/CHANGE-BISECTION.md b/skills/debug/references/CHANGE-BISECTION.md new file mode 100644 index 0000000..83427f0 --- /dev/null +++ b/skills/debug/references/CHANGE-BISECTION.md @@ -0,0 +1,17 @@ +# Change Bisection + +Use this reference when the same crisp property is reliably absent in one ordered state and present in another. States may be revisions, versions, configurations, datasets, or ordered inputs. The result is the smallest reliably classified transition. + +## Freeze the classifier + +Define one command or observation that classifies a state as good, bad, or untestable against the original signal. Confirm trustworthy endpoints before searching. A flaky, environment-sensitive, or changed classifier invalidates ordinary bisection; stabilise it or route to nondeterministic guidance first. + +Test the midpoint, retain its exact state and verdict, keep the half containing the transition, and repeat. For Git history, prefer the repository's supported build and test procedure; use `git bisect run` only when the command's exit statuses faithfully encode good, bad, and untestable. Preserve the log and exit bisect state when finished. + +Apply any compatibility adjustment consistently and keep it separate from the states under test. Do not discard unrelated work or rewrite a user's worktree to make historical states runnable; use an isolated worktree or disposable copy when necessary. + +## Interpret the boundary + +Skipped or broken states near the boundary may leave several candidate transitions. Non-monotonic behaviour or interacting changes may make the result misleading. Environment drift can cause an old state to receive the wrong verdict. + +The first bad state is localisation evidence, not automatic root cause. Inspect the semantic difference and run a discriminating experiment that connects it to the causal mechanism. Stop when the transition is reliable or when the remaining untestable range is explicit. diff --git a/skills/debug/references/COMPARATIVE-DEBUGGING.md b/skills/debug/references/COMPARATIVE-DEBUGGING.md new file mode 100644 index 0000000..da6bfbe --- /dev/null +++ b/skills/debug/references/COMPARATIVE-DEBUGGING.md @@ -0,0 +1,15 @@ +# Comparative Debugging + +Use this reference when a credible working version, implementation, configuration, platform, tenant, request, or input can be compared with the failing case. The result is the first material divergence relevant to the defect. + +## Control the comparison + +State why the comparator is trustworthy for the property under investigation. Hold inputs and environment stable where possible and list intentional differences before observing internal state. + +Compare external outcomes first. Then place equivalent checkpoints along both paths and narrow toward the first difference in output, state, dependency, configuration, control flow, or timing. When many differences exist, partition them or combine this technique with bisection. Reduce a differing case when a smaller comparison retains the same divergence. + +## Test the divergence + +Either side can be wrong, both can share a defect, and intentional or nondeterministic differences create noise. A difference therefore produces a causal candidate, not a verdict. + +Record the shared conditions, relevant differences, first divergence, and why later differences are consequences rather than causes. Return to origin tracking or a controlled hypothesis experiment that introduces or removes the divergence and predicts the original signal. Stop when the first explainable divergence is found or the comparator proves unreliable. diff --git a/skills/debug/references/DELTA-DEBUGGING.md b/skills/debug/references/DELTA-DEBUGGING.md new file mode 100644 index 0000000..dfc36ee --- /dev/null +++ b/skills/debug/references/DELTA-DEBUGGING.md @@ -0,0 +1,17 @@ +# Delta Debugging + +Use this reference when a large input, request, configuration, dataset, trace, sequence, state, or change set can be classified automatically or cheaply. The result is a smaller case that preserves the same failure. + +## Reduce against one oracle + +Freeze a classifier that distinguishes the exact failure from a pass and from an invalid or unresolved candidate. Remove a large partition, run the unchanged classifier, retain the removal only when the same failure remains, and increase granularity when a coarse partition cannot be removed. Continue with the reduced case. + +Preserve ordering and dependencies that make a candidate valid. Record unresolved candidates separately; do not treat them as passes or failures. For generated or fuzzed input, retain the seed and original counterexample before reducing it. + +Manual minimisation uses the same discipline: remove one coherent dimension at a time, retest, and keep only evidence-preserving reductions. Do not rewrite the oracle to accommodate a smaller case. + +## Preserve representativeness + +The result is minimal only relative to the tried partitions and granularity; it need not be globally smallest. Interdependent elements can prevent further reduction, and a reduced case can omit the interaction that makes the production scenario representative. + +Stop when no remaining unit can be removed at the chosen granularity without losing the exact signal, or when further reduction is more expensive than investigating the bounded case. Use the reduced case to localise or form hypotheses, but keep the original unminimised signal for repair verification. diff --git a/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md b/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md new file mode 100644 index 0000000..d0941cb --- /dev/null +++ b/skills/debug/references/HYPOTHESIS-EXPERIMENTS.md @@ -0,0 +1,23 @@ +# Hypothesis-Driven Experiments + +Use this reference when more than one causal explanation remains. The result is one observation that changes the ranked hypothesis set. + +## Form the prediction + +For each plausible cause, state the mechanism and the observation it predicts. Keep a small alternative set grounded in the current evidence; a file, line, component, or recent commit without an explanation is only a location. + +Choose the experiment that best partitions the credible alternatives for the least cost and risk. Prefer an invariant check, focused input change, controlled environment difference, intermediate value, or boundary observation over a repair attempt. Hold other material conditions stable. + +Record: + +- **Hypothesis:** the proposed causal mechanism. +- **Prediction:** the result expected if it is true and, where useful, if it is false. +- **Experiment:** the one controlled observation or intervention. +- **Result:** the exact observation, including conflicting or inconclusive data. +- **Implication:** supported, rejected, or not discriminated, plus the next ranked alternatives. + +## Interpret honestly + +An experiment supports only what its controls and oracle distinguish. A symptom disappearing after a code change may reflect masking, altered timing, or a bypassed path. A negative result is useful when the experiment was capable of exposing the proposed mechanism. + +Remove an owned experimental change after its observation unless it becomes the separately authorised causal repair. Stop when one causal account explains the full signal and trigger conditions and proportionate alternatives have been excluded, or when the next discriminating experiment crosses a named evidence, safety, or authority boundary. diff --git a/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md b/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md new file mode 100644 index 0000000..5f96641 --- /dev/null +++ b/skills/debug/references/INSTRUMENTATION-DEBUGGERS.md @@ -0,0 +1,24 @@ +# Instrumentation and Debuggers + +Use this reference when existing evidence cannot distinguish the active hypotheses. Tools are probes for a stated question, not the debugging method itself. The result is the smallest new observation that changes the causal model. + +## Select the probe + +Choose the instrument whose observation matches the question: + +| Question | Probe | +| ----------------------------------------------------------- | ------------------------------------------------------------------------- | +| Which local state or branch first violates an invariant? | Conditional breakpoint, watchpoint, or stack inspection | +| Where does one request cross a process or service boundary? | Correlated logs, metrics, trace, or narrow state endpoint | +| Which operation consumes CPU, memory, I/O, locks, or time? | Matching profiler, counter, or targeted runtime trace | +| Does a known fault class occur? | Repository-supported detector such as a race, memory, or query diagnostic | + +Place the fewest probes at boundaries, decisions, and state transitions that partition the hypotheses. Capture only the needed input, output, identity, correlation, time, and environment. Establish measurement overhead when the probe can affect the signal. + +## Preserve the evidence boundary + +Pausing can invalidate real-time or concurrent behaviour; logging can change timing; profiles are samples; multiple diagnostic tools can interfere. Prefer non-stopping tracepoints or record/replay only when the project and platform support them. + +Do not log credentials, tokens, keys, connection strings, or unnecessary personal data. Follow project retention and access rules, and keep production systems read-only. Tag temporary probes so they can be found and removed. + +Stop when the observation supports, rejects, or fails to discriminate the active hypotheses. Remove owned probes and sensitive captures after use, or retain a diagnostic deliberately within project authority. If the probe only produces more undirected data, sharpen the prediction before adding another. diff --git a/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md b/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md new file mode 100644 index 0000000..db65ac2 --- /dev/null +++ b/skills/debug/references/NONDETERMINISTIC-CONCURRENT.md @@ -0,0 +1,24 @@ +# Nondeterministic and Concurrent Faults + +Use this reference when nominally identical inputs produce different outcomes or the failure rate changes with timing, order, isolation, load, logging, randomness, clocks, network, shared state, or scheduling. The result is a controlled failure rate or a replayable causal execution, not one passing retry. + +## Measure and partition + +Run the exact trigger repeatedly. Record attempts, failures, seed, input, order, clock, load, resources, environment, and any captured schedule. Establish a baseline failure rate before changing code. + +Vary one likely source at a time: + +- replay or sweep randomness and generated inputs; +- permute test order and isolate shared files, ports, processes, or state; +- control time and wait for observable conditions rather than guessed delays; +- constrain parallelism or use a repository-supported race detector; +- capture, replay, or systematically explore schedules when tooling permits; or +- control load, resource pressure, network, filesystem, and dependency state. + +Use stress or injected delay only to amplify and capture a failure. Preserve the seed, order, trace, schedule, or invariant violation that makes the execution useful. + +## Interpret probability + +A passing sample does not prove absence. Added sleeps, longer timeouts, logging, and reduced parallelism can hide a race without removing its cause. Race detectors and schedule explorers cover only the behaviour and nondeterminism they observe or control. + +Stop reproduction when a failing execution is replayable or the measured rate is stable enough to compare discriminating experiments. Verify a repair first against the preserved failing execution, then repeat the original trigger under the same controls and report failures per attempts and remaining statistical uncertainty. Reject a repair that does not change the causal execution or measured rate as predicted. diff --git a/skills/debug/references/NONDETERMINISTIC.md b/skills/debug/references/NONDETERMINISTIC.md deleted file mode 100644 index ab0ac8d..0000000 --- a/skills/debug/references/NONDETERMINISTIC.md +++ /dev/null @@ -1,37 +0,0 @@ -# Nondeterministic Faults - -Use this reference for intermittent, flaky, timing-sensitive, order-dependent, or concurrent faults. The goal is a controlled failure rate or replayable causal execution, not one passing retry. - -## Measure the fault - -Run the exact trigger repeatedly and record attempts, failures, seed, order, clock, load, resources, environment, and any captured schedule. A useful signal either reproduces at a stable enough rate to compare experiments or preserves the execution that failed. - -Partition the likely nondeterminism before changing code: - -- randomness or generated input; -- test order, shared state, or leaked resources; -- clock, timeout, asynchronous condition, or event order; -- concurrent access or scheduling; -- load, resource pressure, network, filesystem, or environment. - -Vary one dimension and compare the failure rate or execution. Preserve every failing seed, order, input, and schedule that improves repeatability. - -## Select the experiment - -| Evidence | Technique | Causal evidence | -| --- | --- | --- | -| A seed or generated input controls the failure | Seed replay and counterexample reduction | The same input fails repeatedly and a minimised input preserves the verdict. | -| Test order or shared state is suspected | Order permutation and isolation probe | A specific predecessor, state, or unreleased resource changes the rate. | -| An asynchronous condition is suspected | Condition instrumentation and controlled perturbation | An observable state transition, rather than elapsed delay alone, determines success. | -| Unsynchronised access is possible | Repository-supported **race detector** | Conflicting accesses and their call paths identify the shared state to investigate. | -| A particular interleaving is suspected | Systematic, controlled, or recorded schedule | The captured schedule replays the failure and an alternative schedule discriminates the hypothesis. | - -Use stress, injected delay, parallelism, or load only to amplify and capture a failure. Stress without a retained input, schedule, trace, or invariant violation does not prove a cause, and a long passing run does not prove absence. - -Replace guessed delays with **condition-based waiting** only after evidence identifies the condition whose ordering is causal. A longer timeout that merely reduces the observed rate is not a confirmed repair. - -## Verify the repair - -Run the preserved failing seed, order, schedule, or trace first. Then repeat the original trigger under the same controls and compare failures per attempts; keep attempt counts proportionate to the prior rate and report the remaining uncertainty. Run focused regression and repository checks after the causal signal changes as predicted. - -If a repair does not change the preserved execution or measured rate as predicted, record the result and revert the attempt before testing the next hypothesis. diff --git a/skills/debug/references/ORIGIN-TRACKING.md b/skills/debug/references/ORIGIN-TRACKING.md new file mode 100644 index 0000000..5054b75 --- /dev/null +++ b/skills/debug/references/ORIGIN-TRACKING.md @@ -0,0 +1,23 @@ +# Origin Tracking + +Use this reference when a bad value, state transition, side effect, or decision is observed far downstream from where it arose. The result is the earliest demonstrated valid-to-invalid transition and its responsible conditions. + +## Trace backwards + +Start at the first observed invalid state. Identify its data definitions, callers, controlling conditions, prior state, and external inputs. Move backwards through the call and data flow, checking the relevant invariant at each step, until the last valid and first invalid states are adjacent. + +Choose the smallest project-native observation that can expose the transition: + +- a conditional breakpoint for a local state and condition; +- a watchpoint for an unexpected mutation; +- a targeted trace for a call or effect path; +- record/replay or reverse execution when the platform supports it; or +- a focused dynamic or static slice when many statements may influence the value. + +Record both the responsible operation and the inputs, state, ordering, or control condition that made it harmful. An assignment or stack frame alone is not a causal account. + +## Bound the claim + +Static slices may over-approximate, debugger facilities have platform and threading limits, and tracing can perturb execution. If instrumentation changes the failure, route that evidence through nondeterministic guidance. + +Stop at the earliest invalid transition that explains the downstream symptom. Return the transition and conditions to the hypothesis loop and test whether controlling them changes the original signal as predicted. diff --git a/skills/debug/references/PERFORMANCE-RESOURCE.md b/skills/debug/references/PERFORMANCE-RESOURCE.md new file mode 100644 index 0000000..79a28c4 --- /dev/null +++ b/skills/debug/references/PERFORMANCE-RESOURCE.md @@ -0,0 +1,25 @@ +# Performance and Resource Faults + +Use this reference when the defect is latency, throughput, CPU, memory, allocation, I/O, contention, queueing, exhaustion, leakage, query cost, or scale behaviour. The result is a measured causal connection between responsible work and the original user-visible regression. + +## Establish a representative signal + +Define the workload, environment, known-good baseline or expected threshold, warm-up, measurement interval, repetitions, and distribution that distinguishes the fault. Control input size and shape, concurrency, cache state, runtime version, machine resources, data volume, and other material conditions. Route a noisy classifier through nondeterministic guidance before trusting it. + +For early systemic triage, inspect utilization, saturation, and errors for each relevant resource. Then choose the measurement that matches the suspected cost: + +| Suspected cost | Evidence | +| ------------------------------------- | --------------------------------------------------------------- | +| CPU or call-path work | Sampling or instrumenting profile under the controlled workload | +| Memory or allocation | Heap, allocation, retention, or growth measurement | +| I/O, network, queue, or lock pressure | Resource counter and targeted trace | +| Database execution | Actual plan, cardinality, I/O, locks, and query timing | +| Version or configuration regression | Stable differential benchmark or change bisection | + +Connect the hotspot, plan, wait, saturation, or growth to the user-visible signal through a controlled workload or intervention. A hotspot is where cost was observed, not automatically why the system is slow. + +## Verify like with like + +Record measurement overhead and production cost. Long averages can hide bursts, profiles are samples, and one constrained resource can be traded for another. + +After one causal repair, rerun the identical workload and controls. Compare the full relevant distribution and low-level causal metric, then run functional regression evidence. Stop only when both move as predicted under the original representative workload. A faster result obtained by changing behaviour, workload, environment, or measurement does not verify the repair. diff --git a/skills/debug/references/PERFORMANCE.md b/skills/debug/references/PERFORMANCE.md deleted file mode 100644 index d648a72..0000000 --- a/skills/debug/references/PERFORMANCE.md +++ /dev/null @@ -1,28 +0,0 @@ -# Performance Faults - -Use this reference for latency, throughput, resource, query, or scale regressions. Measure a representative workload before selecting a profiler or changing code. - -## Establish the regression - -Define the workload, environment, expected threshold or known-good baseline, measured outcome, and variance that distinguishes the fault. Control input size, data shape, concurrency, cache state, runtime version, machine resources, and other material conditions. Warm up when the runtime requires it, repeat the measurement, and report the distribution rather than one timing. - -When known-good and known-bad states exist, use automated **bisection** with the same stable classifier. Treat noisy or untestable states explicitly; route a flaky classifier through [Nondeterministic Faults](NONDETERMINISTIC.md) before trusting its boundary. - -## Locate responsible work - -After the controlled benchmark proves the regression, choose the smallest instrument that distinguishes the hypotheses: - -| Suspected cost | Technique | Discriminating observation | -| --- | --- | --- | -| CPU or call-path work | Sampling or instrumenting profiler | The responsible stack or operation accounts for the measured difference. | -| Memory, allocation, I/O, lock, or network pressure | Resource counter or targeted trace | The relevant resource changes with the regression under the same workload. | -| Database work | Query plan and execution measurement | The plan, cardinality, I/O, lock, or execution step explains the difference. | -| Version or configuration change | Bisection or differential benchmark | The first ordered boundary preserves the same performance verdict. | - -Record measurement overhead and side effects. Use transactions or inert fixtures when an execution plan can mutate data. Profile the controlled workload; a profile from a different workload does not explain the measured regression. - -## Repair and verify - -Make one minimal change to the responsible work. Remeasure the identical workload and controls, compare the result and variance with the original baseline, then run functional regression and repository checks. A faster result that changes behaviour, workload, or environment does not verify the repair. - -If the measurement does not change as predicted, record the result and revert the attempt before revising the performance hypothesis. diff --git a/skills/debug/references/TECHNIQUES.md b/skills/debug/references/TECHNIQUES.md deleted file mode 100644 index 9cd3d5c..0000000 --- a/skills/debug/references/TECHNIQUES.md +++ /dev/null @@ -1,52 +0,0 @@ -# Debugging Techniques - -Use this reference when the repeatable failing signal or next discriminating experiment is not obvious. Identify the runtime situation, select the smallest technique that predicts a discriminating observation, retain its evidence, then return to the scientific-debugging loop. Combine techniques only when each settles a distinct question. - -## Tighten the Signal - -Run the signal at least once and record its command or probe, input, environment, expected verdict, and observed verdict. A useful signal is: - -- **specific:** it reaches the relevant path and asserts the reported symptom, rather than merely completing without an error; -- **repeatable:** it records the fixture, environment, seed, order, schedule, or captured artefact needed to reproduce the verdict; -- **measurable:** it is deterministic, or reports failures per attempts for a nondeterministic fault; -- **tight:** it removes unrelated setup and runs quickly enough to guide the next experiment; -- **runnable:** the agent can execute it unattended when the environment permits; otherwise it uses repeatable captured evidence or a targeted external probe; -- **safe:** production artefacts are minimised, redacted, and handled within the user's permissions. - -A passing retry does not turn an intermittent failure green. Use [Nondeterministic Faults](NONDETERMINISTIC.md) to control and compare the measured failure rate. - -## Construct a Signal - -| Situation | Technique | Observable verdict and retained artefact | -| --- | --- | --- | -| A stable test seam reaches the fault | Focused failing test or minimal harness | Assert the exact behaviour and preserve the smallest fixture. If retained as regression coverage, `$tdd` remains authoritative. | -| The fault is at an HTTP boundary | HTTP request script | Assert the relevant status, body, and headers; retain a redacted request and response rather than relying only on process exit. | -| The fault is a CLI contract | CLI invocation with fixture input | Assert exit status, stdout, and stderr as applicable; record flags, working directory, and relevant environment. | -| Only a production request or event exposes the fault | Capture and replay | Use [Boundary Evidence](BOUNDARY-EVIDENCE.md) to capture the smallest authorised event and assess replay fidelity. | -| The bad input is unknown or combinatorial | Property or fuzz loop | State an executable invariant, preserve the seed and failing input, then minimise the counterexample before diagnosis. | -| The failure is intermittent, order-dependent, concurrent, or timing-sensitive | Repetition, race detector, or controlled schedule | Use [Nondeterministic Faults](NONDETERMINISTIC.md) to measure the rate, partition nondeterminism, and capture a causal execution. | -| The fault crosses components or environments | Correlated boundary probe | Use [Boundary Evidence](BOUNDARY-EVIDENCE.md) to observe only the boundaries that distinguish the hypotheses. | -| The fault is performance | Controlled benchmark | Use [Performance Faults](PERFORMANCE.md) to establish a representative baseline and threshold before profiling. | -| The fault requires browser behaviour | Headless browser assertion or trace | Assert the relevant DOM, accessibility, console, request, response, screenshot, or timing outcome; retain the smallest trace and fixture. Use a structured human-in-the-loop transcript only when automation cannot perform or observe the essential step. | - -## Select an Experiment - -| Evidence | Experiment | Discriminating result | -| --- | --- | --- | -| A failing input, configuration, or sequence can be reduced | **Minimal reproducible example** or **delta debugging** | Remove partitions while preserving the exact verdict; the remaining elements bound the causal search space. | -| Known-good and known-bad states form an ordered space | **Binary search** or automated bisection | Use a stable good, bad, and untestable classifier across commits, versions, datasets, inputs, or configurations; record the first boundary found. | -| A comparable case works | **Differential testing** | Run the same input through both cases and isolate the smallest output, state, dependency, or configuration difference. Treat a difference as evidence to test, not proof by itself. | -| The symptom appears far from the bad value or action | **Backward causal tracing** | Follow the call and data flow from symptom to the earliest divergence, recording where the value entered and which invariant first failed. | -| The system crosses process or component boundaries | **Boundary instrumentation** | Follow [Boundary Evidence](BOUNDARY-EVIDENCE.md) and record hypothesis-relevant observations at the few boundaries that distinguish the candidates. | -| A value changes unexpectedly during execution | **Breakpoint**, **watchpoint**, or targeted trace | Pause at the earliest mutation or invariant violation and capture the responsible call path and state. | -| Timing, order, or scheduling is suspected | Controlled perturbation | Follow [Nondeterministic Faults](NONDETERMINISTIC.md) and vary one dimension while comparing the measured rate or captured schedule. | -| A controlled benchmark proves a regression | Profiler, query plan, or resource trace | Follow [Performance Faults](PERFORMANCE.md), identify the responsible work, and remeasure the identical workload after repair. | - -An experiment is complete when its observation confirms or rejects a stated hypothesis. If it only produces more data, sharpen the prediction or choose a different experiment. - -## Preserve Useful Evidence - -- Promote a minimised reproducer to regression protection at the strongest stable seam when appropriate; keep `$tdd` authoritative for the test and repair cycle. -- Remove temporary instrumentation and throwaway harnesses after use, or retain them deliberately as documented diagnostics. Tag temporary probes so cleanup is mechanically checkable. -- Store only sanitised captures and fixtures that the repository is authorised to retain. Report external artefacts without copying sensitive data into the workspace. -- Preserve the original reproduction across repair attempts. When a repair fails its prediction, retain the observation but revert the attempt before testing the next hypothesis. diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md index 32d42b0..fe09898 100644 --- a/skills/define-product/SKILL.md +++ b/skills/define-product/SKILL.md @@ -1,41 +1,63 @@ --- name: define-product -description: Discovers and maintains a durable product definition centred on high-level feature descriptions. Use when externalising a new product idea or refining an existing product. +description: Defines a breadth-first product and system requirements foundation. Use when externalising a new product idea or deliberately revising PRODUCT.md. metadata: - invocation: user + type: performer disable-model-invocation: true --- # Define Product -A product definition externalises product knowledge into a durable reference for later planning and development. Concise strategic framing leads into a complete catalogue of high-level features without becoming a delivery plan. +Turns a product idea or existing system into one confirmed `PRODUCT.md` that supplies product intent and system-wide requirements to later feature specifications. ## Process -### 1. Inspect existing knowledge +### 1. Establish the evidence boundary -Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, applicable research and decisions, and the smallest representative repository evidence. Treat code and tests as evidence of current behaviour and the user as the authority on intent; surface contradictions between them. Derive available facts before questioning so the user supplies decisions and knowledge the existing material cannot establish. The known product and unresolved discovery surface are explicit. +Locate the project root; read its repository guidance and check root `PRODUCT.md`, `GLOSSARY.md`, applicable ADRs and research. For an existing system, also inspect the smallest representative public contracts, entry points, data, tests, configuration, and operational evidence needed to understand the product. Record absent foundation files as absent evidence rather than skipping the check. -### 2. Frame the product +Treat the user as authority for intended direction, repository and runtime evidence as evidence of current behaviour, and cited external sources as authority only for the claims they establish. -Invoke `$elicit-with-context` and use the **Product Vision Board** dimensions to confirm the executive summary, vision, intended users and needs, value proposition, market position, business model, goals, success signals, pricing, boundaries, and non-goals. Invoke `$research` when external evidence could materially inform a decision about competitors, market conditions, pricing, regulation, or another product claim; keep its report authoritative and link applicable findings. When a framing dimension stalls, load only the relevant section of [Discovery Techniques](references/DISCOVERY.md). The concise product frame is user-confirmed and externally supported where material. +Separate confirmed target requirements, observed current behaviour, assumptions, and unknowns before questioning. Preserve unrelated confirmed content and local conventions when revising the foundation. When the current product is difficult to reconstruct, load [Discovery Techniques](references/DISCOVERY.md). The evidence, provenance, contradictions, and unresolved decisions are explicit. -### 3. Map the whole product +### 2. Elicit the breadth-first foundation -Use **User Story Mapping's big-picture techniques** without adopting its backlog or delivery workflow. Map the product mile-wide and inch-deep: inventory the known user-facing areas and candidate features before exploring any one feature in depth. Arrange the areas as a narrative backbone following the natural user journey; place a genuinely cross-cutting feature in the smallest coherent user-facing area rather than inventing a false sequence. Include observed features, confirmed direction, and product ideas from the inspected material and the user. Load the feature-mapping guidance in [Discovery Techniques](references/DISCOVERY.md) when the product surface is difficult to expose. The whole feature surface is visible at low resolution. +Invoke `$elicit-with-context` for material user-held information and decisions throughout steps 2–4. Reuse compatible confirmed answers and derive discoverable facts before questioning. Invoke `$research` when a material external claim could change a requirement and its evidence must persist; link the resulting report rather than copying it. -### 4. Explore each feature +Establish the foundation from problem to design inputs: -Work through the mapped features with `$elicit-with-context`, asking only for unresolved knowledge. For each feature, confirm its user value, high-level behaviour, meaningful boundaries, and one status: `Current` for observed product behaviour, `Confirmed direction` for intended behaviour the user has decided, or `Idea` for direction retained without commitment. Stop at the information needed for a concise feature description; leave prioritisation, sequencing, release slicing, estimates, tickets, architecture, implementation, user-story decomposition, and acceptance criteria to downstream work. Each feature is ready to become a self-contained mini-brief. +1. authority and executive orientation; +2. purpose, problem, vision, users, actors, stakeholders, and needs; +3. value, product and business goals, observable success measures, scope, boundaries, and non-goals; +4. current situation and confirmed target direction when an existing system makes the distinction material; +5. end-to-end journeys from entry through value, recovery, support, and completion or exit; +6. a whole-product functional capability catalogue; and +7. system-wide quality, context, interface, data, integration, security, privacy, safety, compliance, technology, platform, operational, and lifecycle requirements. -### 5. Walk the catalogue +Map the whole product before deepening any capability or technical concern. Omit a foundation concern only after establishing that it is immaterial. Record commercial or market detail only when it changes requirements. The product surface and every material system-wide design input are visible without becoming a feature specification. -Narrate the complete product journey area by area with the user. Correct missing, duplicate, misplaced, or contradictory features and resolve every exposed question through `$elicit-with-context`; represent genuine uncertainty through `Idea` and contextual product language rather than an unanswered-questions inventory. Obtain final confirmation of the strategic frame and complete feature catalogue. The product definition is coherent and ready to persist. +### 3. Shape traceable requirements -### 6. Write the product definition +Group capabilities under natural product areas. Give each a stable `CAP-*` identifier and a mini-brief containing its actors and value, high-level externally observable responsibility, meaningful inclusions and exclusions, and source need, goal, journey, obligation, or evidence. Do not add routine delivery or current-state metadata. Leave user stories, detailed functional and non-functional feature requirements, business rules, states, scenarios, examples, and acceptance criteria to later feature specifications. -After final confirmation, create or update the single root `PRODUCT.md` from the [Product Definition Template](assets/product-template.md). Write the executive summary beneath the title, then the strategic sections, followed by feature areas as `##` headings and individual features as `###` headings. Give every feature its status and concise prose covering user value, high-level behaviour, and meaningful boundaries. Present user-confirmed decisions as ordinary product prose, cite useful repository evidence for current claims, and link external claims to their research reports. Preserve canonical language from `CONTEXT.md` and one authoritative meaning for each statement. The durable document makes the product and its features easy to understand and use in later work. +Give every material technical requirement a stable semantic identifier, such as `QUAL-*`, `INT-*`, `DATA-*`, `SEC-*`, `TECH-*`, or `OPS-*`. State the requirement, rationale and source, affected scope, and observable measure or later-verifiable response when applicable. Distinguish hard constraints from preferences. Record mandated external contracts, platforms, runtimes, database families or drivers, hosting limits, and standards as constraints; do not select internal boundaries, components, schemas, endpoints, payloads, algorithms, frameworks, deployment topology, controls, or other implementation mechanisms merely to fill the document. Later feature specifications own the feature-specific technical how, and ADRs own qualifying architecture decisions and rationale. -### 7. Verify the definition +Record assumptions, dependencies, constraints, risks, and open questions distinctly. A non-blocking unresolved item states its evidence, consequence if wrong, affected requirements, owner, and resolution trigger. Do not confirm the foundation while an unresolved item makes the product boundary unsafe or prevents responsible feature specification. -Verify useful `Current` claims against repository evidence, intended direction against user confirmation, `Idea` statuses against the confirmed catalogue, and external claims against linked research. Check that every mapped feature has one mini-brief, the feature order tells a coherent product story, and excluded delivery detail has stayed downstream. Reconcile the finished document with `CONTEXT.md` and applicable decisions, then return changed files, supporting research, and any limitations in repository verification. The user receives a complete product foundation ready to inform feature planning. +### 4. Confirm readiness + +Walk every intended user and lifecycle stakeholder across the journeys, capabilities, and applicable technical requirements. Resolve material omissions, duplicates, broken transitions, contradictory ownership, untraceable requirements, hidden feature depth, and requirements that prescribe unconfirmed design. Check that every normative requirement is necessary, feasible enough for this stage, unambiguous at its level, source-traceable, and capable of later verification. + +Invoke `$elicit-with-context` with the proposed foundation, non-blocking unresolved items, and exact document effect. Use its confirmed synthesis as authority for the agreed `PRODUCT.md` write. If coverage changes afterward, resolve the affected foundation again before writing. + +### 5. Write the foundation + +Create or update the single root `PRODUCT.md` using the [Product and System Requirements Template](assets/product-template.md). Keep one authority even when some sections are omitted as immaterial. Preserve unrelated confirmed content and stylistic local structure. Use stable identifiers and direct links so later feature specifications can trace to the foundation without copying it. Assign identifiers to capabilities, material technical requirements, product-level acceptance, and unresolved records that need downstream reference; do not number every narrative section, goal, measure, or journey by default. + +State each fact and requirement once, then link its identifier. Keep journeys, readiness, acceptance, and evidence from restating the catalogue; add no traceability matrix when inline source traces already establish coverage. + +### 6. Verify and stop + +Verify intended direction against the confirmed synthesis, current claims against inspected evidence, terminology against `GLOSSARY.md`, and material external claims against cited research. Check authority, scope, journeys, capability and technical-requirement coverage, identifier uniqueness, source traceability, internal consistency, explicit non-blocking uncertainty, product-level acceptance, and foundation readiness. Confirm the absence of delivery status, priorities, roadmap, releases, tickets, detailed feature acceptance, selected feature implementation, internal architecture inventory, and unsupported precision. + +Report changed files, supporting evidence, verification, non-blocking unresolved items, and limitations. Stop after `PRODUCT.md` and the glossary changes owned by invoked skills are verified. Do not create feature specifications, ADR decisions, work items, scaffolding, implementation, releases, or deployments. diff --git a/skills/define-product/agents/openai.yaml b/skills/define-product/agents/openai.yaml index b14341f..9b960e1 100644 --- a/skills/define-product/agents/openai.yaml +++ b/skills/define-product/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Define Product' - short_description: 'Discover and document a product direction' + short_description: 'Define product and system requirements' policy: allow_implicit_invocation: false diff --git a/skills/define-product/assets/product-template.md b/skills/define-product/assets/product-template.md index f6ff06f..7d81795 100644 --- a/skills/define-product/assets/product-template.md +++ b/skills/define-product/assets/product-template.md @@ -1,35 +1,119 @@ # {Product name} -{Concise executive summary stating who the product serves, the outcome it enables, and what distinguishes its approach. Include overall product maturity only when it materially improves orientation.} +> **Authority:** This document owns confirmed whole-product intent and system-wide requirements. Feature specifications refine it without silently changing it. -## Vision + -{The product's enduring purpose and positive change, independent of a particular implementation.} +## Executive summary -## Intended users and needs +{Orient readers with intended users, problem, product outcome, distinguishing approach, and consequential boundaries or constraints.} -- **{User or customer}**: {Prioritised need or desired outcome.} +## Purpose, problem, and vision -## Value proposition and market position +{Describe the problem, why it matters, the product's purpose, and the positive change sought without prescribing implementation.} -{Why intended users would choose this product over meaningful alternatives, manual work, or doing nothing. Describe supported differentiation and link material external claims to the applicable research report.} +## Users, actors, stakeholders, and needs -## Business model, goals, and success signals +- **{Role or group}:** {Context, needs, pain, and desired outcomes.} -{Describe the business model and applicable pricing decisions, then the product or business outcomes that justify investment and the observable signals of progress.} +## Value, goals, and success measures -## Product boundaries and non-goals +{Record goals with observable measures, baselines, direction or threshold, measurement source, and horizon where known. Include commercial or market position only when it changes requirements.} -- {A durable boundary or non-goal and the focus it preserves.} +## Scope, boundaries, and non-goals - +### In scope -## {Feature area} +- {Included outcome or responsibility.} -{Optional one-sentence orientation when the area's purpose is not clear from its name.} +### Non-goals -### {Feature name} +- {Durable exclusion and the focus or ownership boundary it preserves.} -_Status: {Current | Confirmed direction | Idea}._ +## Current situation and target direction -{Concise prose describing the feature's user value, high-level behaviour, and meaningful boundaries. Cite repository evidence only when it usefully supports a Current claim; link external claims to their authoritative research report.} + + +{Current evidence, target direction, and material gaps.} + +## Key journeys + +### {Journey name} + +**Actors:** {Users, stakeholders, or external systems.} + +{Narrate entry, outcome, major stages, consequential interactions, recovery or support, and completion or exit. Reference capabilities without repeating their mini-briefs or adding feature scenarios.} + +## Functional capabilities + +### {Natural product area} + +#### CAP-01 — {Capability name} + +- **Actors and value:** {Beneficiaries, need, and enabled outcome.} +- **High-level responsibility:** {One coherent statement of externally observable product behaviour.} +- **Boundaries:** {Important inclusions, exclusions, and adjacent capabilities.} +- **Source trace:** {Need, goal, journey, obligation, research, or current evidence.} + + + + + +### {PREFIX}-01 — {Requirement name} + +{One direct normative requirement.} + +- **Source:** {Confirmed or cited rationale and evidence.} +- **Scope:** {Journeys, capabilities, actors, data, interfaces, or environments governed.} + +## Quality requirements + +{Use `QUAL-*` records for material qualities in their operating context.} + +## System context and external interfaces + +{Briefly describe people and external systems, ownership, exchanges, direction, and trust boundaries. Use `INT-*` records for binding interaction, protocol, standard, ownership, and failure expectations without inventing endpoints, payloads, or adapters. Add a context diagram only when it materially clarifies relationships.} + +## Data and information requirements + +{Use `DATA-*` records for material purpose, categories, sources or sinks, ownership, sensitivity, lifecycle, retention, residency, provenance, scale, or transition obligations.} + +## Integrations and external dependencies + +{Use `INT-*` records for external parties or systems, purpose, exchanges, ownership, mandated contracts, support expectations, failure consequences, or substitution constraints. Link the applicable interface records instead of repeating them.} + +## Security, privacy, safety, and compliance + +{Use `SEC-*` records for protection or assurance outcomes, actor or data scope, trust boundaries, audit obligations, applicable instruments and versions, and risk tolerance.} + +## Technology and platform constraints + +{Use `TECH-*` records for mandated or prohibited platforms, runtimes, languages, database families or drivers, hosting, environments, standards, supported clients, licences, or vendors. State hard versus preferred.} + +## Operational and lifecycle requirements + +{Use `OPS-*` records for availability, support, recovery, capacity, observability, audit, deployment restrictions, maintainability, export, archival, continuity, or retirement outcomes.} + +## Assumptions, dependencies, constraints, risks, and open questions + + + +- **Assumption `ASM-01` — {claim}:** {Evidence; consequence if wrong and affected IDs; owner and resolution trigger.} +- **Dependency `DEP-01` — {condition or party}:** {Evidence; consequence and affected IDs; owner and trigger.} +- **Constraint `CON-01` — {limit}:** {Source and rationale; affected scope; change owner or trigger.} +- **Risk `RSK-01` — {uncertainty}:** {Evidence; consequential effect and affected IDs; owner and review trigger.} +- **Open question `OQ-01` — {question}:** {Why non-blocking; consequence and affected IDs; decision owner and trigger.} + +## Product-level acceptance and foundation readiness + +### Product-level acceptance + +- **ACC-01:** {Whole-product journey, system-wide outcome, or conformance obligation that one feature cannot own cleanly.} + +### Foundation readiness + +{State evidence that the foundation is coherent and safe for downstream feature specification, plus residual limitations. Do not restate the catalogue, self-certify with a checklist, or claim uninspected evidence.} + +## Evidence and traceability + +{Link supplied or inspected research, current-system evidence, applicable ADRs, and `GLOSSARY.md`. Do not invent dates, roles, or provenance. Do not add a traceability matrix when the identifiers and inline source traces already establish coverage.} diff --git a/skills/define-product/references/DISCOVERY.md b/skills/define-product/references/DISCOVERY.md index dce55d9..cdfe354 100644 --- a/skills/define-product/references/DISCOVERY.md +++ b/skills/define-product/references/DISCOVERY.md @@ -1,51 +1,19 @@ # Discovery Techniques -Load only the section needed by the active discovery branch. `$elicit-with-context` remains authoritative for questioning, confirmation, and canonical language; `$research` remains authoritative for external evidence. +Load only the branch needed when direct inspection and ordinary elicitation do not expose the foundation. `$elicit-with-context` owns shared-understanding questioning; `$research` owns durable external evidence; `define-product` retains `PRODUCT.md` and the stopping boundary. -## Establish an existing product +## Reconstruct an existing product -Use **repository archaeology** to recover available behaviour before asking the user. Start with root documentation and manifests, then sample user entry points, public contracts, data boundaries, tests, and operational configuration. Follow evidence until the product areas and feature candidates stabilise. Treat absence as unknown rather than proof, distinguish shipped behaviour from abandoned or planned code, and ask the user to resolve contradictions with stated intent. +Inspect the smallest end-to-end slices that reveal actors, product boundaries, current behaviour, data ownership, external systems, and consequential constraints. Prefer public documentation and contracts, entry points, representative tests, schemas, configuration, and runtime evidence over an implementation inventory. Sample one normal path, one refusal or failure, one recovery path, and one operational or support path where applicable. -## Complete the product frame +Distinguish shipped behaviour from planned or abandoned code. Treat names, code structure, framework choices, and deployment configuration as evidence of the present system, not durable target requirements. Reconcile contradictory evidence with the user instead of selecting a source silently. Use legacy product or architecture documents as evidence only until their statements are confirmed into the current authority. -Use the **Product Vision Board** as a completeness check for the concise opening: +## Expose the whole product -1. What positive change and enduring purpose define the vision? -2. Which users, customers, and influential actors matter, and what outcomes do they need? -3. Why would they choose this product over alternatives, manual work, or doing nothing? -4. What market position or differentiation makes that choice plausible? -5. Which business model, revenue, costs, channels, goals, success signals, and pricing decisions matter now? -6. Which boundaries and non-goals keep the product coherent? +Walk each intended user from entry through recurring value, consequential interaction, failure or refusal, recovery or support, and completion or exit. Change perspective to customers, operators, administrators, support, external-system owners, affected parties, and regulators when material. Derive natural product areas and capability mini-briefs from those journeys, then check commercial, account, trust, data, integration, operational, and lifecycle surfaces that the main journey may hide. -Keep this frame proportionate to its supporting role. Move into whole-product feature discovery once these dimensions are clear. +Use meaningful alternatives, manual work, and doing nothing to clarify value and boundaries. Invoke `$research` only when external position, regulation, standards, providers, or user evidence could materially change a requirement and the evidence must survive the session. -## Map the big picture +## Expose system-wide requirements -Use the **mile-wide, inch-deep** pass before local detail: - -1. Name the product's main users and their entry points. -2. Narrate how each user moves from first contact through recurring value and eventual exit or completion. -3. Record the user-facing product areas along that journey. -4. Beneath each area, inventory current features, confirmed direction, and ideas at one-line resolution. -5. Add commercial, account, trust, support, and other cross-cutting features that the main journey did not expose. - -This pass creates a feature surface, not cards, stories, priorities, screens, releases, or architecture. - -## Explore a feature - -Resolve only the information required by the mini-brief: - -- **User value**: who benefits and what becomes possible or easier? -- **High-level behaviour**: what does the product do from the user's perspective? -- **Status**: is it `Current`, `Confirmed direction`, or `Idea`? -- **Meaningful boundaries**: what nearby behaviour could a later planner reasonably but incorrectly assume belongs to it? - -Use examples or scenarios when behaviour remains ambiguous. Stop when a downstream planning session can understand the feature's product intent without receiving its implementation or delivery design. - -## Walk the complete catalogue - -Read the mapped product back as one narrative. Change perspective across intended users and check entry, recurring-use, recovery, commercial, trust, support, and exit paths where applicable. Look for missing transitions, duplicated features, false journey positions, contradictions, and feature descriptions that hide more than one distinct product behaviour. Resolve each finding during elicitation, then repeat the walk until it exposes nothing new. - -## Establish external position - -Compare the product with alternatives users employ today, including manual work and doing nothing. Invoke `$research` when competitor capabilities, market conditions, pricing, standards, regulation, or user evidence could materially change a product decision. Keep researched claims in the research report and bring only the decision-relevant conclusion and link into `PRODUCT.md`. +For each journey and capability, ask what must remain true across likely implementations: operating conditions, measurable qualities, external ownership and exchanges, information duties, trust and harm boundaries, mandated technology, provider or organisational constraints, support and recovery, and eventual export, archival, or retirement. Record only material design inputs. Leave the selected internal structure and mechanisms to later feature specification. diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index e14c444..995ca0b 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -1,8 +1,8 @@ --- name: elicit-with-context -description: Elicits shared understanding while maintaining project context. Use when an interview should update language and qualifying architecture decisions. +description: Elicits shared understanding while maintaining software-project context. Use when software-project work depends on material user-held information or decisions. metadata: - invocation: user + type: router disable-model-invocation: true --- @@ -12,4 +12,4 @@ Elicits shared understanding while maintaining project context. ## Process -Invoke `$elicit` for questioning, applying `$maintain-context` throughout. +Invoke `$elicit` for questioning. Apply `$maintain-ubiquitous-language` throughout so stable project terms stay current. Invoke `$maintain-decision-records` only when its description applies. Return `$elicit`'s confirmed synthesis. diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index 515dcaa..b5a855c 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -1,41 +1,37 @@ --- name: elicit -description: Elicits user-confirmed decisions one at a time until shared understanding is complete. Use when requirements, constraints, trade-offs, boundaries, or intent need the user's direction before acting. +description: Elicits material information and decisions one question at a time until shared understanding is confirmed. Use when user-held context, clarification, or choices block a bounded outcome. metadata: - invocation: model + type: utility disable-model-invocation: false --- # Elicit -**Goal-oriented requirements engineering** refines a request into user-confirmed decisions until every branch reaches shared understanding. +Builds confirmed shared understanding by resolving a bounded internal **decision tree**, then applying adapted **theoretical saturation**. ## Process -### 1. Establish the root goal +### 1. Establish the basis -Inspect the request, conversation, and accessible task-scoped material before questioning. Derive every available fact and identify the user's intended outcome as the root goal. Keep fact-finding read-only; when it requires a state-changing operation, make authorisation the active decision. Represent every unavailable fact as a branch to resolve with the user. The root goal and factual basis are explicit. +Inspect the request, conversation, caller context, and available task-scoped evidence before questioning. Use cheap read-only fact-finding and stable, confidently applicable general knowledge to close discoverable branches. Verify uncertain, contentious, or potentially current knowledge before treating it as fact. Leave material research and every state-changing action to the caller. The intended outcome, caller boundary, and factual basis are explicit. -### 2. Refine the decision tree +### 2. Maintain the decision tree -Build and continually update an internal, dependency-ordered decision tree. Use lightweight goal refinement to expand the entire request across outcome, scope, terminology, inputs, outputs, prerequisites, dependencies, constraints, flows, exceptions, permissions, risks, trade-offs, and success conditions. Explore alternatives, scenarios, obstacles, and conflicts; preserve compatible decisions when the tree changes. Select the highest-impact unresolved decision whose dependencies are resolved. One active decision is explicit. +Build and continually recompute an internal, dependency-ordered tree containing only branches whose resolution could materially change the bounded outcome. Cover relevant outcome, scope, terminology, inputs, outputs, prerequisites, dependencies, constraints, flows, exceptions, permissions, risks, trade-offs, and success conditions. Preserve compatible answers; close, discard, or reopen branches as evidence changes; and follow directly consequential issues without expanding into unrelated discovery. Select the highest-impact unresolved branch whose prerequisites are resolved. Keep the tree internal and one active issue explicit. -### 3. Ask one issue +### 3. Ask one question -Use **Issue-Based Information Systems** to frame the active decision as one issue with a recommended position, viable alternatives, and the decisive arguments and trade-offs. Offer only positions that resolve the issue in the current tree. Derive the recommendation from the confirmed goal, evidence, conventions, consequences, and prior decisions. Ask exactly one question per turn, ask it once, and leave room for the user's own answer. Treat the user as the sole decision authority. The active decision has one explicit response. +Ask exactly one explicit question per turn in natural language. Explain why an information question matters. Offer suggested answers only when grounded in the established basis. Apply **Design It Twice**: present at least two genuinely distinct viable options, state the material effect of each, and recommend the strongest when the evidence supports a clear winner. Make those options part of the one question; do not append another choice prompt. Leave room for another answer and keep the user as the sole authority over their information and decisions. The active issue receives one explicit response. -### 4. Scaffold an answer +### 4. Adapt and validate -When the user cannot answer, apply **contingent scaffolding** to the same issue through plain-language restatement, clearer alternatives and trade-offs, examples, or scenarios. When needed, decompose it into the highest-impact prerequisite decisions, resolve them one at a time, and recombine their answers. Continue adapting the issue until the user resolves it. The active decision has a user-confirmed answer. +Test every response internally against the outcome, established facts, prior answers, implications, contradictions, scenarios, and counterexamples. Surface a challenge only when it could materially change the shared understanding. Close clear answers without ceremonial repetition. For ambiguity, conflict, difficulty, or consequential interpretation, use plain-English paraphrasing, rewording, clearer options and effects, examples, scenarios, or prerequisite questions resolved one at a time. Do not invent an answer or decide for the user. Recompute the tree and reopen every affected branch. The active issue is resolved consistently. -### 5. Validate the answer +### 5. Reach theoretical saturation -Test each answer against the root goal, prior decisions, scenarios, counterexamples, edge cases, obstacles, conflicts, and consequences. Use **Socratic questioning** to probe the single highest-impact uncertainty in its assumptions, evidence, implications, or viewpoints. Keep an ambiguous or conflicting answer open, state discovered constraints and consequences as facts, and add every exposed decision to the tree. Preserve compatible answers and rebuild affected branches. The answer is consistent and every consequence is represented. +Repeat steps 2–4 until every material branch is resolved. Make an adapted theoretical-saturation pass across the tree, implications, scenarios, counterexamples, and conflicts. Walk each material decision through affected actors and authority, defaults and unchanged behaviour, states and transitions, time boundaries, channels, visibility, exceptions, invalidation, and success evidence; open only consequential gaps. Saturation is reached only when the pass adds or reopens no branch whose answer could materially change the shared understanding. The bounded decision tree is saturated. -### 6. Reach theoretical saturation +### 6. Confirm shared understanding -Continue steps 1–5 until **theoretical saturation**: every branch has a confirmed answer, all dependencies and answers are consistent, and a final goal-refinement, scenario, obstacle, conflict, consequence, and edge-case pass produces no new branch. Shared understanding is ready for synthesis. - -### 7. Confirm shared understanding - -Present one concise, self-contained synthesis of the outcome, boundaries, decisions, constraints, and observable success conditions, then ask for explicit agreement. Treat a correction or rejection as new evidence, reopen every affected branch, and continue from step 2 until saturation returns before presenting the revised synthesis. Affirmative agreement completes elicitation. Return only the user-confirmed synthesis to the caller. +Present one concise, self-contained synthesis of the relevant facts, information, decisions, scope, constraints, implications, and observable success conditions. Ask exactly one question for explicit agreement. Only a new response confirming the complete synthesis ends elicitation; selecting an earlier option does not. Treat a correction or rejection as new evidence, reopen every affected branch, and repeat the saturation pass before presenting a revised synthesis. Return only the confirmed synthesis; create no durable artefact and leave mutation, persistence, verification, downstream action, and the caller's stopping boundary to the caller. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml index dc7e24b..24235cb 100644 --- a/skills/elicit/agents/openai.yaml +++ b/skills/elicit/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Elicit' - short_description: 'Reach shared understanding one decision at a time' + short_description: 'Elicit material information and decisions' policy: allow_implicit_invocation: true diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 32b451b..37847f2 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,22 +1,48 @@ --- name: implement -description: Routes confirmed implementation work through TDD and code review until complete. Use when the user asks to implement a clear software request. +description: Implements one ticket or small confirmed software change as a minimal, locally checked, independently reviewed candidate. Use when agreed software work is ready to build locally. metadata: - invocation: user + type: performer disable-model-invocation: true --- # Implement -A tailored **Software Formal Inspection** lifecycle routes confirmed work through `$tdd`, independent `$code-review`, technical disposition, and verified rework. +Turns one confirmed body of software work into the smallest coherent local change with applicable quality evidence and independent review. ## Process -Invoke `$tdd` to implement the confirmed work, then invoke `$code-review` on the result. Validate every finding against the confirmed request and current codebase, then disposition it: +### 1. Fix the implementation basis -- A required correction is a verified violation of confirmed behaviour, the specification, a repository rule, or a necessary safety boundary, or another defect that leaves the change untrustworthy. -- A proportional improvement is valid but non-blocking; accept it only when its concrete benefit justifies the added change and complexity. -- A rejected finding is falsified, unsupported, superseded, or outside the confirmed scope. -- A user decision is required when accepting or rejecting the finding would change behaviour, contracts, architecture, or scope, or when its evidence cannot be obtained safely. +Inspect the work authority, repository instructions, linked product and technical authorities, current code, tests, relevant contracts, available tools, and complete repository state. State the observable outcome, exclusions, material risks, and completion evidence. Resolve discoverable facts directly. Invoke `$elicit-with-context` only when a material user-held behaviour, contract, architecture, scope, or acceptance decision remains. -Treat priority as evidence of impact and ordering, not remediation authority. Route each accepted change through `$tdd`, then repeat `$code-review` after any correction. Complete when the requested work is verified, every finding has a technical disposition, and no required finding remains unresolved. +Keep the outcome to one implementation-ready ticket, diagnosed repair, or small confirmed change. Preserve unrelated work. Stop when the work is not sufficiently defined to implement and elicitation cannot resolve it within the requested outcome. + +### 2. Load the teaching knowledge + +Invoke `$modular-design` against the fixed work. Invoke `$tdd` when the change affects observable behaviour and an existing usable suite can exercise it through a credible seam. Apply their guidance throughout implementation. + +### 3. Build and check the candidate + +Implement the smallest coherent change that completely satisfies the confirmed outcome. Follow the selected modular constraints and TDD cycles without adding speculative flexibility, unrelated cleanup, or project-wide quality infrastructure outside the agreed work. + +Inspect the complete diff and every in-scope untracked file. Account for each production and test addition, dependency, generated artefact, and measurement-path change. Run applicable repository-required checks. Preserve exact results, unavailable evidence, and residual risks. + +After applicable checks are current, invoke `$measure-code-complexity` with the fixed candidate, comparison base, and implementation authority. Resolve each supported concern by applying an authorised coherent improvement, retaining a supported justification, or invoking `$elicit-with-context` when resolution would change agreed behaviour, contracts, architecture, or scope. Rerun every affected harness and invoke the measurement again after a change. Freeze one complete candidate only when its checks and complexity measurement are current and every trigger is resolved or explicitly retained for handoff. + +### 4. Review and adjudicate + +Invoke `$code-review` on the frozen candidate and its authorities. Validate every Spec and Standards suggestion against the strongest available authority and evidence, then disposition it as: + +- **Required correction:** a confirmed violation, regression, safety defect, or evidence weakness that leaves the change untrustworthy. +- **Proportionate improvement:** a valid in-scope benefit worth its added change and complexity. +- **Rejected finding:** falsified, unsupported, superseded, or outside the confirmed scope. +- **User decision:** resolution would change agreed behaviour, contracts, architecture, or scope, or needs evidence that cannot be obtained safely. + +Apply required corrections and accepted improvements. Invoke `$elicit-with-context` for a user decision. Rerun every affected harness after a candidate or measurement-path change. Freeze and review the complete new candidate after any material change. Continue until every finding has a supported disposition and no applicable correction or accepted improvement remains. + +### 5. Hand off the local result + +Report the delivered behaviour, changed artefacts, applicable TDD and modular-design decisions, exact checks and results, unavailable evidence, residual risks, review scope and results, and every finding disposition. Successful completion requires the agreed behaviour locally, every production addition serving a current purpose, applicable evidence passed or explicitly unavailable, and current Spec and Standards review with no unresolved applicable change. + +Stop without committing, pushing, opening or updating a pull request, changing tracker state, releasing, or deploying. Do not conduct exploratory research, create specifications or tickets, or add unrelated quality infrastructure inside this outcome. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml index 0e09bd3..5421aeb 100644 --- a/skills/implement/agents/openai.yaml +++ b/skills/implement/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Implement' - short_description: 'Implement through TDD and review' + short_description: 'Implement and review one local change' policy: allow_implicit_invocation: false diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md index 038ca5f..423386d 100644 --- a/skills/maintain-agents/SKILL.md +++ b/skills/maintain-agents/SKILL.md @@ -1,33 +1,33 @@ --- name: maintain-agents -description: Creates and compresses lean root AGENTS.md files. Use when initializing or improving repository-wide agent guidance. +description: Maintains concise root AGENTS.md instructions. Use when creating the file or adding, refining, or assessing repository-wide agent guidance. metadata: - invocation: user + type: utility disable-model-invocation: true --- # Maintain AGENTS.md -**Progressive Disclosure** keeps root `AGENTS.md` guidance limited to behaviour every repository task needs while narrower instructions remain discoverable on demand. +Uses **Progressive Disclosure** to keep the repository's always-loaded agent guidance relevant to every request. ## Process -### 1. Inspect the instruction surface +### 1. Establish the file -Locate the repository root. Read the root `AGENTS.md`, applicable instruction layers, and enough manifests, task runners, CI, and contributor documentation to recover each rule's intent and identify project checks. The target, instruction chain, rules, and check entry points are explicit. +Locate the repository root and read its `AGENTS.md` when present. Create it when absent. Ensure this line appears exactly once at the top, replacing or moving equivalent wording: -### 2. Allocate the guidance +```markdown +- When a user correction establishes a reusable repository-wide rule, ask whether to invoke `$maintain-agents` to add it. +``` -Classify every existing and proposed instruction by runtime scope. Retain only concise behaviour governing the whole repository, plus the required correction and completion instructions. Report useful narrower guidance with its smallest discoverable owner: an invocable skill for reusable workflows, a scoped instruction file for directory rules, or executable enforcement for mechanical constraints. Leave destinations unchanged. Discard stale guidance, rationale, boilerplate, repository description, personal preferences, and task-, component-, or workflow-specific instructions. Every retained rule earns its permanent context cost. +### 2. Assess the guidance -### 3. Establish the required guidance +Recommend an instruction when it is user-confirmed, cannot be inferred reliably from repository evidence, governs the repository as a whole, and materially changes agent behaviour. Treat a composing caller's confirmed instruction as user-confirmed. When an instruction fails a gate, explain the concern and ask for the user's final decision; follow that decision. -Ensure the file states: `Ask immediately whether to add a reusable repository-wide rule to AGENTS.md when a user correction establishes it.` When project checks exist, add one instruction to run them after implementation and before handoff. Prefer one canonical aggregate command covering the configured suites; otherwise list every applicable individual command. Invoke `$elicit` when candidates materially differ or a command has unusual external effects. Omit the instruction only when no project checks exist. The correction loop and completion commands are explicit. +### 3. Write the instruction -### 4. Write the root instructions +Apply only the requested addition, refinement, or assessment. Use the shortest direct imperative sentence that preserves the required behaviour and conditions. State each policy once; update equivalent wording instead of adding a semantic duplicate. Leave unrelated instructions unchanged. -Create or rewrite only the root `AGENTS.md`. Use direct imperative lines. Remove headings unless they navigate multiple instruction groups. Apply **Minimalist Instruction** until every word changes behaviour or preserves a necessary condition. Apply **DRY** to meaning: when changing one rule requires changing multiple instructions, merge them into one authoritative expression. No semantic duplicates remain. +### 4. Verify the result -### 5. Verify and hand off - -Re-read every line for repository-wide scope, behavioural value, and semantic duplication. Verify each command exists; run the checks after implementation and before handoff when safe and applicable. Return the changed file, check results or limitations, displaced guidance with destinations, and unresolved conflicts. The user receives a lean verified root file and a visible account of displaced guidance. +Re-read `AGENTS.md`. Confirm the canonical first line, requested outcome, minimal wording, and absence of semantic duplication. Return the change, no-op, or requested advice with any concerns. diff --git a/skills/maintain-agents/agents/openai.yaml b/skills/maintain-agents/agents/openai.yaml index 4755f87..2b4bbb9 100644 --- a/skills/maintain-agents/agents/openai.yaml +++ b/skills/maintain-agents/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Maintain AGENTS.md' - short_description: 'Create or compress repository-wide agent guidance' + short_description: 'Write concise repository-wide agent guidance' policy: allow_implicit_invocation: false diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md deleted file mode 100644 index c783dec..0000000 --- a/skills/maintain-context/SKILL.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: maintain-context -description: Actively maintains project language and architecture decisions. Use when domain terms or consequential codebase decisions emerge or change. -metadata: - invocation: model -disable-model-invocation: false ---- - -# Maintain Context - -**Ubiquitous Language** is an active discipline: challenge and refine project terms during ordinary discussion, then write each resolution into one root `CONTEXT.md` before the conversation moves on. Architecture decision records preserve only rare consequential choices. - -## Process - -### 1. Maintain the language inline - -Apply this loop to each material domain term while the discussion is taking place: - -- Compare it with the single root `CONTEXT.md` and inspect only the relevant code. -- Challenge glossary misuse immediately and quote the conflicting meanings. -- Sharpen vague or overloaded language by proposing one precise canonical term. -- Test the proposed meaning with concrete scenarios and edge cases that expose its boundaries. -- Use **Model-Driven Design** to surface disagreement between language and implementation. Treat code as evidence of current behaviour and the user's confirmed answer as intent. -- When the user resolves the term, update `CONTEXT.md` before continuing the discussion. Keep a genuine uncertainty explicit and leave its glossary entry unresolved. - -Create the root file lazily from the [context template](assets/context-template.md) when the first term resolves. The durable language stays current with the conversation rather than accumulating for handoff. - -### 2. Keep the glossary rigorous - -Keep `CONTEXT.md` as a glossary of project-specific domain language: define each term's meaning in one or two sentences, leaving implementation and specifications to their authoritative sources. Give each meaning one authoritative entry, and add `_Avoid_` only for aliases or ambiguous alternatives that actually occur. - -Use **Conceptual Contours** to group related terms under descriptive subheadings when meaningful domain clusters emerge; keep one flat language list when the terms form a cohesive area. If context-dependent meanings conflict with the single-context structure, surface that ambiguity instead of inventing another context file. - -### 3. Offer ADRs sparingly - -Use **Architecture Decision Records** only for an accepted codebase decision that passes all three gates: - -- changing it later has meaningful cost; -- a future reader would find it surprising without context; and -- viable alternatives created a genuine trade-off. - -Offer an ADR when all three pass and let the user decide whether to record it. A decision that misses any gate remains routine and produces no ADR. - -### 4. Record a qualifying decision - -After the user accepts the offer, create `docs/adr/` lazily and write the next record from the [ADR template](assets/adr-template.md). Derive the next four-digit sequence from filenames alone and name it `NNNN-decision-shaped-slug.md`. State the decision first, then only the context and significant ramifications needed to explain it; use exactly `Decision`, `Context`, and `Ramifications` as content sections, in that order. Link supporting material from the record. The ADR is brief, sequentially numbered, and readable from its filename. - -### 5. Verify and hand off - -Re-read each changed artifact against the resolved language, accepted decisions, and relevant code evidence. Report the files changed and the exact uncertainty behind any unresolved contradiction. diff --git a/skills/maintain-context/agents/openai.yaml b/skills/maintain-context/agents/openai.yaml deleted file mode 100644 index e459f7c..0000000 --- a/skills/maintain-context/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Maintain Context' - short_description: 'Maintain project language and decisions' -policy: - allow_implicit_invocation: true diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md deleted file mode 100644 index 486cc18..0000000 --- a/skills/maintain-context/assets/context-template.md +++ /dev/null @@ -1,10 +0,0 @@ -# {Project Name} Context - -{Describe the project domain and why this language exists in one or two sentences.} - -## Language - -### {Optional descriptive concept group} - -**{Canonical term}**: {Define what the term is in one or two sentences.}\ -_Avoid_: {List observed aliases or ambiguous alternatives; omit when none exist.} diff --git a/skills/maintain-decision-records/SKILL.md b/skills/maintain-decision-records/SKILL.md new file mode 100644 index 0000000..101cf9d --- /dev/null +++ b/skills/maintain-decision-records/SKILL.md @@ -0,0 +1,36 @@ +--- +name: maintain-decision-records +description: Maintains rare architecture decision records. Use when an accepted technical or architectural decision may warrant durable rationale. +metadata: + type: utility +disable-model-invocation: true +--- + +# Maintain Decision Records + +Preserves the rationale for exceptional accepted technical or architectural decisions in concise Architecture Decision Records. + +## Process + +### 1. Inspect the decision + +Inspect the accepted decision, relevant conversation or caller handoff, existing `docs/adr/` records, applicable repository guidance, and only the product, architecture, feature, governance, or implementation evidence needed to establish its owner and rationale. Do not scan unrelated decisions. The candidate decision, alternatives, consequences, existing coverage, and user authority are explicit. + +### 2. Gate the record + +Create an ADR only when the accepted technical or architectural decision passes every gate: + +- changing it later has meaningful cost; +- a future reader would find it surprising without context; +- viable alternatives created a genuine trade-off; and +- no existing durable authority already records the decision or is its better owner, including `PRODUCT.md`, a feature document, or a dedicated governance record. + +Require the user's explicit agreement to preserve the rationale durably. Agreement recorded in the relevant conversation or caller handoff satisfies this gate without another prompt. When every other gate passes but agreement is absent, ask the user one direct question. A decision that misses a gate, lacks agreement, or is routine or discoverable produces no ADR. + +### 3. Write the ADR + +Create `docs/adr/` lazily and write the next record from the [ADR template](assets/adr-template.md). Name it `NNNN-decision-shaped-slug.md`: use `0001` when no sibling matches `NNNN-*.md`; otherwise add one to the largest four-digit prefix. Keep exactly three substantive sections in order: `Decision`, `Context`, and `Consequences`. Record the accepted choice, why it was needed, only the rejected or constrained alternatives necessary to explain its trade-offs, and its material consequences. + +### 4. Verify the result + +Re-read the ADR against the accepted decision, every gate, the user's agreement, and relevant evidence. Return the created file or why no ADR was warranted. Change no caller-owned product, architecture, feature, code, external state, or verification outcome. diff --git a/skills/maintain-decision-records/agents/openai.yaml b/skills/maintain-decision-records/agents/openai.yaml new file mode 100644 index 0000000..29d96ca --- /dev/null +++ b/skills/maintain-decision-records/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Maintain Decision Records' + short_description: 'Maintain rare architecture decisions' +policy: + allow_implicit_invocation: false diff --git a/skills/maintain-context/assets/adr-template.md b/skills/maintain-decision-records/assets/adr-template.md similarity index 59% rename from skills/maintain-context/assets/adr-template.md rename to skills/maintain-decision-records/assets/adr-template.md index fbf0562..bf22119 100644 --- a/skills/maintain-context/assets/adr-template.md +++ b/skills/maintain-decision-records/assets/adr-template.md @@ -6,8 +6,8 @@ ## Context -{Explain the problem, forces, and serious alternatives needed to understand the decision.} +{Explain why the decision was needed and only the rejected or constrained alternatives necessary to understand its trade-offs.} -## Ramifications +## Consequences {State the significant consequences, trade-offs, and conditions that could trigger reconsideration.} diff --git a/skills/maintain-ubiquitous-language/SKILL.md b/skills/maintain-ubiquitous-language/SKILL.md new file mode 100644 index 0000000..f5f2b7d --- /dev/null +++ b/skills/maintain-ubiquitous-language/SKILL.md @@ -0,0 +1,27 @@ +--- +name: maintain-ubiquitous-language +description: Maintains project-specific language in GLOSSARY.md. Use when project terminology must be added, changed, challenged, renamed, deprecated, or reconciled. +metadata: + type: utility +disable-model-invocation: true +--- + +# Maintain Ubiquitous Language + +Applies **Ubiquitous Language** by keeping project-specific terminology consistent in one root `GLOSSARY.md` glossary. + +## Process + +### 1. Inspect the language + +Inspect the relevant conversation or caller handoff, root `GLOSSARY.md`, applicable repository guidance, and only the project evidence needed to understand the language. Treat a stable project-specific meaning as resolved when that context makes it clear. Challenge uses that conflict with an established term. + +### 2. Update inline + +Update `GLOSSARY.md` as each meaning resolves, before the surrounding work continues. Do not request approval or announce the skill. Add no separate verification or handoff for a routine glossary update; follow the surrounding task's normal checks and reporting. + +When ambiguity, conflict, rename, or deprecation could materially change the meaning, ask one direct question that distinguishes the alternatives. Preserve the existing entry until the answer resolves the meaning. + +Create the root file lazily from the [glossary template](assets/glossary-template.md). Preserve unrelated terms and local format. Edit only affected entries, prefer updating an entry to adding a duplicate, and reconcile resolved changes across affected entries. Retain an alias or deprecation only while it helps interpret current project evidence. + +Keep `GLOSSARY.md` a glossary, not a specification or implementation record. Give each canonical term one short project-native paragraph; group terms by domain only when useful. diff --git a/skills/maintain-ubiquitous-language/agents/openai.yaml b/skills/maintain-ubiquitous-language/agents/openai.yaml new file mode 100644 index 0000000..3a8cfa7 --- /dev/null +++ b/skills/maintain-ubiquitous-language/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Maintain Ubiquitous Language' + short_description: 'Maintain shared project terminology' +policy: + allow_implicit_invocation: false diff --git a/skills/maintain-ubiquitous-language/assets/glossary-template.md b/skills/maintain-ubiquitous-language/assets/glossary-template.md new file mode 100644 index 0000000..5d11007 --- /dev/null +++ b/skills/maintain-ubiquitous-language/assets/glossary-template.md @@ -0,0 +1,7 @@ +# {Project Name} Glossary + +## Language + +### {Optional descriptive concept group} + +**{Canonical term}**: {Define the term's project-specific meaning in one or two concise sentences.} diff --git a/skills/measure-code-complexity/SKILL.md b/skills/measure-code-complexity/SKILL.md new file mode 100644 index 0000000..add0e04 --- /dev/null +++ b/skills/measure-code-complexity/SKILL.md @@ -0,0 +1,54 @@ +--- +name: measure-code-complexity +description: Measures changed-code complexity with pinned cross-language metrics and advisory review triggers. Use when implementing, reviewing, or directly assessing code complexity. +metadata: + type: utility +disable-model-invocation: false +--- + +# Measure Code Complexity + +Measures reproducible complexity signals and routes triggered changed code through contextual engineering judgement. + +## Prerequisites + +Fix the Git repository, candidate, comparison base, caller authority, and any explicit repository thresholds. Require Python 3.8 or newer. Report the exact unavailable or incomplete evidence when any prerequisite is absent; never treat a failed or unsupported measurement as clear. + +## Process + +### 1. Measure the fixed change + +Run the bundled [measurement script](scripts/measure.py) without installing dependencies or accessing the network: + +```sh +python3 /path/to/measure-code-complexity/scripts/measure.py \ + --repo /path/to/repository \ + --base +``` + +Pass the corresponding threshold option when an explicit repository policy overrides a bundled default. Use `--whole-repository` only for an explicit repository-wide request and `--all` only when compact evidence cannot resolve a concrete question. + +### 2. Investigate triggered signals + +Read the compact JSON. Its summary accounts for every measured changed function; detailed records default to triggered entities and the raw artifact retains the complete normalized result. + +For each triggered metric, load only its named reference: [Cyclomatic Complexity](references/CYCLOMATIC-COMPLEXITY.md), [Function Size](references/FUNCTION-SIZE.md), [Nesting](references/NESTING.md), [Parameters](references/PARAMETERS.md), or [Duplication](references/DUPLICATION.md). Inspect the cited source, nearby contracts, tests, and clone counterparts. Do not load a metric reference that did not trigger. + +Disposition every trigger as one of: + +- **Supported concern:** state the concrete maintainability consequence, evidence, and narrow improvement direction. +- **Justified shape:** state the concrete code- and test-based reason the shape is appropriate. +- **Unresolved:** state the missing authority or evidence and leave the trigger open. + +Measure and interpret only. Leave every source edit, test run, and decision to apply an improvement to the caller. + +### 3. Return the evidence + +Return the fixed scope, compact summary, triggered locations and values, baseline deltas when present, each disposition, incomplete evidence, and raw-artifact path. A high value triggers inspection; it does not establish a defect, require refactoring, or supply a code-quality verdict. + +## Rules + +- Keep the bundled metric definitions and bands intact unless explicit repository policy overrides a threshold. +- Preserve all metric components; do not combine them into Maintainability Index, CRAP, or another scalar grade. +- Reject score-only changes that merely move branching, add indirection, hide parameters, or replace one clone with a shallow abstraction. +- Stop after every trigger has a supported disposition or is explicitly unresolved. Do not modify source or tests, run implementation checks, create repository policy or durable reports, commit, publish, or change external state. diff --git a/skills/measure-code-complexity/agents/openai.yaml b/skills/measure-code-complexity/agents/openai.yaml new file mode 100644 index 0000000..46dd2f9 --- /dev/null +++ b/skills/measure-code-complexity/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Measure Code Complexity' + short_description: 'Measure changed-code complexity and review triggers' +policy: + allow_implicit_invocation: true diff --git a/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md b/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md new file mode 100644 index 0000000..fba7a8a --- /dev/null +++ b/skills/measure-code-complexity/references/CYCLOMATIC-COMPLEXITY.md @@ -0,0 +1,9 @@ +# Cyclomatic Complexity + +Cyclomatic complexity counts recognized decision points within each function as a control-flow-path proxy. Use the bundled bands as attention routing: `1-6` low, `7-9` moderate, `10-20` high, and `21+` very high. Values differ across measurement engines and languages; this does not measure all executable paths, nesting, domain difficulty, runtime behaviour, or correctness. + +Inspect whether the branches represent one cohesive decision, repeated cases, invalid intermediate states, flag-driven behaviour, or several policies sharing a function. Trace the distinct outcomes and their tests. + +Prefer guard clauses for invalid states, data or lookup tables for declarative cases, and extraction behind a named boundary when a decision has an independent contract. Use polymorphism or strategy objects only when the variants are real concepts with separate change patterns. Do not improve the number by scattering the same decisions across shallow helpers. + +Retain high complexity when an explicit algorithm, parser, state transition, protocol, or irreducible domain rule is clearer locally and its material paths are tested. Record that mechanism and evidence. diff --git a/skills/measure-code-complexity/references/DUPLICATION.md b/skills/measure-code-complexity/references/DUPLICATION.md new file mode 100644 index 0000000..511f65a --- /dev/null +++ b/skills/measure-code-complexity/references/DUPLICATION.md @@ -0,0 +1,9 @@ +# Duplication + +Clone detection normalizes token sequences and reports locations meeting the bundled `70`-token floor. Review new or expanded clone groups that intersect changed code. A clone is syntactic similarity, not proof that occurrences share one concept or should evolve together. + +Compare every occurrence. Inspect whether the same rule, defect fix, invariant, or sequence would need parallel change; also check whether similarities are coincidental, generated, declarative, protocol-defined, or intentionally independent test examples. + +Prefer one owner with a deep interface when the occurrences share knowledge and change together. Use data tables or parameterized tests when only values differ. Do not create a shallow helper that leaks sequencing, accepts mode flags, couples independent features, or obscures a readable example. + +Retain a clone when independent evolution, protocol fidelity, test clarity, or a small stable repetition outweighs shared ownership. Record that reason and the evidence that future changes need not stay synchronized. diff --git a/skills/measure-code-complexity/references/FUNCTION-SIZE.md b/skills/measure-code-complexity/references/FUNCTION-SIZE.md new file mode 100644 index 0000000..bcbefda --- /dev/null +++ b/skills/measure-code-complexity/references/FUNCTION-SIZE.md @@ -0,0 +1,9 @@ +# Function Size + +NLOC counts non-comment source lines within a function; token count is supporting scale evidence. Review NLOC above `100`. Size measures change surface, not value, productivity, correctness, or understandability, and formatting or language syntax can change it. + +Inspect whether the function mixes validation, policy, transformation, persistence, external effects, or several temporal phases. Look for a coherent block with its own inputs, result, invariant, and useful name rather than extracting by line count. + +Prefer a smaller deep helper, a table for repetitive data, or an owned module when that improves locality and hides a real decision. Keep related sequencing together when extraction would force callers to coordinate it or create pass-through methods. + +Retain long linear functions when they are declarative mappings, protocol mirrors, migrations, generated structures, or one readable algorithm whose split would obscure the flow. Verify the retained shape through focused tests and the applicable repository checks. diff --git a/skills/measure-code-complexity/references/NESTING.md b/skills/measure-code-complexity/references/NESTING.md new file mode 100644 index 0000000..b9d29ec --- /dev/null +++ b/skills/measure-code-complexity/references/NESTING.md @@ -0,0 +1,9 @@ +# Nested Control Structures + +The nested-structures metric reports the maximum number of nested control structures in a function. Review values above `3`. It is a syntactic proxy for context carried through nested branches; it is not Cognitive Complexity and may vary with language support. + +Inspect which conditions protect invalid states, which levels represent independent policy, and whether loop, exception, and conditional nesting obscure the active invariant. Trace the deepest path and its tests. + +Prefer guard clauses, `continue` or early completion for invalid cases, named predicates, and extraction of a cohesive nested policy. Flatten only when the resulting order and effects remain explicit. Avoid boolean flags, callback chains, or hidden mutable state that reduce indentation while increasing coordination. + +Retain nesting when tree traversal, parsing, structured resource handling, or transactional cleanup is clearest in its lexical hierarchy. Record why flattening would weaken correctness or locality and identify the tests protecting the deepest path. diff --git a/skills/measure-code-complexity/references/PARAMETERS.md b/skills/measure-code-complexity/references/PARAMETERS.md new file mode 100644 index 0000000..0936b80 --- /dev/null +++ b/skills/measure-code-complexity/references/PARAMETERS.md @@ -0,0 +1,9 @@ +# Parameter Count + +The measurement reports a function parameter count. Verify it against the signature before dispositioning it because partial language parsers can miscount parameters. Review counts of `5` or more. The count can expose a wide interface or recurring data group, but it does not measure parameter meaning, type safety, defaults, or the depth of the function's abstraction. + +Inspect whether parameters travel together, represent one concept, encode flags or modes, or change for unrelated reasons. Check call sites before changing the interface. + +Prefer an existing domain value, an explicit request or options type with a coherent invariant, or separate operations when callers currently select unrelated behaviour. Do not hide unrelated values in a generic bag or move required context into globals, ambient state, or service locators. + +Retain a wider signature for mathematical functions, stable interoperation boundaries, framework callbacks, or flat data construction when grouping would add ceremony without ownership. Record the caller evidence and keep meaningful parameter names and types. diff --git a/skills/measure-code-complexity/scripts/measure.py b/skills/measure-code-complexity/scripts/measure.py new file mode 100644 index 0000000..a537d3c --- /dev/null +++ b/skills/measure-code-complexity/scripts/measure.py @@ -0,0 +1,740 @@ +#!/usr/bin/env python3 +"""Measure changed-code complexity with a pinned, vendored Lizard runtime.""" + +from __future__ import annotations + +import argparse +import hashlib +import itertools +import json +import os +from pathlib import Path +import re +import subprocess +import sys +import tempfile +from typing import Any, Iterable + + +SCHEMA_VERSION = 1 +SCRIPT_ROOT = Path(__file__).resolve().parent +VENDOR_ROOT = SCRIPT_ROOT / "vendor" +WHEELS = ( + ( + "pygments-2.19.2-py3-none-any.whl", + "86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", + ), + ( + "lizard-1.24.0-py2.py3-none-any.whl", + "a688bc607a891ff4a7836826f25742dc9c1bf648da3075dbd495e199e8848602", + ), +) + +DEFAULTS = { + "cyclomaticReview": 10, + "nlocReview": 100, + "nestedStructuresReview": 3, + "parameterCountReview": 5, + "duplicateTokens": 70, +} + +REFERENCES = { + "cyclomaticComplexity": "references/CYCLOMATIC-COMPLEXITY.md", + "nloc": "references/FUNCTION-SIZE.md", + "nestedStructures": "references/NESTING.md", + "parameterCount": "references/PARAMETERS.md", + "duplication": "references/DUPLICATION.md", +} + +EXCLUDED_SEGMENTS = { + ".git", + ".hg", + ".svn", + "build", + "coverage", + "deps", + "dist", + "fixtures", + "generated", + "node_modules", + "snapshots", + "vendor", + "vendors", + "__fixtures__", + "__snapshots__", +} + +TEST_SEGMENTS = {"spec", "specs", "test", "tests", "__tests__"} +NON_SOURCE_SUFFIXES = { + ".css", + ".csv", + ".gif", + ".html", + ".jpeg", + ".jpg", + ".json", + ".lock", + ".md", + ".pdf", + ".png", + ".svg", + ".toml", + ".txt", + ".xml", + ".yaml", + ".yml", +} + + +class MeasurementError(RuntimeError): + """A deterministic measurement prerequisite or execution failed.""" + + +def sha256(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as stream: + for block in iter(lambda: stream.read(1024 * 1024), b""): + digest.update(block) + return digest.hexdigest() + + +def load_analyzer() -> tuple[Any, Any, Any, str]: + if sys.version_info < (3, 8): + raise MeasurementError("Python 3.8 or newer is required.") + + for filename, expected in WHEELS: + wheel = VENDOR_ROOT / filename + if not wheel.is_file(): + raise MeasurementError(f"Missing vendored analyzer wheel: {filename}") + actual = sha256(wheel) + if actual != expected: + raise MeasurementError( + f"Checksum mismatch for {filename}: expected {expected}, got {actual}" + ) + sys.path.insert(0, str(wheel)) + + try: + import lizard # type: ignore + from lizard_ext import lizardduplicate, lizardns, version # type: ignore + except (ImportError, SystemExit) as error: + raise MeasurementError(f"Unable to load vendored Lizard: {error}") from error + + return lizard, lizardns, lizardduplicate, str(version) + + +def git(repo: Path, *arguments: str, check: bool = True) -> bytes: + command = ["git", "-C", str(repo), *arguments] + result = subprocess.run(command, capture_output=True, check=False) + if check and result.returncode != 0: + message = result.stderr.decode("utf-8", "replace").strip() + raise MeasurementError( + f"Command failed ({result.returncode}): {' '.join(command)}: {message}" + ) + return result.stdout + + +def nul_fields(data: bytes) -> list[str]: + return [field.decode("utf-8", "surrogateescape") for field in data.split(b"\0") if field] + + +def normalize_path(value: str) -> str: + return Path(value).as_posix().removeprefix("./") + + +def excluded(path: str) -> bool: + normalized = normalize_path(path) + parts = set(Path(normalized).parts) + name = Path(normalized).name.lower() + return ( + bool(parts & EXCLUDED_SEGMENTS) + or bool(parts & TEST_SEGMENTS) + or name.endswith((".min.js", ".min.css", ".generated.ts", ".generated.js")) + or ".fixture." in name + or ".snap." in name + or name.endswith((".spec.ts", ".spec.tsx", ".test.ts", ".test.tsx")) + ) + + +def parse_name_status(data: bytes) -> dict[str, str | None]: + fields = nul_fields(data) + changed: dict[str, str | None] = {} + index = 0 + while index < len(fields): + status = fields[index] + index += 1 + if status.startswith(("R", "C")): + if index + 1 >= len(fields): + raise MeasurementError("Malformed git rename/copy status output.") + old_path = normalize_path(fields[index]) + new_path = normalize_path(fields[index + 1]) + changed[new_path] = old_path + index += 2 + else: + if index >= len(fields): + raise MeasurementError("Malformed git name-status output.") + path = normalize_path(fields[index]) + index += 1 + if not status.startswith("D"): + changed[path] = path + return changed + + +def all_changed_paths(repo: Path, base: str) -> dict[str, str | None]: + changed = parse_name_status( + git(repo, "diff", "--name-status", "-z", "--find-renames", base, "--") + ) + for path in nul_fields(git(repo, "ls-files", "--others", "--exclude-standard", "-z")): + changed[normalize_path(path)] = None + return {path: old_path for path, old_path in changed.items() if (repo / path).is_file()} + + +def changed_paths(repo: Path, base: str) -> dict[str, str | None]: + return { + path: old_path + for path, old_path in all_changed_paths(repo, base).items() + if not excluded(path) + } + + +def line_ranges(repo: Path, base: str, path: str, is_untracked: bool) -> list[tuple[int, int]]: + if is_untracked: + line_count = sum(1 for _ in (repo / path).open("rb")) + return [(1, max(1, line_count))] + + patch = git(repo, "diff", "--unified=0", "--no-color", base, "--", path).decode( + "utf-8", "replace" + ) + ranges: list[tuple[int, int]] = [] + for match in re.finditer(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@", patch, re.MULTILINE): + start = int(match.group(1)) + count = int(match.group(2) or "1") + if count: + ranges.append((start, start + count - 1)) + return ranges + + +def intersects(start: int, end: int, ranges: Iterable[tuple[int, int]]) -> bool: + return any(start <= range_end and end >= range_start for range_start, range_end in ranges) + + +def current_paths(repo: Path) -> list[str]: + paths = nul_fields(git(repo, "ls-files", "-co", "--exclude-standard", "-z")) + return sorted( + { + normalize_path(path) + for path in paths + if (repo / path).is_file() and not excluded(path) + } + ) + + +def base_paths(repo: Path, base: str) -> list[str]: + return sorted( + path + for path in map( + normalize_path, + nul_fields(git(repo, "ls-tree", "-r", "--name-only", "-z", base)), + ) + if not excluded(path) + ) + + +def source_paths(paths: Iterable[str], root: Path, lizard: Any) -> tuple[list[str], list[str]]: + supported: list[str] = [] + unsupported: list[str] = [] + for path in paths: + if lizard.get_reader_for(str(root / path)): + supported.append(path) + elif Path(path).suffix.lower() not in NON_SOURCE_SUFFIXES: + unsupported.append(path) + return supported, unsupported + + +def extract_base(repo: Path, base: str, paths: Iterable[str], target: Path) -> list[str]: + extracted: list[str] = [] + for path in paths: + result = subprocess.run( + ["git", "-C", str(repo), "show", f"{base}:{path}"], + capture_output=True, + check=False, + ) + if result.returncode != 0: + continue + destination = target / path + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_bytes(result.stdout) + extracted.append(path) + return extracted + + +def analyze( + root: Path, + paths: list[str], + lizard: Any, + lizardns: Any, + duplicate_module: Any, + duplicate_tokens: int, +) -> tuple[list[dict[str, Any]], list[list[dict[str, Any]]], float]: + nested_extension = lizardns.LizardExtension() + duplicate_extension = duplicate_module.LizardExtension() + extensions = lizard.get_extensions([nested_extension, duplicate_extension]) + absolute_paths = [str(root / path) for path in paths] + file_infos = list(lizard.analyze_files(absolute_paths, threads=1, exts=extensions)) + + functions: list[dict[str, Any]] = [] + for file_info in file_infos: + relative = normalize_path(os.path.relpath(file_info.filename, root)) + for function in file_info.function_list: + functions.append( + { + "file": relative, + "line": int(function.start_line), + "endLine": int(function.end_line), + "symbol": str(function.name), + "longName": str(function.long_name), + "metrics": { + "cyclomaticComplexity": int(function.cyclomatic_complexity), + "nloc": int(function.nloc), + "nestedStructures": int(function.max_nested_structures), + "parameterCount": int(function.parameter_count), + "tokenCount": int(function.token_count), + }, + } + ) + + duplicates: list[list[dict[str, Any]]] = [] + for group in duplicate_extension.get_duplicates(duplicate_tokens): + duplicates.append( + [ + { + "file": normalize_path(os.path.relpath(snippet.file_name, root)), + "line": int(snippet.start_line), + "endLine": int(snippet.end_line), + } + for snippet in group + ] + ) + return functions, duplicates, float(duplicate_extension.duplicate_rate() or 0.0) + + +def cyclomatic_band(value: int) -> str: + if value <= 6: + return "low" + if value <= 9: + return "moderate" + if value <= 20: + return "high" + return "veryHigh" + + +def baseline_match(function: dict[str, Any], base_functions: list[dict[str, Any]], old_path: str | None) -> dict[str, Any] | None: + if old_path is None: + return None + same_name = [ + item + for item in base_functions + if item["file"] == old_path and item["symbol"] == function["symbol"] + ] + if len(same_name) == 1: + return same_name[0] + same_signature = [item for item in same_name if item["longName"] == function["longName"]] + if same_signature: + return min(same_signature, key=lambda item: abs(item["line"] - function["line"])) + if same_name: + return min(same_name, key=lambda item: abs(item["line"] - function["line"])) + return None + + +def metric_value( + value: int, + baseline: int | None, + band: str | None = None, + is_new: bool = False, +) -> dict[str, Any]: + result: dict[str, Any] = {"value": value} + if is_new: + result["baseline"] = "absent" + result["delta"] = "new" + elif baseline is not None: + result["baseline"] = baseline + result["delta"] = value - baseline + if band: + result["band"] = band + return result + + +def duplicate_pairs(groups: list[list[dict[str, Any]]]) -> dict[tuple[str, str], int]: + pairs: dict[tuple[str, str], int] = {} + for group in groups: + for left, right in itertools.combinations(group, 2): + key = tuple(sorted((left["file"], right["file"]))) + span = min( + left["endLine"] - left["line"] + 1, + right["endLine"] - right["line"] + 1, + ) + pairs[key] = max(pairs.get(key, 0), span) + return pairs + + +def duplicate_triggers( + candidate_groups: list[list[dict[str, Any]]], + base_groups: list[list[dict[str, Any]]], + changed: dict[str, str | None], + changed_lines: dict[str, list[tuple[int, int]]], + whole_repository: bool, + minimum_tokens: int, +) -> list[dict[str, Any]]: + base_pair_lengths = duplicate_pairs(base_groups) + results: list[dict[str, Any]] = [] + seen: set[tuple[tuple[str, int, int], ...]] = set() + + for group in candidate_groups: + touches_change = whole_repository or any( + snippet["file"] in changed + and intersects( + snippet["line"], + snippet["endLine"], + changed_lines.get(snippet["file"], []), + ) + for snippet in group + ) + if not touches_change: + continue + + state = "present" if whole_repository else None + baseline_lines: int | None = None + if not whole_repository: + for left, right in itertools.combinations(group, 2): + old_left = changed.get(left["file"], left["file"]) + old_right = changed.get(right["file"], right["file"]) + if old_left is None or old_right is None: + state = "new" + continue + base_key = tuple(sorted((old_left, old_right))) + candidate_span = min( + left["endLine"] - left["line"] + 1, + right["endLine"] - right["line"] + 1, + ) + prior_span = base_pair_lengths.get(base_key) + if prior_span is None: + state = "new" + elif candidate_span > prior_span and state != "new": + state = "expanded" + baseline_lines = prior_span + + if state is None: + continue + identity = tuple( + sorted((item["file"], item["line"], item["endLine"]) for item in group) + ) + if identity in seen: + continue + seen.add(identity) + item: dict[str, Any] = { + "state": state, + "minimumTokens": minimum_tokens, + "locations": group, + "reference": REFERENCES["duplication"], + } + if state == "new": + item["baseline"] = "absent" + item["delta"] = "new" + elif state == "expanded": + item["delta"] = "expanded" + if baseline_lines is not None: + item["baselineSpanLines"] = baseline_lines + results.append(item) + return results + + +def write_raw(payload: dict[str, Any]) -> str: + descriptor, path = tempfile.mkstemp(prefix="code-complexity-", suffix=".json") + with os.fdopen(descriptor, "w", encoding="utf-8") as stream: + json.dump(payload, stream, indent=2, sort_keys=True) + stream.write("\n") + return path + + +def parser() -> argparse.ArgumentParser: + result = argparse.ArgumentParser(description=__doc__) + result.add_argument("--repo", default=".", help="Git repository to measure") + result.add_argument("--base", help="Base revision for changed-code measurement") + result.add_argument( + "--whole-repository", + action="store_true", + help="Measure every supported production source file without a baseline", + ) + result.add_argument("--all", action="store_true", help="Include every normalized record") + result.add_argument("--cyclomatic-review", type=int, default=DEFAULTS["cyclomaticReview"]) + result.add_argument("--nloc-review", type=int, default=DEFAULTS["nlocReview"]) + result.add_argument( + "--nested-structures-review", + type=int, + default=DEFAULTS["nestedStructuresReview"], + ) + result.add_argument( + "--parameter-count-review", + type=int, + default=DEFAULTS["parameterCountReview"], + ) + result.add_argument("--duplicate-tokens", type=int, default=DEFAULTS["duplicateTokens"]) + return result + + +def main() -> int: + args = parser().parse_args() + try: + if args.whole_repository and args.base: + raise MeasurementError("--base and --whole-repository cannot be combined.") + if not args.whole_repository and not args.base: + raise MeasurementError("--base is required unless --whole-repository is set.") + thresholds = { + "cyclomaticReview": args.cyclomatic_review, + "nlocReview": args.nloc_review, + "nestedStructuresReview": args.nested_structures_review, + "parameterCountReview": args.parameter_count_review, + "duplicateTokens": args.duplicate_tokens, + } + if any(value < 1 for value in thresholds.values()): + raise MeasurementError("Every threshold must be a positive integer.") + + repo = Path(args.repo).resolve() + if not repo.is_dir(): + raise MeasurementError(f"Repository directory does not exist: {repo}") + git(repo, "rev-parse", "--show-toplevel") + head = git(repo, "rev-parse", "HEAD").decode().strip() + base = None + if args.base: + base = git(repo, "rev-parse", "--verify", f"{args.base}^{{commit}}").decode().strip() + + lizard, lizardns, duplicate_module, lizard_version = load_analyzer() + all_current_paths = current_paths(repo) + supported_current, _ = source_paths(all_current_paths, repo, lizard) + + if args.whole_repository: + changed: dict[str, str | None] = {path: None for path in supported_current} + changed_lines = { + path: [(1, max(1, sum(1 for _ in (repo / path).open("rb"))))] + for path in supported_current + } + unsupported_changed: list[str] = [] + else: + changed = changed_paths(repo, base or args.base) + changed_lines = { + path: line_ranges(repo, base or args.base, path, old_path is None) + for path, old_path in changed.items() + } + supported_changed, unsupported_changed = source_paths(changed, repo, lizard) + changed = {path: changed[path] for path in supported_changed} + changed_lines = {path: changed_lines[path] for path in supported_changed} + + candidate_functions, candidate_duplicates, candidate_duplicate_rate = analyze( + repo, + supported_current, + lizard, + lizardns, + duplicate_module, + thresholds["duplicateTokens"], + ) + + base_functions: list[dict[str, Any]] = [] + base_duplicates: list[list[dict[str, Any]]] = [] + base_duplicate_rate: float | None = None + if base: + with tempfile.TemporaryDirectory(prefix="code-complexity-base-") as directory: + base_root = Path(directory) + possible_base_paths = base_paths(repo, base) + supported_base, _ = source_paths(possible_base_paths, base_root, lizard) + extracted = extract_base(repo, base, supported_base, base_root) + base_functions, base_duplicates, base_duplicate_rate = analyze( + base_root, + extracted, + lizard, + lizardns, + duplicate_module, + thresholds["duplicateTokens"], + ) + + changed_functions = [ + function + for function in candidate_functions + if function["file"] in changed + and ( + args.whole_repository + or intersects( + function["line"], + function["endLine"], + changed_lines.get(function["file"], []), + ) + ) + ] + + band_counts = {"low": 0, "moderate": 0, "high": 0, "veryHigh": 0} + maxima = { + "cyclomaticComplexity": 0, + "nloc": 0, + "nestedStructures": 0, + "parameterCount": 0, + "tokenCount": 0, + } + function_triggers: list[dict[str, Any]] = [] + + for function in changed_functions: + metrics = function["metrics"] + band = cyclomatic_band(metrics["cyclomaticComplexity"]) + band_counts[band] += 1 + for metric in maxima: + maxima[metric] = max(maxima[metric], metrics[metric]) + + baseline_function = baseline_match( + function, + base_functions, + changed.get(function["file"]), + ) + baseline_metrics = baseline_function["metrics"] if baseline_function else {} + is_new = bool(base and baseline_function is None) + triggered: dict[str, Any] = {} + references: list[str] = [] + + if metrics["cyclomaticComplexity"] >= thresholds["cyclomaticReview"]: + triggered["cyclomaticComplexity"] = metric_value( + metrics["cyclomaticComplexity"], + baseline_metrics.get("cyclomaticComplexity"), + band, + is_new, + ) + references.append(REFERENCES["cyclomaticComplexity"]) + if metrics["nloc"] > thresholds["nlocReview"]: + triggered["nloc"] = metric_value( + metrics["nloc"], baseline_metrics.get("nloc"), is_new=is_new + ) + references.append(REFERENCES["nloc"]) + if metrics["nestedStructures"] > thresholds["nestedStructuresReview"]: + triggered["nestedStructures"] = metric_value( + metrics["nestedStructures"], + baseline_metrics.get("nestedStructures"), + is_new=is_new, + ) + references.append(REFERENCES["nestedStructures"]) + if metrics["parameterCount"] >= thresholds["parameterCountReview"]: + triggered["parameterCount"] = metric_value( + metrics["parameterCount"], + baseline_metrics.get("parameterCount"), + is_new=is_new, + ) + references.append(REFERENCES["parameterCount"]) + + if triggered: + function_triggers.append( + { + "file": function["file"], + "line": function["line"], + "endLine": function["endLine"], + "symbol": function["symbol"], + "metrics": triggered, + "tokenCount": metrics["tokenCount"], + "references": sorted(set(references)), + } + ) + + duplication_triggers = duplicate_triggers( + candidate_duplicates, + base_duplicates, + changed, + changed_lines, + args.whole_repository, + thresholds["duplicateTokens"], + ) + + scope = { + "base": base, + "candidate": f"working-tree@{head}", + "changedProductionFiles": len(changed), + "sourceFilesAnalyzed": len(supported_current), + "changedFunctionsAnalyzed": len(changed_functions), + "excludedChangedPaths": sorted( + path + for path in (all_changed_paths(repo, base or args.base) if base else {}) + if excluded(path) + ), + } + summary = { + "cyclomaticBands": band_counts, + "maxima": maxima, + "observedCloneGroups": len(candidate_duplicates), + "duplicateRate": candidate_duplicate_rate, + "triggeredFunctions": len(function_triggers), + "triggeredCloneGroups": len(duplication_triggers), + } + limitations = [] + if unsupported_changed: + limitations.append( + { + "kind": "unsupported-language", + "paths": sorted(unsupported_changed), + } + ) + + tool = { + "name": "lizard", + "version": lizard_version, + "cloneDetector": { + "name": "lizard-duplicate", + "version": lizard_version, + }, + } + raw_payload = { + "schema": SCHEMA_VERSION, + "tool": tool, + "scope": scope, + "thresholds": thresholds, + "functions": candidate_functions, + "duplicates": candidate_duplicates, + "duplicateRate": candidate_duplicate_rate, + "baseFunctions": base_functions, + "baseDuplicates": base_duplicates, + "baseDuplicateRate": base_duplicate_rate, + "limitations": limitations, + } + raw_artifact = write_raw(raw_payload) + attention = bool(function_triggers or duplication_triggers) + status = "incomplete" if limitations else "attention" if attention else "clear" + output: dict[str, Any] = { + "schema": SCHEMA_VERSION, + "tool": tool, + "status": status, + "scope": scope, + "thresholds": thresholds, + "summary": summary, + "triggers": { + "functions": function_triggers, + "duplicates": duplication_triggers, + }, + "rawArtifact": raw_artifact, + } + if limitations: + output["limitations"] = limitations + if args.all: + output["records"] = { + "functions": candidate_functions, + "duplicates": candidate_duplicates, + } + print(json.dumps(output, indent=2, sort_keys=True)) + return 0 + except MeasurementError as error: + print( + json.dumps( + { + "schema": SCHEMA_VERSION, + "status": "incomplete", + "error": str(error), + }, + indent=2, + sort_keys=True, + ) + ) + return 2 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md b/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md new file mode 100644 index 0000000..f3c85cd --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/THIRD-PARTY-NOTICES.md @@ -0,0 +1,8 @@ +# Third-Party Notices + +The measurement script loads these unmodified Python wheels directly from this directory: + +- Lizard 1.24.0, checksum `a688bc607a891ff4a7836826f25742dc9c1bf648da3075dbd495e199e8848602`. Retain its [license](licenses/lizard/LICENSE.txt) and the [Apache License 2.0](licenses/lizard/APACHE-2.0.txt) referenced by licensed source headers. +- Pygments 2.19.2, checksum `86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b`. Retain its [license](licenses/pygments/LICENSE) and [authors](licenses/pygments/AUTHORS). + +The wheels remain subject to their included upstream notices and disclaimers. diff --git a/skills/measure-code-complexity/scripts/vendor/licenses/lizard/APACHE-2.0.txt b/skills/measure-code-complexity/scripts/vendor/licenses/lizard/APACHE-2.0.txt new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/licenses/lizard/APACHE-2.0.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/skills/measure-code-complexity/scripts/vendor/licenses/lizard/LICENSE.txt b/skills/measure-code-complexity/scripts/vendor/licenses/lizard/LICENSE.txt new file mode 100644 index 0000000..74a3411 --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/licenses/lizard/LICENSE.txt @@ -0,0 +1,30 @@ +Copyright Terry Yin and other contributors + +This software consists of voluntary contributions made by many +individuals. For exact contribution history, see the revision history. + +The following license applies to all parts of this software except as +documented below: + +==== + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +==== diff --git a/skills/measure-code-complexity/scripts/vendor/licenses/pygments/AUTHORS b/skills/measure-code-complexity/scripts/vendor/licenses/pygments/AUTHORS new file mode 100644 index 0000000..811c66a --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/licenses/pygments/AUTHORS @@ -0,0 +1,291 @@ +Pygments is written and maintained by Georg Brandl . + +Major developers are Tim Hatch and Armin Ronacher +. + +Other contributors, listed alphabetically, are: + +* Sam Aaron -- Ioke lexer +* Jean Abou Samra -- LilyPond lexer +* João Abecasis -- JSLT lexer +* Ali Afshar -- image formatter +* Thomas Aglassinger -- Easytrieve, JCL, Rexx, Transact-SQL and VBScript + lexers +* Maxence Ahlouche -- PostgreSQL Explain lexer +* Muthiah Annamalai -- Ezhil lexer +* Nikolay Antipov -- OpenSCAD lexer +* Kumar Appaiah -- Debian control lexer +* Andreas Amann -- AppleScript lexer +* Timothy Armstrong -- Dart lexer fixes +* Jeffrey Arnold -- R/S, Rd, BUGS, Jags, and Stan lexers +* Eiríkr Åsheim -- Uxntal lexer +* Jeremy Ashkenas -- CoffeeScript lexer +* José Joaquín Atria -- Praat lexer +* Stefan Matthias Aust -- Smalltalk lexer +* Lucas Bajolet -- Nit lexer +* Ben Bangert -- Mako lexers +* Max Battcher -- Darcs patch lexer +* Thomas Baruchel -- APL lexer +* Tim Baumann -- (Literate) Agda lexer +* Paul Baumgart, 280 North, Inc. -- Objective-J lexer +* Michael Bayer -- Myghty lexers +* Thomas Beale -- Archetype lexers +* John Benediktsson -- Factor lexer +* David Benjamin, Google LLC -- TLS lexer +* Trevor Bergeron -- mIRC formatter +* Vincent Bernat -- LessCSS lexer +* Christopher Bertels -- Fancy lexer +* Sébastien Bigaret -- QVT Operational lexer +* Jarrett Billingsley -- MiniD lexer +* Adam Blinkinsop -- Haskell, Redcode lexers +* Stéphane Blondon -- Procfile, SGF and Sieve lexers +* Frits van Bommel -- assembler lexers +* Pierre Bourdon -- bugfixes +* Martijn Braam -- Kernel log lexer, BARE lexer +* JD Browne, Google LLC -- GoogleSQL lexer +* Matthias Bussonnier -- ANSI style handling for terminal-256 formatter +* chebee7i -- Python traceback lexer improvements +* Hiram Chirino -- Scaml and Jade lexers +* Mauricio Caceres -- SAS and Stata lexers. +* Michael Camilleri, John Gabriele, sogaiu -- Janet lexer +* Daren Chandisingh -- Gleam lexer +* Ian Cooper -- VGL lexer +* David Corbett -- Inform, Jasmin, JSGF, Snowball, and TADS 3 lexers +* Leaf Corcoran -- MoonScript lexer +* Fraser Cormack -- TableGen lexer +* Gabriel Corona -- ASN.1 lexer +* Christopher Creutzig -- MuPAD lexer +* Daniël W. Crompton -- Pike lexer +* Pete Curry -- bugfixes +* Bryan Davis -- EBNF lexer +* Bruno Deferrari -- Shen lexer +* Walter Dörwald -- UL4 lexer +* Luke Drummond -- Meson lexer +* Giedrius Dubinskas -- HTML formatter improvements +* Owen Durni -- Haxe lexer +* Alexander Dutton, Oxford University Computing Services -- SPARQL lexer +* James Edwards -- Terraform lexer +* Nick Efford -- Python 3 lexer +* Sven Efftinge -- Xtend lexer +* Artem Egorkine -- terminal256 formatter +* Matthew Fernandez -- CAmkES lexer +* Paweł Fertyk -- GDScript lexer, HTML formatter improvements +* Michael Ficarra -- CPSA lexer +* James H. Fisher -- PostScript lexer +* Amanda Fitch, Google LLC -- GoogleSQL lexer +* William S. Fulton -- SWIG lexer +* Carlos Galdino -- Elixir and Elixir Console lexers +* Michael Galloy -- IDL lexer +* Naveen Garg -- Autohotkey lexer +* Simon Garnotel -- FreeFem++ lexer +* Laurent Gautier -- R/S lexer +* Alex Gaynor -- PyPy log lexer +* Richard Gerkin -- Igor Pro lexer +* Alain Gilbert -- TypeScript lexer +* Alex Gilding -- BlitzBasic lexer +* GitHub, Inc -- DASM16, Augeas, TOML, and Slash lexers +* Bertrand Goetzmann -- Groovy lexer +* Krzysiek Goj -- Scala lexer +* Rostyslav Golda -- FloScript lexer +* Andrey Golovizin -- BibTeX lexers +* Matt Good -- Genshi, Cheetah lexers +* Michał Górny -- vim modeline support +* Alex Gosse -- TrafficScript lexer +* Patrick Gotthardt -- PHP namespaces support +* Hubert Gruniaux -- C and C++ lexer improvements +* Olivier Guibe -- Asymptote lexer +* Phil Hagelberg -- Fennel lexer +* Florian Hahn -- Boogie lexer +* Martin Harriman -- SNOBOL lexer +* Matthew Harrison -- SVG formatter +* Steven Hazel -- Tcl lexer +* Dan Michael Heggø -- Turtle lexer +* Aslak Hellesøy -- Gherkin lexer +* Greg Hendershott -- Racket lexer +* Justin Hendrick -- ParaSail lexer +* Jordi Gutiérrez Hermoso -- Octave lexer +* David Hess, Fish Software, Inc. -- Objective-J lexer +* Ken Hilton -- Typographic Number Theory and Arrow lexers +* Varun Hiremath -- Debian control lexer +* Rob Hoelz -- Perl 6 lexer +* Doug Hogan -- Mscgen lexer +* Ben Hollis -- Mason lexer +* Max Horn -- GAP lexer +* Fred Hornsey -- OMG IDL Lexer +* Alastair Houghton -- Lexer inheritance facility +* Tim Howard -- BlitzMax lexer +* Dustin Howett -- Logos lexer +* Ivan Inozemtsev -- Fantom lexer +* Hiroaki Itoh -- Shell console rewrite, Lexers for PowerShell session, + MSDOS session, BC, WDiff +* Brian R. Jackson -- Tea lexer +* Christian Jann -- ShellSession lexer +* Jonas Camillus Jeppesen -- Line numbers and line highlighting for + RTF-formatter +* Dennis Kaarsemaker -- sources.list lexer +* Dmitri Kabak -- Inferno Limbo lexer +* Igor Kalnitsky -- vhdl lexer +* Colin Kennedy - USD lexer +* Alexander Kit -- MaskJS lexer +* Pekka Klärck -- Robot Framework lexer +* Gerwin Klein -- Isabelle lexer +* Eric Knibbe -- Lasso lexer +* Stepan Koltsov -- Clay lexer +* Oliver Kopp - Friendly grayscale style +* Adam Koprowski -- Opa lexer +* Benjamin Kowarsch -- Modula-2 lexer +* Domen Kožar -- Nix lexer +* Oleh Krekel -- Emacs Lisp lexer +* Alexander Kriegisch -- Kconfig and AspectJ lexers +* Marek Kubica -- Scheme lexer +* Jochen Kupperschmidt -- Markdown processor +* Gerd Kurzbach -- Modelica lexer +* Jon Larimer, Google Inc. -- Smali lexer +* Olov Lassus -- Dart lexer +* Matt Layman -- TAP lexer +* Dan Lazin, Google LLC -- GoogleSQL lexer +* Kristian Lyngstøl -- Varnish lexers +* Sylvestre Ledru -- Scilab lexer +* Chee Sing Lee -- Flatline lexer +* Mark Lee -- Vala lexer +* Thomas Linder Puls -- Visual Prolog lexer +* Pete Lomax -- Phix lexer +* Valentin Lorentz -- C++ lexer improvements +* Ben Mabey -- Gherkin lexer +* Angus MacArthur -- QML lexer +* Louis Mandel -- X10 lexer +* Louis Marchand -- Eiffel lexer +* Simone Margaritelli -- Hybris lexer +* Tim Martin - World of Warcraft TOC lexer +* Kirk McDonald -- D lexer +* Gordon McGregor -- SystemVerilog lexer +* Stephen McKamey -- Duel/JBST lexer +* Brian McKenna -- F# lexer +* Charles McLaughlin -- Puppet lexer +* Kurt McKee -- Tera Term macro lexer, PostgreSQL updates, MySQL overhaul, JSON lexer +* Joe Eli McIlvain -- Savi lexer +* Lukas Meuser -- BBCode formatter, Lua lexer +* Cat Miller -- Pig lexer +* Paul Miller -- LiveScript lexer +* Hong Minhee -- HTTP lexer +* Michael Mior -- Awk lexer +* Bruce Mitchener -- Dylan lexer rewrite +* Reuben Morais -- SourcePawn lexer +* Jon Morton -- Rust lexer +* Paulo Moura -- Logtalk lexer +* Mher Movsisyan -- DTD lexer +* Dejan Muhamedagic -- Crmsh lexer +* Adrien Nayrat -- PostgreSQL Explain lexer +* Ana Nelson -- Ragel, ANTLR, R console lexers +* David Neto, Google LLC -- WebGPU Shading Language lexer +* Kurt Neufeld -- Markdown lexer +* Nam T. Nguyen -- Monokai style +* Jesper Noehr -- HTML formatter "anchorlinenos" +* Mike Nolta -- Julia lexer +* Avery Nortonsmith -- Pointless lexer +* Jonas Obrist -- BBCode lexer +* Edward O'Callaghan -- Cryptol lexer +* David Oliva -- Rebol lexer +* Pat Pannuto -- nesC lexer +* Jon Parise -- Protocol buffers and Thrift lexers +* Benjamin Peterson -- Test suite refactoring +* Ronny Pfannschmidt -- BBCode lexer +* Dominik Picheta -- Nimrod lexer +* Andrew Pinkham -- RTF Formatter Refactoring +* Clément Prévost -- UrbiScript lexer +* Tanner Prynn -- cmdline -x option and loading lexers from files +* Oleh Prypin -- Crystal lexer (based on Ruby lexer) +* Nick Psaris -- K and Q lexers +* Xidorn Quan -- Web IDL lexer +* Elias Rabel -- Fortran fixed form lexer +* raichoo -- Idris lexer +* Daniel Ramirez -- GDScript lexer +* Kashif Rasul -- CUDA lexer +* Nathan Reed -- HLSL lexer +* Justin Reidy -- MXML lexer +* Jonathon Reinhart, Google LLC -- Soong lexer +* Norman Richards -- JSON lexer +* Corey Richardson -- Rust lexer updates +* Fabrizio Riguzzi -- cplint leder +* Lubomir Rintel -- GoodData MAQL and CL lexers +* Andre Roberge -- Tango style +* Georg Rollinger -- HSAIL lexer +* Michiel Roos -- TypoScript lexer +* Konrad Rudolph -- LaTeX formatter enhancements +* Mario Ruggier -- Evoque lexers +* Miikka Salminen -- Lovelace style, Hexdump lexer, lexer enhancements +* Stou Sandalski -- NumPy, FORTRAN, tcsh and XSLT lexers +* Matteo Sasso -- Common Lisp lexer +* Joe Schafer -- Ada lexer +* Max Schillinger -- TiddlyWiki5 lexer +* Andrew Schmidt -- X++ lexer +* Ken Schutte -- Matlab lexers +* René Schwaiger -- Rainbow Dash style +* Sebastian Schweizer -- Whiley lexer +* Tassilo Schweyer -- Io, MOOCode lexers +* Pablo Seminario -- PromQL lexer +* Ted Shaw -- AutoIt lexer +* Joerg Sieker -- ABAP lexer +* Robert Simmons -- Standard ML lexer +* Kirill Simonov -- YAML lexer +* Corbin Simpson -- Monte lexer +* Ville Skyttä -- ASCII armored lexer +* Alexander Smishlajev -- Visual FoxPro lexer +* Steve Spigarelli -- XQuery lexer +* Jerome St-Louis -- eC lexer +* Camil Staps -- Clean and NuSMV lexers; Solarized style +* James Strachan -- Kotlin lexer +* Tom Stuart -- Treetop lexer +* Colin Sullivan -- SuperCollider lexer +* Ben Swift -- Extempore lexer +* tatt61880 -- Kuin lexer +* Edoardo Tenani -- Arduino lexer +* Tiberius Teng -- default style overhaul +* Jeremy Thurgood -- Erlang, Squid config lexers +* Brian Tiffin -- OpenCOBOL lexer +* Bob Tolbert -- Hy lexer +* Doug Torrance -- Macaulay2 lexer +* Matthias Trute -- Forth lexer +* Tuoa Spi T4 -- Bdd lexer +* Erick Tryzelaar -- Felix lexer +* Alexander Udalov -- Kotlin lexer improvements +* Thomas Van Doren -- Chapel lexer +* Dave Van Ee -- Uxntal lexer updates +* Daniele Varrazzo -- PostgreSQL lexers +* Abe Voelker -- OpenEdge ABL lexer +* Pepijn de Vos -- HTML formatter CTags support +* Matthias Vallentin -- Bro lexer +* Benoît Vinot -- AMPL lexer +* Linh Vu Hong -- RSL lexer +* Taavi Väänänen -- Debian control lexer +* Immanuel Washington -- Smithy lexer +* Nathan Weizenbaum -- Haml and Sass lexers +* Nathan Whetsell -- Csound lexers +* Dietmar Winkler -- Modelica lexer +* Nils Winter -- Smalltalk lexer +* Davy Wybiral -- Clojure lexer +* Whitney Young -- ObjectiveC lexer +* Diego Zamboni -- CFengine3 lexer +* Enrique Zamudio -- Ceylon lexer +* Alex Zimin -- Nemerle lexer +* Rob Zimmerman -- Kal lexer +* Evgenii Zheltonozhskii -- Maple lexer +* Vincent Zurczak -- Roboconf lexer +* Hubert Gruniaux -- C and C++ lexer improvements +* Thomas Symalla -- AMDGPU Lexer +* 15b3 -- Image Formatter improvements +* Fabian Neumann -- CDDL lexer +* Thomas Duboucher -- CDDL lexer +* Philipp Imhof -- Pango Markup formatter +* Thomas Voss -- Sed lexer +* Martin Fischer -- WCAG contrast testing +* Marc Auberer -- Spice lexer +* Amr Hesham -- Carbon lexer +* diskdance -- Wikitext lexer +* vanillajonathan -- PRQL lexer +* Nikolay Antipov -- OpenSCAD lexer +* Markus Meyer, Nextron Systems -- YARA lexer +* Hannes Römer -- Mojo lexer +* Jan Frederik Schaefer -- PDDL lexer + +Many thanks for all contributions! diff --git a/skills/measure-code-complexity/scripts/vendor/licenses/pygments/LICENSE b/skills/measure-code-complexity/scripts/vendor/licenses/pygments/LICENSE new file mode 100644 index 0000000..446a1a8 --- /dev/null +++ b/skills/measure-code-complexity/scripts/vendor/licenses/pygments/LICENSE @@ -0,0 +1,25 @@ +Copyright (c) 2006-2022 by the respective authors (see AUTHORS file). +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/skills/measure-code-complexity/scripts/vendor/lizard-1.24.0-py2.py3-none-any.whl b/skills/measure-code-complexity/scripts/vendor/lizard-1.24.0-py2.py3-none-any.whl new file mode 100644 index 0000000..7e8f60c Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/lizard-1.24.0-py2.py3-none-any.whl differ diff --git a/skills/measure-code-complexity/scripts/vendor/pygments-2.19.2-py3-none-any.whl b/skills/measure-code-complexity/scripts/vendor/pygments-2.19.2-py3-none-any.whl new file mode 100644 index 0000000..3ec3f10 Binary files /dev/null and b/skills/measure-code-complexity/scripts/vendor/pygments-2.19.2-py3-none-any.whl differ diff --git a/skills/modular-design/SKILL.md b/skills/modular-design/SKILL.md index 4620ee4..935991c 100644 --- a/skills/modular-design/SKILL.md +++ b/skills/modular-design/SKILL.md @@ -1,55 +1,85 @@ --- name: modular-design -description: Defines an evidence-backed modular architecture standard. Use when designing or assessing modules, interfaces, dependencies, ownership, or seams. +description: Teaches structural design through information hiding, deep modules, cohesive ownership, stable interfaces, and change locality. Use when writing or assessing code, boundaries, contracts, dependencies, seams, or change propagation. metadata: - invocation: model -disable-model-invocation: false + type: teaching +disable-model-invocation: true --- # Modular Design -**Information hiding** makes code safer to change by assigning cohesive knowledge and change-prone decisions to modules whose callers learn only a small, stable contract. +Teaches a caller to make the smallest coherent change through deep modules whose owned knowledge and likely changes remain local. ## Process -Apply this standard inside the caller's workflow. Let the caller own repository inspection, quality priorities, design comparison, implementation, verification, and artifacts; this skill supplies architecture knowledge without starting a separate process or producing its own output. Explicit project constraints, domain language, and architecture decisions govern where they conflict with the baseline. +### 1. Fix the structural basis -## Standard +Use the caller's confirmed behaviour, outcome, repository guidance, domain language, architecture decisions, relevant source, contracts, and tests. Inspect only evidence that is missing or stale. Follow explicit project authorities and established language and framework idioms when they conflict with this baseline. -### Name the architecture precisely +Treat a **module** as any cohesive capability with an interface and implementation: a function, object, component, package, process, service, or tier-spanning slice. Treat its **interface** as everything callers must know, including operations, data, invariants, ordering, errors, configuration, effects, and material performance characteristics. Do not equate modules with files, classes, layers, or deployment units. -- A **module** is a cohesive capability with an interface and implementation, regardless of whether code expresses it as a function, object, package, process, or tier-spanning slice. -- An **interface** is everything callers must know to use the module correctly, including behaviour, data shapes, invariants, ordering, errors, configuration, side effects, and material performance characteristics. It is broader than a language `interface` declaration. -- An **implementation** is the hidden representation, policy, algorithm, sequencing, framework detail, and collaboration that fulfils the interface. -- A **seam** is a controlled place where behaviour can be observed or substituted without editing the calling location. -- An **adapter** translates between a module's contract and a technology, protocol, framework, or external system. +Use confirmed behaviour and applicable quality requirements as constraints on ownership, boundaries, and contracts. Do not redefine those requirements during structural design. -Use this vocabulary for reasoning while preserving established project and framework names in code and reports. +### 2. Assign each decision to one owner -### Hide owned knowledge +Name the behaviour and every rule, invariant, protocol, representation, sequence, side effect, or framework decision it introduces or changes. Keep each with its natural existing owner when that owner remains coherent; otherwise create the smallest boundary that owns the complete concern. An owner has the knowledge and authority needed to uphold the decision, not merely the nearest file or conventional technical layer. -Decompose around difficult, consequential, or change-prone knowledge. Give one module ownership of each representation, invariant, policy, protocol, sequencing rule, or framework decision that other modules should not repeat. A change to hidden knowledge should remain behind its interface unless the promised behaviour changes. +Represent each material decision once. Co-locate elements that change for the same current, evidenced reason. Separate elements when their responsibilities and axes of change differ. Prefer domain and capability boundaries over uniform file sizes or technical-layer symmetry. -### Prefer deep cohesive modules +Keep derived knowledge behind the owner of its source representation. When another module needs a fact such as a total, classification, eligibility, or transition derived from owned state, use or add a domain-meaningful owner operation instead of making the caller traverse that state. Let the caller derive it only when the representation is deliberately public and the derivation belongs to the caller's own policy. -Apply **deep modules**: make the caller-visible interface markedly simpler than the cohesive capability it exposes. Remove or absorb shallow wrappers that repeat another interface, scatter one decision across callers, or add navigation without hiding knowledge. +Check these contrasts: -Use **cohesion and coupling** qualitatively. Keep knowledge that changes for the same reason together; separate unrelated actors, models, or policies. Reduce cross-module knowledge, coordination, cycles, and change propagation while retaining necessary collaboration. Do not optimize file size, class count, method count, or mechanical coupling scores as substitutes for architectural evidence. +- **Local rule:** put a pricing threshold in the pricing policy that decides it. **Leaked rule:** repeat it in a controller, job, validator, and their tests. +- **Owned derivation:** ask an order for `totalWeightGrams()` when it owns line weights and quantities. **Leaked derivation:** make delivery, fulfilment, and reporting each traverse order lines to reconstruct that fact. +- **Cohesive size:** keep a large parser together when its grammar and invariants change as one concern. **Fragmented size:** split it only to satisfy a line or class count, making one grammar change cross several files. +- **Damaging coordinator:** reconsider even a short coordinator when it knows every participant's order, data shape, and error handling; brevity does not make scattered knowledge cohesive. -### Choose an idiomatic realization +### 3. Design a deep interface -Prefer object-oriented realization where the language and framework make it natural: objects own identity, state, invariants, and cohesive behaviour; purposeful action or use-case entry points hide a complete operation; collaborators are composed; and nominal interfaces express meaningful variation or ownership boundaries. +Apply **information hiding** and **deep modules**. Give callers substantial cohesive capability through a comparatively simple, domain-meaningful contract. Minimise what callers must know rather than method count. Hide representations, mechanisms, sequencing, framework details, and policies that callers do not need. Make required inputs, outcomes, failures, ordering, and effects explicit. -Treat functions, closures, structural types, and language modules as equivalent realizations when they provide the same ownership, contract, and hiding. In frontend frameworks, keep components and framework-specific state or effect primitives focused on presentation and interaction, and place durable policy behind framework-neutral modules when that separation is cohesive. Framework-owned code may use framework types at its own edge. +Keep the contract narrower and more stable than the decisions behind it without combining unrelated knowledge merely to appear deep. A design interface does not require a language `interface`, base class, wrapper, or extra file. -### Load only applicable techniques +Check these contrasts: -Read [Modular Design Techniques](references/TECHNIQUES.md) when evidence presents a volatile mechanism, application-to-technology boundary, competing domain model, need for controlled observation or substitution, entangled deterministic policy and effects, or an architectural promise that needs repeatable protection. Use only the technique whose stated condition is present. +- **Deep:** `reservation.confirm(command)` owns validation, state transition, persistence sequencing, and the confirmation outcome. **Shallow:** callers invoke `validate`, `markConfirmed`, `save`, and `publish` in the required order. +- **Hidden vendor protocol:** an adapter accepts checkout terms and maps vendor fields, units, and expected failures. **Leaked protocol:** controllers and policies know `vendorAmount`, vendor error classes, and response codes. +- **Owned boundary:** retain a layer that translates, authorises, applies policy, preserves compatibility, observes, or coordinates an application conversation. **Pass-through:** absorb a layer whose only act is forwarding the same arguments and result to another contract. + +### 4. Keep the change coherent and earned + +Make the least production, test, and supporting change that completely delivers the confirmed behaviour and leaves its knowledge local. Fewest lines or files is not the goal. Permit a bounded enabling refactor only when the behaviour cannot fit coherently without it; alter no more surrounding structure than the behaviour needs. + +Keep a stable local concrete dependency direct. Add an abstraction only for current evidence of meaningful variation, isolated observation, replacement, staged migration, a volatile external mechanism, a material technology or ownership boundary, or separation of stable policy from mechanism. Reuse an existing extension point only when its contract fits the present behaviour. Do not add hypothetical implementations, options, generic services, interface-per-class, universal repositories, plugin systems, or unrelated cleanup. + +Use objects for cohesive identity, state, lifecycle, and invariants when they fit. Use functions, closures, structural types, modules, components, composition, and framework primitives when they preserve the same ownership with less machinery. Use inheritance only for genuine substitutability or a required framework extension. + +### 5. Compare material structural choices + +When introducing or substantially changing a public interface, module boundary, seam, or dependency direction, load [Design It Twice](references/DESIGN-IT-TWICE.md). Produce at least two genuinely different responsibility or contract designs, compare them, and select the smallest design supported by current evidence. Routine work that fits an established coherent boundary proceeds directly. + +The caller produces and selects the alternatives inside its own workflow. Do not dispatch a design workflow, require parallel agents, or turn the comparison into a separate artefact unless the caller's outcome requires one. + +### 6. Apply only triggered techniques + +Classify triggers from the evidence already loaded, then read only the smallest applicable reference. An ordinary ownership choice, one domain vocabulary, one conditional, or the mere possibility of future change is not a trigger: + +- Load [Dependency Techniques](references/DEPENDENCY-TECHNIQUES.md) when stable policy directly knows a volatile mechanism; a material technology or ownership boundary needs translation; controlled substitution, observation, replacement, or migration is required; composition competes with inheritance; or polymorphic substitutability is in question. +- Load [Domain Techniques](references/DOMAIN-TECHNIQUES.md) only when one term has evidenced competing meanings or rules, domain language and observed change patterns disagree with the current boundary, or co-location versus extraction remains a material choice after the ownership analysis. Do not load it for a single coherent domain model or an ordinary file-placement choice. +- Load [Decision and Effect Techniques](references/EFFECT-TECHNIQUES.md) only when substantial deterministic policy across multiple cases or transitions is entangled with I/O, time, mutable state, or framework lifecycle effects. Do not load it for one calculation or conditional merely because the surrounding operation performs I/O. + +Do not load references to search for a reason to use a technique. Use one fitting mechanism when triggers overlap. Treat SOLID and named patterns as diagnostic vocabulary, not mandatory architecture; treat smells and metrics only as prompts to investigate a concrete mechanism and consequence. + +### 7. Trace locality + +Trace one plausible current-project change through the proposed owner, interface, consumers, implementation, and tests. Prefer a change suggested by requirements, integrations, repository history, or present volatility over an imagined future. + +Reconsider the design when the same decision remains duplicated, elements that always change together are split, an owner changes mostly for unrelated reasons, callers still coordinate hidden sequencing, or one conceptual change requires scattered edits. Do not substitute file size, class count, method count, churn, coupling scores, complexity thresholds, or speculative agent-context savings for this trace. + +Keep the owner, caller-visible contract, hidden decisions, locality trace, triggered technique or material comparison, and unresolved structural uncertainty explicit in the caller's workflow. ## Rules -- Keep a stable local concrete dependency direct when no meaningful knowledge, variation, isolation, observation, or migration need justifies another abstraction. -- Introduce a language interface only when callers need a stable contract distinct from a realization; an interface that mirrors one concrete type without hiding knowledge is ceremony. -- Let a cohesive module contain several internal actions. A class or function with one entry point is valuable only when it hides a complete capability rather than forwards the call. -- Prefer composition in object-oriented code; use inheritance for a genuine substitutable type or required framework extension contract. -- Optimize the knowledge callers require, not repository fragmentation or speculative token savings. Reduced agent context is an inference to verify, not proof of correctness. +- Prefer project evidence over generic architecture advice. +- Preserve the complete confirmed behaviour while improving structure; do not trade correctness or scope for aesthetic purity. diff --git a/skills/modular-design/agents/openai.yaml b/skills/modular-design/agents/openai.yaml index 5214400..d97ee31 100644 --- a/skills/modular-design/agents/openai.yaml +++ b/skills/modular-design/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Modular Design' - short_description: 'Apply an evidence-backed modular design standard' + short_description: 'Design deep modules with local change' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md b/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md new file mode 100644 index 0000000..0ab6087 --- /dev/null +++ b/skills/modular-design/references/DEPENDENCY-TECHNIQUES.md @@ -0,0 +1,48 @@ +# Dependency Techniques + +Load only for a triggered dependency, technology boundary, seam, composition, or substitutability decision. A contract in design does not require a language `interface`. + +## Invert volatile mechanism knowledge + +Apply **dependency inversion** when stable domain or application policy directly knows a materially volatile framework, device, vendor, persistence, transport, or delivery mechanism. Define the smallest policy-owned contract in policy language and make the mechanism satisfy it. + +- **Good:** invoicing policy asks a `TaxRateSource` for the rate and the vendor adapter owns authentication, wire fields, and response mapping. +- **Bad:** invoicing imports vendor request types and switches on vendor status codes, or adds an interface that repeats one stable local calculator without changing dependency knowledge. + +Cost: an owned contract and composition wiring must be maintained. Keep a stable local concrete dependency direct when inversion creates only interface-per-class indirection. + +## Isolate a material boundary + +Apply **ports and adapters** when an application-purpose conversation must remain independent of a material external technology or ownership boundary, isolated execution, replacement, staged migration, or multiple implementations. State the port in the application's language; let adapters translate UI, persistence, network, vendor, or test technology. Framework types stay at framework-owned edges. + +- **Good:** `PlaceOrder` accepts an application command and returns an application outcome while HTTP and database adapters translate at the edges. +- **Bad:** wrap every framework call, mirror a vendor SDK method-for-method, or add a generic provider registry for one fixed integration. + +Cost: translation, wiring, and sometimes duplicated boundary types. A concrete adapter without a language interface can still be the right port boundary when it hides the protocol and no separate runtime contract is earned. + +## Add a controlled seam + +Add a **seam** when substitution, observation, replacement, or staged migration requires behaviour to vary without editing the calling location. Use the smallest enabling point: a parameter, callback, collaborator, provider, module export, composition-root binding, or framework facility. + +- **Good:** inject a clock where expiry policy needs deterministic time. +- **Bad:** introduce factories and provider interfaces around every deterministic local function in case tests might mock it. + +Cost: another variation point callers and maintainers must understand. Prefer direct behaviour when it is local, stable, and observable through its supported outcome. + +## Prefer composition and delegation + +Use composition or delegation when a capability can be assembled from independently owned behaviours without claiming an is-a relationship. Keep delegation deep: the composing owner must add policy, translation, sequencing, or a simpler capability rather than merely repeat another contract. + +- **Good:** a `Checkout` delegates tax calculation and payment authorisation while owning their ordering and checkout outcome. +- **Bad:** `PaymentService.process()` only forwards to `PaymentProcessor.process()` with identical inputs, outputs, and responsibility. + +Cost: extra navigation and wiring. Absorb a delegation layer that owns no decision. + +## Require genuine substitutability + +Use inheritance or polymorphism only when every subtype can honour the complete base contract for all supported callers without strengthened preconditions, weakened outcomes, surprising effects, or type tests. Prefer composition for optional behaviour or shared implementation that does not form a stable substitutable concept. + +- **Good:** supported storage adapters honour the same explicit read/write/error contract. +- **Bad:** `ReadOnlyRepository extends Repository` but throws from inherited `save`, forcing callers to inspect its concrete type. + +Cost: base-contract evolution constrains every subtype. A required framework extension is valid when its lifecycle contract is honoured, even when composition would otherwise be preferred. diff --git a/skills/modular-design/references/DESIGN-IT-TWICE.md b/skills/modular-design/references/DESIGN-IT-TWICE.md new file mode 100644 index 0000000..4d4443a --- /dev/null +++ b/skills/modular-design/references/DESIGN-IT-TWICE.md @@ -0,0 +1,28 @@ +# Design It Twice + +Load this reference only for a material new or substantially changed public interface, module boundary, seam, or dependency direction. + +## Form two real designs + +Describe at least two alternatives that differ in ownership, caller knowledge, contract, or dependency direction. Renaming, moving the same class, changing interface syntax, or comparing a credible design with an obvious straw design does not count. + +Keep each alternative only detailed enough to decide. For each, state: + +- which module owns the rule, representation, sequence, and effects; +- what callers must know and do; +- what the interface promises, including failure and effects; +- which dependencies point toward which owner; +- how tests observe the promised behaviour; and +- how one plausible evidenced change propagates. + +Compare interface depth, caller burden, cohesion, locality, dependency direction, testability, transition cost, and speculative machinery. Select the smallest coherent design supported by current evidence; record the losing alternative's material disadvantage and any uncertainty that could reverse the choice. + +## Contrast: delivery quote boundary + +Suppose checkout needs a delivery quote from one current carrier. + +**Design A — concrete checkout adapter:** `DeliveryQuotes` depends directly on `FastShipDeliveryQuotes`, which translates FastShip fields and failures into checkout terms. This hides the vendor protocol with no language interface. It is preferable when one implementation is approved, the concrete adapter is replaceable at the composition root, and tests can observe policy without a distinct runtime contract. + +**Design B — policy-owned port:** `DeliveryQuotes` depends on a checkout-owned `DeliveryQuoteSource`; `FastShipDeliveryQuoteSource` implements it. This adds a separate stable contract. It is preferable when isolated execution, multiple implementations, staged replacement, or an ownership boundary currently requires the policy to remain independent of the concrete adapter. + +Both designs isolate vendor translation. Selecting B merely because another carrier might exist someday is speculative; selecting A when application policy must directly import vendor types leaves the boundary incomplete. diff --git a/skills/modular-design/references/DOMAIN-TECHNIQUES.md b/skills/modular-design/references/DOMAIN-TECHNIQUES.md new file mode 100644 index 0000000..7b65338 --- /dev/null +++ b/skills/modular-design/references/DOMAIN-TECHNIQUES.md @@ -0,0 +1,32 @@ +# Domain Techniques + +Load only when domain meanings, observed change contours, or co-location and extraction are materially in question. + +## Separate competing meanings + +Apply **bounded contexts** when the same term has competing meanings, rules, lifecycles, or representations. Keep one ubiquitous language and model inside each evidenced context; translate explicitly at their boundary. + +- **Good:** Sales `Customer` owns prospects and purchasing eligibility while Support `Customer` owns service entitlement, with an explicit identity translation. +- **Bad:** one universal `Customer` accumulates nullable sales, billing, fulfilment, and support state, so every change affects unrelated callers. + +Cost: translation and explicit context ownership. Do not create bounded contexts merely because departments or folders have different names. + +## Follow conceptual contours + +Apply **conceptual contours** when domain language and observed axes of change reveal a more natural capability grain than current technical layers or uniform class sizes. Keep entity identity, state, invariants, and cohesive behaviour together. Use a standalone domain service only for a significant process that belongs naturally to no entity or value object. + +- **Good:** an `Allocation` owns quantity invariants and release behaviour that always change together. +- **Bad:** split `AllocationValidator`, `AllocationUpdater`, and `AllocationRules` by technical action, making one invariant change cross all three. + +Cost: a domain-shaped module may be larger or cross conventional layer boundaries. That is acceptable when its contract remains clear and changes stay local. + +## Co-locate or extract for evidenced locality + +Co-locate code when it shares one owner and changes for the same evidenced reason. Extract when a complete sub-concern has a distinct contract, reuse by real consumers, independent volatility, or enough hidden knowledge to repay navigation. + +- **Good co-location:** keep a component's one-use rendering helper beside the component while they evolve together. +- **Bad extraction:** move every small helper into a global utilities module, coupling unrelated capabilities to a grab bag. +- **Good extraction:** isolate a tax-jurisdiction rule used by checkout and invoicing behind one policy-owned contract. +- **Bad co-location:** duplicate that rule in both consumers to avoid adding a file. + +Cost: extraction adds naming, navigation, and a contract; co-location can overload an owner when change reasons diverge. Decide from ownership and propagation rather than size. diff --git a/skills/modular-design/references/EFFECT-TECHNIQUES.md b/skills/modular-design/references/EFFECT-TECHNIQUES.md new file mode 100644 index 0000000..c29c327 --- /dev/null +++ b/skills/modular-design/references/EFFECT-TECHNIQUES.md @@ -0,0 +1,14 @@ +# Decision and Effect Techniques + +Load only when substantial deterministic decisions are entangled with I/O, time, mutable state, or framework lifecycle effects. + +## Form a functional core and imperative shell + +Apply **functional core, imperative shell** when explicit input values can drive substantial deterministic policy while a narrow edge performs I/O, time access, mutation, or framework integration. The core returns decisions or intended effects; the shell obtains inputs, executes effects, and maps failures. + +- **Good:** a renewal function receives subscription state and `now`, then returns `renew`, `expire`, or `no-op`; a job handler loads state, calls it, and performs the selected effect. +- **Bad:** policy reads the system clock, database, queue, and configuration throughout nested branches, so every case requires effectful setup and policy changes alter orchestration. + +Preserve stateful ownership when identity, lifecycle, effect ordering, transactions, or invariant enforcement is intrinsic. Do not turn an application into a bag of pure functions with an unencapsulated shell. + +Cost: explicit values and decision types cross the core boundary, and the shell must translate effect failures honestly. Use the technique only when the deterministic policy is substantial enough to repay that contract. diff --git a/skills/modular-design/references/TECHNIQUES.md b/skills/modular-design/references/TECHNIQUES.md deleted file mode 100644 index 5c27e2b..0000000 --- a/skills/modular-design/references/TECHNIQUES.md +++ /dev/null @@ -1,33 +0,0 @@ -# Modular Design Techniques - -Load this reference only when repository evidence satisfies a technique's condition. Information hiding and the standard in `SKILL.md` remain authoritative; a pattern earns its place by solving the evidenced boundary problem. - -## Protect policy from a volatile mechanism - -Apply **dependency inversion** when stable domain or application policy directly knows a materially volatile framework, device, vendor, persistence, transport, or delivery mechanism. Define the smallest policy-owned contract in the policy's language and make the mechanism satisfy it. Keep a stable local concrete dependency direct when inversion would only create an interface-per-class and wiring. - -## Isolate an application conversation - -Apply **ports and adapters** when one application capability must support multiple technologies, replacement, isolated execution, or a material external boundary. Let a port describe the purpose of the conversation and let adapters translate UI, persistence, network, vendor, or test technology. Keep framework types at framework-owned edges and avoid wrapping every framework call. - -## Separate domain models - -Apply **bounded contexts** when the same term or concept has competing meanings, rules, or models. Keep one ubiquitous language inside each evidenced context and translate explicitly between them. - -Apply **conceptual contours** when domain language and observed axes of change reveal a more natural capability grain than technical layers or uniform class sizes. Keep cohesive entity behaviour and invariants together; use a standalone domain service only for a significant process that belongs to no entity or value object. - -## Create purposeful variation or observation - -Add a **seam** when testing, diagnosis, replacement, observation, or staged migration needs controlled variation. Use the smallest existing enabling point—such as a parameter, collaborator, provider, module export, or framework facility—before adding a nominal interface. Direct behaviour remains preferable when it is already local, stable, and observable. - -## Separate decisions from effects - -Apply **functional core, imperative shell** when substantial deterministic policy is entangled with I/O, time, mutable state, or framework lifecycle behaviour. Express the policy as transformations of explicit values and keep effects in a thin shell. Preserve stateful objects when identity, lifecycle, effect ordering, or invariant ownership is intrinsic; do not turn the shell into the unencapsulated application. - -## Preserve an architectural promise - -Define an **architecture fitness function** when a material contract, dependency rule, quality threshold, or runtime characteristic has a faithful objective signal. State the property, signal, expected result, and execution point. Prefer contract tests, dependency rules, adapter conformance, cycle checks, or measured runtime thresholds; retain qualitative review when a metric would be a misleading proxy. - -## Realize a capability entry point - -Use an action object, use-case class, function, command, or framework-native entry point when it exposes one meaningful actor goal and hides cohesive sequencing, policy, invariants, failure handling, or transaction behaviour. Reuse the entry point when several delivery mechanisms need the same capability. Absorb or remove it when it merely forwards to another module or becomes generic for hypothetical reuse. diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md deleted file mode 100644 index 475567d..0000000 --- a/skills/pr/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: pr -description: Publishes the current branch and creates or updates its pull request. Use when committed work is ready for review. -metadata: - invocation: user -disable-model-invocation: true ---- - -# Pull Request - -Publish the current branch through the repository's available setup and represent its complete work in one pull request. - -## Process - -### 1. Inspect the repository setup - -Inspect repository instructions, Git status, the current branch, its remote and base, available publication tooling, and any existing pull request for the branch. Use the user-supplied base or the repository default. When no usable publication path exists, report the blocker; otherwise the publication context is explicit. - -### 2. Establish the grouped work - -Invoke `$commit` when eligible changed work remains, then inspect the commit history and **whole-branch change scope** against the base. When the branch has no publishable change, report it and stop; otherwise the complete pull-request scope is explicit. - -### 3. Write the pull request - -Write a `type[(scope)][!]: description` title that summarizes the complete grouped work. Apply **BLUF** by writing one succinct paragraph that begins directly with what the grouped work changes and why. Follow additional repository requirements only when they explicitly mandate them. - -### 4. Publish and verify - -Use the available repository mechanism to publish the current branch without rewriting remote history and create or update its one pull request. Make it ready for review unless the user requested a draft. Verify the head, base, title, body, and review state, then return the pull-request URL. diff --git a/skills/pull-request/SKILL.md b/skills/pull-request/SKILL.md new file mode 100644 index 0000000..3981cc5 --- /dev/null +++ b/skills/pull-request/SKILL.md @@ -0,0 +1,19 @@ +--- +name: pull-request +description: Publishes the current branch as one concise verified pull request. Use when the branch is ready for external review. +metadata: + type: utility +disable-model-invocation: true +--- + +# Pull Request + +Publishes the complete branch for review without advancing it further. + +## Process + +Assign the entire process below to one fresh agent with the user's request and repository path. Have it invoke `$commit` when eligible uncommitted work belongs to the branch, compare the whole branch with its base, then use the repository's native tools to push without rewriting history before creating or updating one pull request. + +Use one **Conventional Commit** title for the complete outcome. Write the first body paragraph as three short sentences covering what, why, and how. Add a short testing paragraph only when existing tests provide material behavioural evidence; describe the behaviour covered and any material gap, not the suite, coverage, metrics, or publication-time execution, and do not run tests. + +Have the fresh agent read back the title, URL, head, base, state, and published revision. Return the title and URL, adding only a material blocker or excluded work when necessary, and retain only that result. Stop without reviewing, merging, releasing, or deploying. diff --git a/skills/pr/agents/openai.yaml b/skills/pull-request/agents/openai.yaml similarity index 57% rename from skills/pr/agents/openai.yaml rename to skills/pull-request/agents/openai.yaml index b844df6..a117e71 100644 --- a/skills/pr/agents/openai.yaml +++ b/skills/pull-request/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Pull Request' - short_description: 'Publish a concise pull request' + short_description: 'Publish one concise verified pull request' policy: allow_implicit_invocation: false diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index c6c4cfc..9134b21 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,37 +1,49 @@ --- name: research -description: Researches questions against high-trust primary sources and persists cited reports. Use when a durable evidence-backed answer is needed. +description: Investigates a material subject against high-trust sources and writes a trusted cited report. Use when a material question needs durable external evidence. metadata: - invocation: model -disable-model-invocation: false + type: utility +disable-model-invocation: true --- # Research -**Rapid evidence assessment** turns a scoped question into an auditable report grounded in high-trust primary sources. +Investigates a material subject in a fresh agent and hands back a trusted report for the consumer to synthesize. ## Process -### 1. Define the research contract +### 1. Fix the subject and scope -Define the research question, intended use, scope, exclusions, currency needs, and source hierarchy. Inspect task-relevant repository context and `docs/research/` for related reports before searching. Resolve ambiguity that could materially change the investigation. The research contract and applicable prior evidence are explicit. +Use the request and caller context to state what the research is for and what it covers. Resolve discoverable scope without questioning. Ask the user only when an ambiguity could materially change the investigation. Treat every invocation as standalone; do not inspect or maintain previous research reports. -### 2. Assign the investigation +Use `docs/research/` as the default output directory unless the caller specifies another destination. Keep the investigation within authorised read and report-write boundaries. -Give a fresh agent the complete research contract, relevant repository context, primary-source standard, and output contract. One fresh agent owns source discovery, appraisal, synthesis, and report writing; the caller verifies the finished report. +### 2. Start the fresh investigation -### 3. Discover and appraise primary evidence +Start exactly one fresh agent with the fixed subject and scope, relevant task-local evidence, available source tools, output destination, source rules, report template, and stopping rule. Do not supply a desired answer. The fresh agent owns discovery, source appraisal, thematic organisation, report writing, and report verification as one evidence chain; it does not delegate the investigation again. -Discover the strongest applicable primary evidence, including official documentation, source code, standards, original publications, first-party APIs, and first-party data. Use secondary sources only as discovery leads, then apply **backward citation searching** to trace material claims to their originals. Critically appraise authority and access, validity, currency, applicability, completeness, and bias. Primary-source status sets the hierarchy; appraisal determines the trust warranted. The evidence set is relevant, current enough for the question, and traceable. +Require the fresh agent to: -### 4. Synthesize the findings +- identify the material claims and areas needed to cover the scope, then select source types capable of establishing each one; +- prefer primary, original, official, or owning sources; use an authoritative secondary source when it is itself appropriate to the claim, and trace its material claims to original evidence where possible; +- treat authority as claim-relative: an originator can establish what a practice says, but that alone does not prove its effectiveness; +- corroborate material claims through genuinely independent evidence routes where available, and seek credible disagreement, contrary evidence, and important gaps; +- appraise what each source can establish, including its authority, validity, currency, applicability, completeness, incentives, and consistency with underlying evidence; +- distinguish sourced fact from material inference and distinguish missing evidence from evidence against; and +- stop when the scope has adequate high-trust coverage, conflicts and limitations are recorded, and further searching is unlikely to add materially different findings. -Compare independent evidence through **triangulation**, treating sources that repeat the same upstream claim as one evidence route. Test emerging conclusions through **falsification** by seeking contrary evidence and plausible alternatives. Distinguish direct evidence, inference, conflict, and unknowns; narrow or qualify conclusions when the evidence cannot support a stronger answer. Stop discovery when each material claim is supported or explicitly unresolved and further primary-source work is unlikely to change the answer. Every material finding is proportionate to the evidence. +### 3. Write the report -### 5. Write the research report +Create a new standalone Markdown report using [the research report template](assets/research-report-template.md). Organise `Findings` by human-readable themes rather than by source. Cite every material claim with numbered references such as `[1]`, reuse a source's number, and provide the matching numbered links under `Sources`. -Persist the result at `docs/research/YYYYMMDD-{research-title}.md` using [the research report template](assets/research-report-template.md). Use a concise lowercase hyphenated title and claim-level links to primary evidence. Replace every placeholder, retain only applicable lifecycle fields, and complete every applicable section. Record the research date, material search locations or approaches, appraisal basis, and synthesis method for **auditability** without retaining the raw search trail. When related research already exists, apply [the research report lifecycle](references/REPORT-LIFECYCLE.md). The report is concise, auditable, and proportionate to its evidence. +Write for human readers. Use natural language, varied sentence length, short coherent paragraphs, descriptive subheadings, and restrained bold, italics, lists, or tables where they improve comprehension. Identify material inference explicitly. -### 6. Verify and hand off +Keep the five template sections. `Scope` only explains what the research was for and what subject or information need it covered. Give each conflict and limitation its own paragraph; state `None identified.` when applicable. -Verify that each material claim is supported by its cited primary source, evidence routes are genuinely independent, every link and relative report path resolves, conflicts and uncertainty are visible, and the recorded method makes the investigation auditable. Return the report path, concise concrete findings, and unresolved limitations to the caller. The caller receives a validated durable result without the raw search context. +### 4. Verify the trusted report + +Require the fresh agent to re-read the finished report and verify that every material claim is supported by its cited source; citations and source numbers resolve; links open to the identified evidence; independent routes are not duplicate retellings of one upstream claim; conflicts, limitations, and material inferences are visible; all five sections are present; and the writing is coherent and easy to navigate. It corrects report defects before returning. + +## Handoff + +Return only the finished report path to the user or caller. Retain none of the investigation transcript in the calling thread and require no duplicate caller verification. Stop after handoff; the consumer owns every overall synthesis, conclusion, recommendation, decision, and downstream mutation. diff --git a/skills/research/agents/openai.yaml b/skills/research/agents/openai.yaml index 0f9f9ed..1412093 100644 --- a/skills/research/agents/openai.yaml +++ b/skills/research/agents/openai.yaml @@ -1,5 +1,6 @@ interface: display_name: 'Research' - short_description: 'Research primary sources into cited reports' + short_description: 'Research a subject into a trusted cited report' + default_prompt: 'Use $research to investigate this subject in a fresh agent and write a trusted cited report.' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/research/assets/research-report-template.md b/skills/research/assets/research-report-template.md index 8e382bd..fefe963 100644 --- a/skills/research/assets/research-report-template.md +++ b/skills/research/assets/research-report-template.md @@ -1,45 +1,23 @@ ---- -title: '{research title}' -createdAt: YYYY-MM-DD -updatedAt: YYYY-MM-DD -status: current -# Retain each applicable relationship and remove this guidance. -# supersedes: './YYYYMMDD-research-title.md' -# supersededBy: './YYYYMMDD-research-title.md' ---- - # {Research title} -## Research question and scope - -**Question:** {The question this report answers} - -**Intended use:** {The decision or caller this evidence informs} - -**Scope:** {Included and excluded concerns, applicable versions or environments, and evidence currency} +## Scope -## Conclusion - -{The concise answer, qualified to match the strength of the evidence} +{Describe what the research was for and the subject or information need it covered.} ## Findings -### {Finding} +### {Descriptive theme} -{Material claims with direct links to supporting primary sources. Identify inferences explicitly.} +{Present the evidence in approachable prose. Cite each material claim with its numbered source, for example [1], and identify material inference explicitly.} ## Conflicts -{Conflicting evidence and its effect on the conclusion, or "None found."} +{Give each material conflict its own paragraph, with citations. Write "None identified." when applicable.} ## Limitations -{Unresolved uncertainty, evidence gaps, and freshness risks, or "None known."} - -## Method - -{The research date, material search locations, terms or approaches, appraisal basis, triangulation and falsification method, and auditability constraints without the raw search trail.} +{Give each material evidence gap, access constraint, unresolved uncertainty, or relevant research limitation its own paragraph. Write "None identified." when applicable.} -## Primary sources +## Sources -- [{Source title}]({URL or repository-relative path}) — {publisher or owner, version or publication date, accessed YYYY-MM-DD, and relevance} +1. [Source title](https://example.com/source) — {author, publisher, or owning organisation} diff --git a/skills/research/references/REPORT-LIFECYCLE.md b/skills/research/references/REPORT-LIFECYCLE.md deleted file mode 100644 index c01349d..0000000 --- a/skills/research/references/REPORT-LIFECYCLE.md +++ /dev/null @@ -1,15 +0,0 @@ -# Research Report Lifecycle - -Use this reference only when `docs/research/` already contains research related to the current question. - -## Correct the current report - -Update a report in place only to repair wording, formatting, or a link to the same evidence without changing a material claim. Retain `createdAt` and change `updatedAt`. The corrected report remains the current snapshot. - -## Create a substantive refresh - -New evidence, changed scope, or a materially changed finding creates a new dated snapshot with a relative `supersedes` link. Mark the previous snapshot `superseded`, add its relative `supersededBy` link, and preserve its historical findings. The report history distinguishes correction from substantive refresh. - -## Resolve a dated-path collision - -When a distinct report already occupies the dated path, append `-2` to the filename slug and increment it until an unused path is available. Keep the frontmatter title and H1 unchanged. diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index 910f9bb..f7723d6 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -1,33 +1,41 @@ --- name: review-architecture -description: Reviews a codebase or scope for high-value modular redesigns, persists a Markdown review, and opens a disposable visual HTML shortlist. Use when modular architecture needs assessment. +description: Reviews a whole codebase for high-impact evidence-backed modular-design improvements and writes an interactive HTML report. Use for architecture or structural maintainability reviews. metadata: - invocation: user + type: performer disable-model-invocation: true --- # Review Architecture -The **visual information-seeking mantra** turns an evidence-backed modular review into an impact-grouped overview for people and a durable implementation reference for agents. +Finds the most consequential current opportunities to improve a codebase's modular structure and explains them in one interactive HTML report. ## Process -### 1. Establish the review +### 1. Establish whole-codebase evidence -Use the user's explicit scope or the whole repository with the slug `full-codebase`. Inspect applicable project context, architecture decisions, source, tests, contracts, schemas, dependencies, runtime configuration, and documentation. Exclude generated output, vendored dependencies, caches, and binaries unless they participate in a material boundary. Invoke `$modular-design` as the architecture authority. The scope, exclusions, project constraints, and modular baseline are explicit. +Inspect the request, repository guidance, root `PRODUCT.md` and `GLOSSARY.md`, applicable ADRs, current revision, and starting worktree state. Treat the whole repository as the review scope while honouring explicit exclusions. Map its capabilities and inspect the source, tests, contracts, schemas, configuration, and operational evidence needed to understand current structure. Exclude dependencies, generated output, vendored code, and obsolete paths from recommendation coverage. -### 2. Select the redesigns +Inspect relevant Git history after mapping the repository. Use repeated cross-file changes and hotspots as supporting evidence and ranking signals without excluding quieter areas. Distinguish project authority, current observation, inference, and unknowns. -Read [Architecture Analysis](references/architecture-analysis.md). Recover confirmed and inferred quality drivers, map the current capabilities and contracts, and trace material architecture pressure to precise repository locations. Apply **design it twice** to every serious candidate and load `$modular-design` techniques only when their conditions fit. Invoke `$research` only when a recommendation materially depends on an external claim requiring durable verification. Retain every redesign that clears the evidence threshold, assign stable two-digit IDs in ranked order, and group the set by explained `high`, `medium`, or `low` impact. Zero recommendations is valid. +Apply `$modular-design` to the authorities and current evidence. Invoke `$research` only when a material candidate depends on external framework, platform, or technical evidence that the repository cannot establish; read its report before deciding whether the candidate qualifies. -### 3. Persist the review +### 2. Retain only top-level candidates -Write the canonical report to `docs/architecture/YYYYMMDD-{scope}-architecture-review.md`; preserve an existing path with `-2`, `-3`, and so on unless replacement is explicit. For each recommendation, make the issue, fix, benefit, affected architecture, current and target design, evidence, rejected alternative, costs, risks, dependencies, migration route, smallest useful slice, containment, and fitness checks independently understandable. Record coverage without a qualifying redesign and material limitations. Stop before implementation or a file-by-file plan. +Require each candidate to have precise current repository evidence, a credible structural cause, a material present benefit, and visible trade-offs or uncertainty. State only the recommended structural direction, why it matters, and what it improves. Claim only improvements caused by that structural direction; do not imply that it establishes correctness, safety, or another quality it cannot demonstrate. Reject cosmetic cleanup, unsupported smell labels, speculative abstractions, and changes whose benefit is minor or hypothetical. -### 4. Present the visual shortlist +Keep only the highest-impact qualifying candidates. Use no fixed count. Order them by explicit qualitative judgement of present consequence, evidence, likely benefit, and feasibility; preserve that fixed order and identify the top recommendation. Zero candidates is a valid result. Record reviewed coverage and meaningful non-qualifying areas so absence of recommendations remains trustworthy. -Read [Report Design](references/report-design.md), then create a disposable `architecture-review-{timestamp}.html` in the operating system's temporary directory and open it for the user. Give it the same recommendation IDs, ordering, conclusions, and technical substance as the Markdown report. Show the complete set as `High impact`, `Medium impact`, and `Low impact`; make each collapsed card understandable through an aligned before-and-after visual and plain-language `Issue`, `Fix`, and `Benefit`, with technical depth available on demand. Add filters only when they materially improve navigation. +### 3. Write the interactive report -### 5. Verify and hand off +Write only `docs/architecture/YYYYMMDD-full-codebase-architecture-review.html`, using `-2`, `-3`, and later numeric suffixes when a same-day path exists unless replacement was explicit. Copy and complete [the report template](assets/report-template.html). Escape repository-derived text before placing it in HTML and remove every template marker. -Verify the Markdown paths, links, structure, and implementation sufficiency, then compare both artifacts for matching IDs and claims. Inspect the HTML at desktop and narrow widths, exercising disclosure, applicable filters, pointer and keyboard operation, focus, overflow, external dependencies, and print output. Correct material defects; when browser inspection is unavailable, mark visual acceptance incomplete. Return both report paths, scope and exclusions, recommendation IDs and count, invoked research, validation performed, and unresolved limitations. Preserve the reviewed implementation unchanged. +Keep each candidate's recommendation, reason, and improvement always visible. Put exact file and history evidence, trade-offs, and uncertainty in one native expandable section. Do not add filters, reordering, scores, detailed target interfaces, file-by-file changes, migration steps, test prescriptions, tickets, or an implementation plan. + +Add a current-versus-recommended visual only when it makes the structural relationship materially easier to understand. Design it specifically for that candidate with accessible HTML or inline SVG; add another CDN library only when it clearly improves the explanation. Omit a weak, generic, or decorative visual. + +### 4. Verify and stop + +Run the bundled `scripts/validate-report.js` with Bun and the report path. Re-read the report against the fixed order and current evidence; verify every cited repository path and material claim, the top recommendation, coverage, limitations, HTML escaping, and absence of leftover markers. Recheck the revision for material drift and confirm that only the report changed apart from pre-existing work. Do not open the report or perform rendered visual review. + +Return the report path, ordered candidate titles or the zero-candidate result, reviewed revision, invoked research, verification, and limitations. Stop without changing implementation or project authorities, elaborating a detailed design, creating specifications or tickets, committing, or publishing. diff --git a/skills/review-architecture/agents/openai.yaml b/skills/review-architecture/agents/openai.yaml index 9ea18e8..21441f7 100644 --- a/skills/review-architecture/agents/openai.yaml +++ b/skills/review-architecture/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Review Architecture' - short_description: 'Review architecture and explain redesigns' + short_description: 'Find the biggest structural improvements' policy: allow_implicit_invocation: false diff --git a/skills/review-architecture/assets/report-template.html b/skills/review-architecture/assets/report-template.html new file mode 100644 index 0000000..0274bc8 --- /dev/null +++ b/skills/review-architecture/assets/report-template.html @@ -0,0 +1,213 @@ + + + + + + %%PROJECT_NAME%% architecture review + + + + + +
+
+

+ Architecture review · %%REVIEW_DATE%% +

+

+ %%PROJECT_NAME%% +

+

+ %%OUTCOME_SUMMARY%% +

+
+
+
Reviewed revision
+
+ %%REVISION%% +
+
+
+
Recommendations
+
%%CANDIDATE_COUNT%%
+
+
+
Scope
+
+ Whole codebase%%SCOPE_EXCLUSIONS%% +
+
+
+
+ + + +
+
+
+

+ Prioritised shortlist +

+

+ Highest-impact opportunities +

+
+ +
+ +
+ +
+

+ Recommendation 01 · top recommendation +

+

+ %%CANDIDATE_TITLE%% +

+
+
+
+ Recommendation +
+
+ %%RECOMMENDATION%% +
+
+
+
+ Why it matters +
+
+ %%WHY_IT_MATTERS%% +
+
+
+
+ What it improves +
+
+ %%WHAT_IT_IMPROVES%% +
+
+
+ + + +
+ + Evidence and trade-offs + + +
+
+

+ Evidence +

+
%%EVIDENCE%%
+
+
+

+ Trade-offs and uncertainty +

+
%%TRADEOFFS%%
+
+
+
+
+ %%ADDITIONAL_CANDIDATES_OR_ZERO_RESULT%% +
+
+ +
+

+ Review record +

+

+ Coverage and limitations +

+
+
+

Reviewed

+
%%REVIEWED_COVERAGE%%
+
+
+

+ Limitations +

+
%%LIMITATIONS%%
+
+
+
+
+ + diff --git a/skills/review-architecture/references/architecture-analysis.md b/skills/review-architecture/references/architecture-analysis.md deleted file mode 100644 index fb21338..0000000 --- a/skills/review-architecture/references/architecture-analysis.md +++ /dev/null @@ -1,46 +0,0 @@ -# Architecture Analysis - -Load this reference while selecting and ranking redesigns. `$modular-design` owns architecture vocabulary, information hiding, deep modules, realization, and conditional techniques; this reference owns review-specific evidence and judgment. - -## Quality Priority - -Apply the first evidenced priority in this order: - -1. Safety, correctness, security, and data integrity constraints. -2. Explicit project quality drivers. -3. Qualities defined by `$modular-design`. -4. Testability and migration safety. -5. Operability, reliability, performance, scalability, and portability when material to the system. - -Recover drivers from product and domain context, architecture decisions, public promises, tests, operational configuration, incidents, recurring changes, and repository history when available. Express a material driver as a scenario with a stimulus, affected capability, expected response, and observable measure. Label inference and confidence; ask the user only when an unavailable priority would materially change qualification or rank. - -## Evidence and Comparison - -Map capabilities rather than assuming directories, classes, packages, services, or deployment units are architecture modules. For each material pressure, trace the owned knowledge, public contract, consumers, dependencies, runtime boundaries, verification seams, and repeated change propagation to repository-relative paths and precise locations. Separate observations, supported conclusions, and uncertainty. Metrics may locate candidates but cannot prove a redesign. - -For every serious candidate compare at least two materially different capability boundaries. State each contract, hidden knowledge, dependency direction, quality effects, framework and runtime fit, migration seam, first useful slice, containment, costs, and risks. A naming, file-placement, or interface-syntax variation is not a second design. Prefer the alternative that hides more consequential knowledge behind the simpler stable contract while satisfying the higher-priority evidence. - -## Qualification and Rank - -A recommendation qualifies only when it: - -- materially improves a priority quality; -- traces its problem and expected improvement to repository evidence; -- hides or realigns architectural knowledge rather than rearranging code locally; -- has a credible incremental route with visible dependencies and risks; and -- is supported strongly enough to recommend with material uncertainty exposed. - -Retain every qualifying redesign and none below the threshold. Record non-qualifying areas only as review coverage. Assign labels with a one-sentence evidence rationale: - -- **Impact:** `high` changes a constraint or explicit driver, or removes repeated high-reach pressure; `medium` materially improves a bounded capability; `low` produces a worthwhile but contained architectural gain. -- **Effort:** `high` crosses several boundaries or requires staged data, contract, or deployment work; `medium` needs coordinated changes; `low` is contained behind an existing seam. -- **Risk:** `high` threatens behaviour, data, security, public contracts, or runtime continuity; `medium` needs managed integration; `low` is isolated and readily reversible. -- **Confidence:** `high` follows direct repeated evidence and executable verification; `medium` combines credible evidence with limited inference; `low` depends materially on missing context. - -Do not calculate a composite score. Order impact groups `high`, `medium`, then `low`; rank within a group by quality priority, evidence reach, confidence, and migration feasibility. Assign `01`, `02`, and onward after ranking, and preserve those IDs across both reports regardless of filtering. - -## Migration and Fitness - -Define stages that keep the system operable and verifiable: prerequisites, smallest independently useful slice, old/new coexistence, data or contract transition, containment or rollback, and superseded-path removal. Replace a high-risk boundary incrementally; replace a safe local boundary atomically. Stop before a file-by-file implementation plan. - -Pair each claimed benefit with observable fitness evidence. State the signal, expected result, and where it should run, using existing contract tests, dependency checks, change-impact checks, adapter conformance, runtime thresholds, telemetry, or deployment signals when they prove the quality. Propose new machinery only when existing verification cannot. diff --git a/skills/review-architecture/references/report-design.md b/skills/review-architecture/references/report-design.md deleted file mode 100644 index dc07cd7..0000000 --- a/skills/review-architecture/references/report-design.md +++ /dev/null @@ -1,52 +0,0 @@ -# Architecture Review Report Design - -Load this reference after the recommendation set is complete. The Markdown report is the durable implementation record; the disposable HTML is its visual decision view. They adapt presentation to their readers without changing recommendation IDs, order, claims, or technical substance. - -## Markdown Record - -Use this reading order: - -1. Title, date, scope, exclusions, one-sentence outcome, and recommendation index. -2. `High impact`, `Medium impact`, and `Low impact` recommendation groups, omitting empty groups. -3. Review coverage and evidence limitations. -4. Method, invoked research reports, and validation status. - -Name each recommendation `{ID}. {action-led title}`. Lead with three plain-language fields: - -- **Issue:** the present architecture friction and consequence. -- **Fix:** the ownership, contract, or dependency change. -- **Benefit:** the concrete quality improvement. - -Then preserve the affected modules and contracts, current and target design, repository evidence with precise locations, before-and-after explanation, rejected alternative, framework and runtime fit, costs, risks, uncertainty, dependencies, migration and coexistence stages, containment or rollback, smallest useful slice, and fitness checks. A downstream agent must be able to receive the Markdown path plus an ID and understand the bounded change without reopening the review. - -## HTML Shortlist - -Apply overview first and details on demand. The initial viewport identifies the review and exposes the impact-grouped recommendation set without introductory prose. Each card shows its ID, title, impact, before-and-after visual, `Issue`, `Fix`, and `Benefit`. Put evidence, alternatives, effort, risk, confidence, migration, and fitness checks in native disclosure. Show a direct zero-result state when no redesign qualifies. - -Use filters only when the set is large enough that impact groups alone do not support comparison. Filtering changes visibility, never IDs, ranking, or report content; show the visible count and a clear reset. - -## Visual Language - -Apply **visual juxtaposition**: give every recommendation an aligned current/target pair that answers one question about changed ownership, hidden knowledge, dependency direction, runtime flow, or migration. Keep corresponding concepts in corresponding positions with consistent names, shapes, direction, and scale. At narrow widths, stack the pair while preserving that visual grammar. Simplify the visual rather than shrinking an unreadable whole-system map. - -Choose the smallest useful form: a boundary or dependency graph, quality-scenario flow, ownership sketch, cross-section, or staged migration. Mermaid, inline SVG, and semantic HTML/CSS are all valid. Mix techniques when the evidence benefits; avoid ornamental diagrams. Give every visual an accessible name and adjacent textual explanation. - -Use strong hierarchy, generous spacing, readable line lengths, restrained colour, and consistent cards. Paths and contracts may use monospace. Colour reinforces words and shapes rather than carrying meaning. Prefer semantic controls, visible focus, and native disclosure; interactions remain keyboard-operable. Provide responsive and print styles that preserve all content and expand technical details for printing. - -Scripts, styles, fonts, and diagram libraries may load from verified CDNs when useful. Keep the generated artifact in one HTML file apart from those dependencies, escape repository-derived text for its destination context, and verify every selected dependency at generation time. - -## Plain Language - -Use **plain language** for `Issue`, `Fix`, and `Benefit`: state the point first, use active verbs and familiar concrete words, and keep one idea in each field. Preserve established domain, project, framework, and architecture terms when they are more precise. Move substantiation into disclosure instead of weakening or repeating the summary. A collapsed card succeeds when it is concise and distinguishable from every other recommendation. - -## Visual QA - -Inspect the actual temporary file with network access: - -1. Confirm external dependencies and every before-and-after visual render. -2. Compare recommendation IDs, order, labels, and claims with the Markdown record. -3. Exercise disclosure and applicable filters by pointer and keyboard; verify focus, state, count, and reset. -4. Inspect desktop, narrow, zero-result, and print states for hierarchy, wrapping, overflow, clipping, and content loss. -5. Confirm the report remains understandable without colour and that evidence paths remain legible. - -Correct material defects and rerun affected checks. When browser inspection is unavailable, complete structural and source checks, then mark visual acceptance incomplete in both artifacts and the handoff. diff --git a/skills/review-architecture/scripts/validate-report.js b/skills/review-architecture/scripts/validate-report.js new file mode 100644 index 0000000..10a0a01 --- /dev/null +++ b/skills/review-architecture/scripts/validate-report.js @@ -0,0 +1,99 @@ +#!/usr/bin/env bun + +import fs from 'node:fs'; +import path from 'node:path'; + +const reportPath = process.argv[2]; +const errors = []; + +if (!reportPath) { + console.error('Usage: bun scripts/validate-report.js '); + process.exit(2); +} + +const absolutePath = path.resolve(reportPath); +if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { + errors.push(`Report not found: ${absolutePath}`); +} + +let html = ''; +if (!errors.length) html = fs.readFileSync(absolutePath, 'utf8'); + +const normalized = absolutePath.split(path.sep).join('/'); +if ( + !normalized.includes('/docs/architecture/') || + path.extname(absolutePath) !== '.html' +) { + errors.push('Report must be an HTML file under docs/architecture/.'); +} +if ( + !/^\d{8}-full-codebase-architecture-review(?:-\d+)?\.html$/.test( + path.basename(absolutePath), + ) +) { + errors.push( + 'Report filename must follow the dated full-codebase convention.', + ); +} + +const required = [ + ['HTML document', //i], + ['language', /]*\blang=/i], + ['UTF-8 metadata', /]*charset=["']?utf-8/i], + ['responsive viewport', /]*name=["']viewport["']/i], + [ + 'Tailwind browser CDN', + /cdn\.jsdelivr\.net\/npm\/@tailwindcss\/browser@4/, + ], + [ + 'deferred Alpine CDN', + /]*\bdefer\b[^>]*alpinejs@3\.x\.x\/dist\/cdn\.min\.js/i, + ], + ['review root', /\bdata-architecture-review\b/], + ['reviewed revision', /\bdata-reviewed-revision\b/], + ['coverage', /\bdata-coverage\b/], +]; + +for (const [label, pattern] of required) { + if (!pattern.test(html)) errors.push(`Missing ${label}.`); +} + +if (/%%[A-Z0-9_-]+%%/.test(html)) + errors.push('Unresolved template marker remains.'); + +const candidates = [ + ...html.matchAll(/]*\bdata-recommendation=["'](\d+)["']/gi), +]; +const numbers = candidates.map((match) => Number(match[1])); +if (numbers.some((number, index) => number !== index + 1)) { + errors.push( + 'Recommendation numbers must be contiguous and in fixed document order.', + ); +} + +if (candidates.length) { + if (!/\bdata-top-recommendation\b/.test(html)) + errors.push('Missing top recommendation.'); + for (const marker of [ + 'data-recommendation-summary', + 'data-field="recommendation"', + 'data-field="why"', + 'data-field="improves"', + 'data-evidence', + 'data-tradeoffs', + ]) { + if (!html.includes(marker)) + errors.push(`Missing candidate field: ${marker}.`); + } +} else if (!/\bdata-zero-result\b/.test(html)) { + errors.push('A zero-candidate report must contain data-zero-result.'); +} + +if (errors.length) { + for (const error of errors) console.error(`- ${error}`); + process.exit(1); +} + +console.log( + `Report valid: ${absolutePath} (${candidates.length} recommendations)`, +); diff --git a/skills/review-pull-request/SKILL.md b/skills/review-pull-request/SKILL.md new file mode 100644 index 0000000..7f563e8 --- /dev/null +++ b/skills/review-pull-request/SKILL.md @@ -0,0 +1,17 @@ +--- +name: review-pull-request +description: Reviews a supplied pull request through independent specification and engineering-standards assessment. Use when a pull request needs a read-only independent report. +metadata: + type: router +disable-model-invocation: true +--- + +# Review Pull Request + +Routes one fixed pull request through `$code-review` and returns its independent findings unchanged. + +## Process + +Resolve the supplied pull-request identifier against the current repository unless another repository is named. Use native host metadata to fix its repository, number or URL, and exact base and head revisions. Return the exact blocker when the pull request is ambiguous or inaccessible. + +Invoke `$code-review` with that fixed pull-request candidate and a read-only boundary. Return its result unchanged. diff --git a/skills/review-pull-request/agents/openai.yaml b/skills/review-pull-request/agents/openai.yaml new file mode 100644 index 0000000..f2d504f --- /dev/null +++ b/skills/review-pull-request/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Review Pull Request' + short_description: 'Return a read-only pull-request review' +policy: + allow_implicit_invocation: false diff --git a/skills/specify-feature/SKILL.md b/skills/specify-feature/SKILL.md new file mode 100644 index 0000000..fed97ba --- /dev/null +++ b/skills/specify-feature/SKILL.md @@ -0,0 +1,43 @@ +--- +name: specify-feature +description: Creates a decision-complete specification for one feature. Use when a high-level feature request or capability needs collaborative definition before ticket creation. +metadata: + type: performer +disable-model-invocation: true +--- + +# Specify Feature + +Turns one high-level feature description into one user-confirmed specification containing both feature intent and the selected buildable solution. + +## Process + +### 1. Build shared understanding + +Inspect the request and the project evidence relevant to the feature. Resolve discoverable facts before asking the user, and distinguish evidence of the current system from intended future behaviour. + +Invoke `$elicit-with-context` with the relevant evidence and unresolved decision whenever material user-held information or a decision is needed. Use its confirmed synthesis as authority for the feature direction. + +Invoke `$research` when durable external evidence is needed to resolve the feature. Use its report as evidence, not as authority for a product or solution decision. + +### 2. Make the feature decision-complete + +Establish **feature intent** before selecting the **solution**, and visibly reopen the affected intent when solution work exposes a behavioural gap. Use the [Feature Specification Template](assets/specification-template.md) as a coverage guide rather than a checklist: depth follows ambiguity, risk, external obligation and what ticket decomposition needs. + +Use goal-oriented use cases to connect actors to complete outcomes. Add triggers, preconditions, alternatives, failures and recovery where they reveal material behaviour. Use concrete context-event-outcome scenarios only where they make a rule, boundary or acceptance outcome testable through the application's interface or another stable observable boundary. Do not add user stories when they contribute no further meaning. + +Keep feature intent independent of internal implementation. Put consequential system-specific choices in the selected solution: enough responsibility, boundary, contract, data, integration, failure, quality, migration, operational and verification detail to constrain implementation, but not files, classes, framework wiring, exhaustive tests or ticket breakdown. Invoke `$modular-design` when a material structural choice needs resolving. + +Resolve every decision that could change scope, observable behaviour, acceptance or the material solution. An uncertainty may remain only when ticket decomposition is still safe; record its evidence, consequence, affected decisions and the condition or later user-agent step that will resolve it. Do not invent team roles, owners, approval bodies or third-party coordination. + +### 3. Write the specification + +Once shared understanding covers the complete feature, create `docs/features//specification.md` from the template. Record only decisions established with the user and evidence-supported facts, keeping feature intent and selected solution visibly distinct. Preserve the stable section spine, omit immaterial conditional content and link supporting product, context, decision, research, design and current-system evidence rather than duplicating it. + +Use stable semantic identifiers only where they make later reference and traceability clearer. Add a concise Mermaid diagram when a state model, interaction, boundary or runtime relationship is materially easier to understand visually. + +### 4. Verify and stop + +Re-read the finished document against the established decisions and cited evidence. Check that it describes one coherent feature; states each rule and decision once; covers the material use cases, adverse paths, qualities and acceptance boundaries; keeps acceptance observable; distinguishes intent from solution; traces consequential solution elements to their reason; and represents uncertainty honestly. + +The specification is ready when `$create-tickets` can decompose it without inventing product behaviour or selecting a material solution. Report the path, evidence used, verification performed and any non-blocking uncertainty. Do not create tickets or implement the feature. diff --git a/skills/specify-feature/agents/openai.yaml b/skills/specify-feature/agents/openai.yaml new file mode 100644 index 0000000..27fdbe8 --- /dev/null +++ b/skills/specify-feature/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Specify Feature' + short_description: 'Create one decision-complete feature specification' +policy: + allow_implicit_invocation: false diff --git a/skills/specify-feature/assets/specification-template.md b/skills/specify-feature/assets/specification-template.md new file mode 100644 index 0000000..a400d49 --- /dev/null +++ b/skills/specify-feature/assets/specification-template.md @@ -0,0 +1,128 @@ +# {Feature name} + +> **Authority:** This document owns the approved intent and selected solution for one feature. It is ready for ticket decomposition only when its readiness statement is satisfied. + + + +## Feature overview + +{Orient the reader with the feature, its source request or capability, current context, intended beneficiaries, and concise outcome.} + +## Problem, outcomes, and success measures + +{State the evidenced problem or opportunity, desired user or product outcomes, and only applicable measures with their source, baseline, direction or threshold, and horizon when known.} + +## Scope and non-goals + +### In scope + +- {Included feature outcome or observable responsibility.} + +### Non-goals + +- {Excluded adjacent behaviour and the boundary it preserves.} + +## Actors, goals, and use cases + +### {ACT-01 — Actor or beneficiary} + +{Goal and value sought from this feature.} + +### {UC-01 — Use-case name} + +- **Actor:** {Primary actor.} +- **Trigger:** {Observable event that starts the use case.} +- **Preconditions:** {Material conditions, if any.} +- **Successful outcome:** {Externally observable completion.} +- **Alternatives and exceptions:** {Only material refusal, adverse, recovery, or edge paths.} + +## Feature intent + +### Requirements and rules + +- **REQ-01 — {Requirement name}:** {One necessary, unambiguous, verifiable normative statement.} + +### States and transitions + + + +### Experience and design requirements + + + +### Quality and external constraints + + + +### Scenarios and acceptance + +#### SC-01 — {Scenario name} + +- **Given:** {Observable starting context.} +- **When:** {Actor action or external event.} +- **Then:** {User-, assistive-technology-, contract-, or operating-interface outcome.} + +**Covers:** {REQ-01 and any distinct acceptance identifiers evidenced by this scenario.} + +#### Acceptance conditions + + + +- **ACC-01:** {Observable acceptance boundary stated once.} + +## Selected solution + +### Design drivers and current context + +{Link the requirements, constraints, accepted decisions, and inspected current-system forces that shape the solution. Distinguish current evidence from selected direction.} + +### Strategy and material decisions + +{State the selected coherent approach and only the alternatives or trade-offs needed to understand a consequential choice.} + +### Responsibilities and boundaries + +{Describe affected capabilities, owned knowledge, contracts, dependency direction, and enabling changes without a file or class inventory. Use a small Mermaid context or runtime diagram when it clarifies the design.} + +### Interfaces and data contracts + + + +### Data and lifecycle + + + +### Integrations and failure handling + + + +### Cross-cutting and operational design + + + +### Verification seams + +{Identify the public or stable contract boundaries and evidence capable of establishing the selected behaviour. Do not prescribe an exhaustive test inventory.} + +## Dependencies, assumptions, risks, and unresolved items + + + +- **DEP-01 — {Dependency}:** {Evidence, consequence, and affected identifiers.} +- **ASM-01 — {Assumption}:** {Evidence, consequence if wrong, and affected identifiers.} +- **RSK-01 — {Risk}:** {Evidence, consequence, mitigation or design response, and affected identifiers.} +- **UNR-01 — {Non-blocking uncertainty}:** {Evidence, consequence if wrong, affected decisions, and resolution condition or later user-agent step; explain why ticket decomposition remains safe.} + +## Traceability and readiness + +| Intent or acceptance identifier | Selected responsibility or contract | Verification seam or evidence | +| ------------------------------- | ------------------------------------ | ----------------------------------- | +| {REQ-01 or ACC-01} | {Design responsibility or contract.} | {Observable verification boundary.} | + +| Introduced design element | Originating intent, constraint, evidence, or accepted decision | +| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| {Material responsibility, contract, data, integration, migration, operational, or verification element.} | {Exact identifier or linked authority.} | + +### Readiness statement + +{State concisely why later ticket creation can proceed without inventing observable behaviour or selecting a material solution, plus any non-blocking limitation. Do not recap the specification.} diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 3a365b8..512e0d6 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -1,39 +1,53 @@ --- name: tdd -description: Implements observable features and bug fixes through red-green-refactor. Use when an existing runnable test suite can exercise the change at a stable public seam. +description: Teaches test-driven development through red-green-refactor with durable behavioural tests. Use when a usable suite can exercise changed behaviour through a credible seam. metadata: - invocation: model -disable-model-invocation: false + type: teaching +disable-model-invocation: true --- # Test-Driven Development -**Classicist TDD** builds one observable behaviour at a time through red-green-refactor, testing the narrowest stable public seam with real internal collaborators and doubling only uncontrollable boundaries. +Teaches a caller to implement one observable behaviour at a time and retain a small suite that detects promised-behaviour defects without resisting structural change. -## Prerequisite +## Prerequisites -TDD applies when an existing runnable test suite can exercise the requested behaviour through a stable public seam. Otherwise return control with the missing condition; the caller owns any decision to create a test harness or reshape a public contract. Apply TDD to observable behaviour, including configuration with observable effects; leave documentation, configuration-only maintenance, and behaviour-preserving refactors with the caller. +Apply TDD only when the work adds, changes, or repairs observable behaviour and an existing usable suite can exercise it through a credible seam. Otherwise surface the missing condition so the caller can use the strongest project-native feedback without claiming TDD. Create a suite or framework only when that infrastructure is part of the agreed work. ## Process -### 1. Establish the baseline +### 1. Fix the slice, seam, and oracle -Read repository instructions, identify the relevant test command, and run the existing suite. Use **tracer bullets** to select the smallest end-to-end behaviour that advances the request, then choose the narrowest stable public seam that can observe the slice without exposing hidden structure. Invoke `$modular-design` when the slice changes modular architecture. Identify a **test oracle**—a requirement, worked example, invariant, contract, trusted reference, accepted prior behaviour, or explicit domain decision—capable of distinguishing the expected outcome from the implementation. Consult [Test Quality](references/TEST-QUALITY.md) when the seam, oracle, or proposed assertion could couple to representation. The baseline, behaviour, seam, oracle, and applicable modular constraints are explicit. +Use the caller's confirmed behaviour, applicable modular constraints, and current production and test evidence. Inspect only evidence that is missing or stale. Identify the focused command and run its baseline. Keep pre-existing failures visible; continue only when they cannot hide the next Red or Green signal. + +Select a **tracer bullet**: the smallest complete vertical slice that produces one requested observable outcome. Apply `$test-design` to choose its seam, oracle, test shape, and any conditional technique. Current output is characterization, not proof of correctness. + +For an existing partial implementation, demonstrate sensitivity against the pre-change revision, a safely disabled behaviour, or a controlled known-bad variant. When none is safe, retain an independently meaningful test as regression or characterization evidence without calling the work TDD. ### 2. Red -Use **Arrange-Act-Assert** to add one focused test. Apply the **Test Desiderata**, especially behavioural sensitivity, structure insensitivity, specificity, determinism, readability, and production prediction. Keep internal collaborators real. When an uncontrollable boundary must be controlled or observed, choose the least powerful **Test Double** that supplies the required evidence; consult [Test Doubles](references/TEST-DOUBLES.md) before introducing a double or interaction assertion. +Write one focused behavioural test before its production change, following the selected test design. -For a bug, reproduce the incorrect behaviour; adopt an already-failing regression test only when it independently specifies the desired behaviour. Run the focused test and confirm that it fails for the expected behavioural reason. When it fails because of the test or environment, remain in Red: correct an in-scope defect or report the blocker, then rerun until the intended failure is observed. Meaningful red evidence exists before Green begins. +For a bug, reproduce the incorrect result and assert the independently established desired result. Structure the test so failure is reported against the promise: an unexpected exception that aborts before any oracle assertion is not Red unless the test explicitly establishes that successful completion is the promise. When count or order at a system boundary is promised, assert it directly rather than inferring it from final state. + +Run the focused test. Red exists only when an oracle fails for the intended missing or incorrect behaviour; a pass, syntax error, fixture failure, or environment error is invalid. Correct an in-scope test or environment defect and rerun, or surface the blocker in the caller's workflow. Preserve the exact Red command and failure. ### 3. Green -Implement only enough production code to satisfy the behaviour, then run the focused test and relevant nearby tests. The new behaviour passes without speculative production code or hidden baseline failures. +Add only enough production code for the current behaviour. Treat confirmed preconditions as inputs to this slice; do not invent validation, errors, fallbacks, or branches for their violation. Do not anticipate later cases, add hypothetical options, or refactor unrelated code. Run the focused test and relevant nearby tests. Fix production code while the independent oracle remains valid; never weaken the test merely to obtain Green. Preserve the exact Green command and result. + +### 4. Refactor while green + +Improve production naming, cohesion, duplication, ownership, and interfaces without adding behaviour. Keep behavioural tests unchanged through production refactors. When structural movement alone breaks a test, move its observation back to the promised outcome. Clarify test names or fixtures only without weakening the oracle or counterfactuals. Run the focused tests after each material step. + +If refactoring exposes a new material structural decision not resolved by the caller's modular constraints, pause the cycle until the caller resolves it. + +### 5. Rationalise the retained suite -### 4. Refactor +After production refactoring, reapply `$test-design` to the affected suite while it remains Green. -Improve the test and production code while keeping behaviour fixed. Preserve the test across changes to algorithms, collaborators, storage, rendering, or other hidden structure; when structure alone breaks it, move the observation back to the public outcome. Run the focused tests after each material change until the design is clear and green. The cycle ends without a refactor regression. +### 6. Complete the cycles -### 5. Complete the cycles +Repeat Red, Green, Refactor, and rationalisation for each remaining confirmed behaviour. Run the complete relevant suite. -Repeat Red, Green, and Refactor for each remaining behaviour, then run the complete relevant suite. Report the behaviours delivered, red and green evidence, refactors, commands, results, and unresolved baseline failures. The requested behaviour and retained tests are verified. +Keep the delivered behaviours, retained tests and their unique protection, exact Red and Green evidence, refactors, commands and results, unresolved baseline failures, fidelity limits, and other missing evidence current in the caller's workflow. diff --git a/skills/tdd/agents/openai.yaml b/skills/tdd/agents/openai.yaml index 1386203..d3df8d3 100644 --- a/skills/tdd/agents/openai.yaml +++ b/skills/tdd/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Test-Driven Development' - short_description: 'Build behaviour with red-green-refactor' + short_description: 'Build durable behaviour through red-green-refactor' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/tdd/references/TEST-DOUBLES.md b/skills/tdd/references/TEST-DOUBLES.md deleted file mode 100644 index ded54f2..0000000 --- a/skills/tdd/references/TEST-DOUBLES.md +++ /dev/null @@ -1,59 +0,0 @@ -# Test Doubles - -Use this guide before replacing a collaborator or asserting calls. Keep collaborators inside the system real; substitute a boundary when the real dependency is slow, unavailable, non-deterministic, externally mutating, or otherwise uncontrollable in the test. - -## Choose the least powerful double - -Start with the real collaborator, then introduce only the capability the test needs: - -| Double | Use it to | Verification | -| --- | --- | --- | -| Dummy | Fill an unused required parameter | None | -| Stub | Supply a controlled indirect input | Assert the public outcome | -| Fake | Run a working, simplified boundary implementation | Assert the public outcome or recorded public effect | -| Spy | Record an otherwise invisible boundary effect | Inspect only promised boundary facts | -| Mock | Specify a required external interaction protocol | Verify only contractually material calls | - -Prefer state verification: act through the public seam, then inspect its result or a recorded boundary effect. Use interaction verification when the interaction is itself observable behaviour, such as one idempotency-keyed payment request or committing only after a durable write. - -## Keep the contract visible - -Specify the external fact that matters and leave the internal route free to change. - -```typescript -// Couples the test to internal delegation. -expect(pricingService.lookup).toHaveBeenCalledTimes(1); -expect(discountCalculator.apply).toHaveBeenCalledBefore(taxCalculator.apply); - -// Observes the public result with real internal collaborators. -expect(await quoteOrder(order)).toEqual({ total: 108, currency: 'GBP' }); -``` - -At an uncontrollable boundary, record the promised effect without specifying internal calls: - -```typescript -const mailer = new RecordingMailer(); -await registerUser({ email: 'ada@example.com' }, { mailer }); - -expect(mailer.sent).toEqual([{ to: 'ada@example.com', template: 'welcome' }]); -``` - -Use an expectation mock when the external protocol is the outcome: - -```typescript -await submitPayment(order, paymentGateway); - -expect(paymentGateway.charge).toHaveBeenCalledOnceWith({ - amount: 108, - currency: 'GBP', - idempotencyKey: order.id, -}); -``` - -Here the amount, currency, single request, and idempotency key are provider-facing promises. Do not add expectations for logging, helper calls, object construction, or other internal routing. - -## Preserve boundary fidelity - -A double can make an impossible system look correct. Keep its behaviour smaller than the production boundary and derive responses from the provider contract rather than copied client logic. Where feasible, run focused contract tests against the real boundary to confirm that the fake, stub, or recorded request still matches it. Otherwise report the unverified fidelity as a limitation. - -Control time and randomness by injecting a clock or deterministic source at the system boundary. Prefer a real test database or filesystem in an isolated disposable environment when its semantics are material; use a fake only when its behavioural differences cannot invalidate the test's claim. diff --git a/skills/tdd/references/TEST-QUALITY.md b/skills/tdd/references/TEST-QUALITY.md deleted file mode 100644 index 1a53249..0000000 --- a/skills/tdd/references/TEST-QUALITY.md +++ /dev/null @@ -1,83 +0,0 @@ -# Test Quality - -Use this guide when choosing a seam or oracle, or when an assertion may couple the test to representation rather than promised behaviour. - -## Choose the test seam - -Test the narrowest boundary that satisfies all three conditions: - -- **Observable:** it exposes the requested return value, public state, error, emitted effect, persistence, navigation, or user-perceivable result. -- **Stable:** it hides algorithms, collaborator graphs, storage layouts, rendering wrappers, generated selectors, and other decisions that may change while behaviour remains fixed. -- **Predictive:** exercising it provides credible evidence that the behaviour will work in production. - -Use a coarser companion test only when the narrow seam cannot predict a material integration outcome. A substitutable private hook is not a suitable assertion boundary merely because it is convenient to replace. - -## Construct the oracle - -Derive the expected outcome before implementing Green. Prefer, in order: - -1. A requirement, accepted example, published protocol, or explicit domain decision. -2. A law, invariant, or contract independent of the production algorithm. -3. A trusted external reference or separately implemented model. -4. Prior accepted behaviour when preserving that behaviour is the requirement. - -Encode the oracle as an independently reasoned literal or predicate. A small calculation is suitable when it expresses a different trusted rule; reusing the production helper or repeating its algorithm can only reproduce the same defect. - -```typescript -// Repeats the implementation's likely algorithm. -const expected = items.reduce((sum, item) => sum + item.price, 0); -expect(calculateTotal(items)).toBe(expected); - -// Uses the accepted worked example as an independent oracle. -expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15); -``` - -When no credible oracle exists, return the missing behavioural decision instead of inventing the expected result. Treat output captured from the current implementation as characterization, not proof of correctness. - -## Structure one behaviour - -Use Arrange-Act-Assert: - -1. **Arrange** only the state and collaborators needed for the behaviour. -2. **Act** once through the selected public seam. -3. **Assert** the complete promised outcome and material unchanged state. - -One behaviour may require several cohesive assertions. Split a test when it contains multiple independent Acts or when its name cannot state one behavioural rule. Clean up resources or external state acquired by the test. - -## Apply the Test Desiderata - -Retain tests that are isolated, composable, deterministic, fast, writable, readable, behavioural, structure-insensitive, automated, specific, predictive, and inspiring. Treat the properties as trade-offs: a slower test can earn its cost through prediction, while a faster test still needs credible production evidence. - -Use two counterfactuals: - -- If promised behaviour changed, would the test result change? -- If only hidden structure changed, would the test and result remain unchanged? - -A useful test answers yes to both. Move a structure-sensitive observation outward to the supported result; move a behaviour-insensitive assertion toward the actual promise. - -## Observe promised outcomes - -| Concern | Durable observation | Replace structure coupling with | Representation is valid when | -| --- | --- | --- | --- | -| Domain result | Public operation against an independently justified example or invariant | A literal, contract, or independently reasoned predicate instead of the production algorithm | The representation is part of the domain contract | -| Public state | Supported command followed by a documented query or return value | Public state instead of private fields, methods, or patched internals | Diagnostic state is an intentional supported interface | -| Error | Caller-visible type, code, material message, and promised recovery or unchanged state | Stable error meaning instead of a private branch, stack shape, or helper call | Exact wording is a documented user or API contract | -| UI | Role, label, text, displayed value, accessible state, focus, or navigation | User-perceivable outcome instead of classes, wrapper tags, child indexes, or DOM depth | Visual appearance or semantic markup is the promised behaviour | -| Persistence | Write and read through supported interfaces, with reload or restart when durability matters | Public retrieval instead of private tables, columns, ORM calls, or storage layout | The schema is a published integration contract | -| External effect | Recorded boundary request or fake mailbox, queue, or provider outcome | Promised payload and result instead of internal delegation | Count, order, or arguments are part of the external protocol | -| Snapshot or serialization | Small reviewed public artifact or selected semantic fields | Focused compatibility facts instead of broad structural snapshots | Exact bytes, markup, or object shape are the published format | -| Configuration | Configured system exercised through its observable effect | Runtime result instead of parser calls or incidental internal objects | Generated configuration text is itself the public artifact | - -For UI behaviour, interact as a user would and assert what a user or assistive technology can perceive: - -```typescript -// Couples the test to generated styling and DOM structure. -expect(button.className).toBe('btn btn-primary px-4'); -expect(container.children[0]).toBe(button); - -// Observes the supported interaction and visible result. -await user.click(screen.getByRole('button', { name: 'Save' })); -expect(screen.getByText('Changes saved')).toBeVisible(); -``` - -For side effects, observe the system boundary rather than the internal route. Assert call count or order only when duplicate suppression, transaction ordering, or protocol sequencing is the behaviour. See [Test Doubles](TEST-DOUBLES.md) for boundary substitutes and interaction assertions. diff --git a/skills/test-design/SKILL.md b/skills/test-design/SKILL.md new file mode 100644 index 0000000..e4ad25c --- /dev/null +++ b/skills/test-design/SKILL.md @@ -0,0 +1,59 @@ +--- +name: test-design +description: Teaches durable behavioural test design through stable seams, independent oracles, determinism, and counterfactual challenge. Use when writing, reviewing, or rationalising tests. +metadata: + type: teaching +disable-model-invocation: true +--- + +# Test Design + +Teaches a caller to retain tests that detect promised-behaviour defects without resisting hidden structural change. + +## Process + +### 1. Fix the behavioural basis + +Use the caller's confirmed behaviour, applicable contracts, and current production and test evidence. Inspect only evidence that is missing or stale. Treat representation as a valid oracle only when that representation is itself a published contract. + +### 2. Select a durable seam + +Use the narrowest seam that is: + +- **Observable:** exposes a supported result, state, error, effect, persistence, navigation, or user-perceivable outcome. +- **Stable:** hides algorithms, collaborator graphs, storage layouts, rendering wrappers, generated selectors, and other replaceable decisions. +- **Predictive:** exercises the behaviour and technology whose production failure matters. + +Add a broader companion test only when the narrower seam cannot retain a material integration risk. Test a pure rule through its public function, a database guarantee against the real engine when its semantics matter, and an end-user interaction through the rendered application when wiring or accessibility is part of the promise. + +Prefer supported operations and observable outcomes over private methods, helper delegation, ORM calls, CSS classes, wrapper tags, DOM depth, stack shape, or broad incidental snapshots. For a defect, reproduce the wrong result and assert a requirement-derived correction rather than treating the existing failure as the expectation. + +When a slow, unavailable, destructive, non-deterministic, externally mutating, or otherwise uncontrollable boundary needs substitution or observation, load [Test Doubles](references/TEST-DOUBLES.md). Keep internal collaborators real and do not introduce a production abstraction solely to enable mocking. + +### 3. Build an independent oracle + +Prefer, in order: + +1. a confirmed requirement, accepted worked example, published protocol, or domain decision; +2. a law, invariant, or contract independent of the production algorithm; +3. a trusted external reference or separately implemented model; or +4. accepted prior behaviour when preservation is the requirement. + +Encode the expectation as an independently reasoned literal or predicate. Do not call the production helper, copy its algorithm, approve newly captured output, or assert only that execution completed unless completion is the entire promise. When no credible oracle exists, surface the missing behavioural decision in the caller's workflow. + +When examples cannot economically cover a large input or state space, or a direct expected output is unavailable but an independent relation, model, or comparator exists, load [Generative Testing](references/GENERATIVE-TESTING.md). Use only the technique whose trigger and oracle hold. + +### 4. Make the test deterministic and complete + +Arrange local explicit state, perform one meaningful action, assert the complete promised outcome, then release acquired resources. Add a negative or unchanged-state assertion only when the requirement makes it material and the action has a real causal path to the observed value. One behaviour may need several cohesive assertions; split multiple independent actions or rules. + +Control time and randomness through a deterministic source at the system boundary. Use fixed instants and seeds and preserve a minimised failing counterexample. Give each test isolated data and restore process state, files, transactions, services, timers, and environment values it changes. Avoid sleeps, execution-order dependencies, live external services, and shared mutable fixtures. + +### 5. Challenge and rationalise + +Apply both counterfactuals before retaining a test: + +- If promised behaviour broke, would this test fail? +- If only hidden structure changed, would this test remain unchanged and pass? + +Map every affected test to unique protection after refactoring. Keep a focused example when it specifies a distinct rule or gives a clearer failure. Otherwise remove duplicates or consolidate cases only when the resulting oracle and failure diagnosis remain clear. Fewer tests are better only when no unique defect detection is lost. diff --git a/skills/test-design/agents/openai.yaml b/skills/test-design/agents/openai.yaml new file mode 100644 index 0000000..bd620c2 --- /dev/null +++ b/skills/test-design/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Test Design' + short_description: 'Design durable behavioural tests' +policy: + allow_implicit_invocation: false diff --git a/skills/test-design/references/GENERATIVE-TESTING.md b/skills/test-design/references/GENERATIVE-TESTING.md new file mode 100644 index 0000000..63e43a4 --- /dev/null +++ b/skills/test-design/references/GENERATIVE-TESTING.md @@ -0,0 +1,32 @@ +# Generative Testing + +Use an example test by default. Select one of these techniques only when its trigger applies and its oracle is independently justified. + +| Technique | Trigger | Oracle and limitation | +| ------------------ | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Property-based** | Stable invariants over many values; parsers, serializers, algebra, collections, boundary-rich pure logic | Assert an independent invariant. Biased generators and tautological properties can pass indefinitely. | +| **Model-based** | Stateful workflows or protocols where sequences and invalid transitions matter | Compare with a smaller independent state model. A model copied from production repeats its defects and can suffer state explosion. | +| **Metamorphic** | Direct expected outputs are unavailable but relationships between executions are known | Assert relations such as round-trip, permutation invariance, monotonicity, or scaling. A relation detects inconsistency, not necessarily the uniquely correct result. | +| **Differential** | Two genuinely comparable implementations, versions, backends, or conforming tools can receive the same inputs | Compare normalized outcomes. Agreement may be jointly wrong; shared code or assumptions weaken independence. | + +## Apply the selected technique + +1. State the rule and its authority before writing the generator or model. +2. Constrain generated data to valid and deliberately invalid domains that exercise the promised behaviour. +3. Reject vacuous properties, unreachable model states, shared oracle logic, and normalization that erases material differences. +4. Run with a recorded seed. Minimize a failure and retain the smallest counterexample as a focused regression test. +5. Report the sampled scope and the oracle's limitation; a passing generated run is not proof over the full space. + +```typescript +// Tautological: repeats the implementation's sorting comparison. +property(array(integer()), (values) => + expect(sort(values)).toEqual(values.toSorted(productionComparator)), +); + +// Independent metamorphic relation: permutation cannot change the multiset. +property(array(integer()), (values) => + expect(frequencies(sort(values))).toEqual(frequencies(values)), +); +``` + +For stateful behaviour, keep the model smaller than production and express only authoritative states and transitions. For differential testing, first identify allowed variation and normalize only that variation. Preserve every meaningful discrepancy until it is explained as a candidate defect, an oracle defect, or permitted divergence. diff --git a/skills/test-design/references/TEST-DOUBLES.md b/skills/test-design/references/TEST-DOUBLES.md new file mode 100644 index 0000000..a18429a --- /dev/null +++ b/skills/test-design/references/TEST-DOUBLES.md @@ -0,0 +1,63 @@ +# Test Doubles + +Keep collaborators inside the system real. Substitute a boundary only when the real dependency is slow, unavailable, destructive, non-deterministic, externally mutating, or otherwise uncontrollable in this test. + +## Choose the least powerful double + +| Double | Supply | Verify | +| ------ | -------------------------------------------------- | -------------------------------------------- | +| Dummy | An unused required value | Nothing | +| Stub | A controlled indirect input | The public outcome | +| Fake | A small working boundary implementation | The public outcome or recorded public effect | +| Spy | A record of an otherwise invisible boundary effect | Only promised boundary facts | +| Mock | An expected external interaction protocol | Only contractually material calls | + +Prefer state verification. Interaction verification is warranted when the interaction is the promise: for example, one idempotency-keyed payment request or publishing only after a durable write. + +```typescript +// Brittle: replaces internal policy and specifies its call graph. +expect(pricing.lookup).toHaveBeenCalledTimes(1); +expect(discounts.apply).toHaveBeenCalledBefore(tax.apply); + +// Durable: real internal collaborators produce the supported result. +expect(await quoteOrder(order)).toEqual({ total: 108, currency: 'GBP' }); +``` + +At an uncontrollable external boundary, record only the promised effect: + +```typescript +const mailer = new RecordingMailer(); +await registerUser({ email: 'ada@example.com' }, { mailer }); + +expect(mailer.sent).toEqual([{ to: 'ada@example.com', template: 'welcome' }]); +``` + +Use a mock when interaction is the provider-facing contract: + +```typescript +expect(paymentGateway.charge).toHaveBeenCalledOnceWith({ + amount: 108, + currency: 'GBP', + idempotencyKey: order.id, +}); +``` + +When sequencing across system boundaries is promised, record those boundary events and assert their public order: + +```typescript +const events: string[] = []; +const payments = new RecordingGateway({ events, result: { paymentId: 'p-1' } }); +const orders = new RecordingOrders({ events, initial: pendingOrder }); + +await checkout(pendingOrder.id, { payments, orders }); + +expect(events).toEqual(['charge-succeeded', 'order-saved']); +``` + +This protects a payment-before-persistence promise. Ordering between pricing helpers, mappers, or other internal collaborators remains hidden structure. + +Do not assert logging, helper calls, object construction, or internal order unless those facts are externally promised. + +## Preserve boundary fidelity + +Derive double responses from the external contract, not copied client logic. Keep the double smaller than the real boundary. Prefer a real database or filesystem in an isolated disposable environment when its semantics matter. When feasible, use caller-selected contract evidence against the real boundary to check that a fake, stub, or recorded request remains compatible; otherwise report the untested fidelity. diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index f6f1c34..b5d9f09 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,53 +1,119 @@ --- name: write-skill -description: Creates and updates predictable agent skills through confirmed behavioural contracts, evidence-backed concepts, and forward testing. Use when authoring or revising a skill. +description: Creates and revises effective agent skills through confirmed requirements, minimum-sufficient design, and baseline-controlled evaluation. Use when authoring or maintaining a reusable agent skill. metadata: - invocation: user + type: performer disable-model-invocation: true --- # Write Skill -**Minimalist instruction** turns confirmed behaviours into the smallest skill bundle that reliably teaches them. +Creates minimum-sufficient agent skills whose observed behaviour justifies their context and execution cost. ## Process -### 1. Establish the behavioural contract +### 1. Confirm the contract -Inspect the request, complete target bundle, discoverable callers, and host conventions. Invoke `$elicit` and use the **main success scenario** to confirm the skill's purpose, trigger, primary behaviour, required inputs, observable result, and resource needs. Apply **YAGNI** to speculative branches: retain an exception only when representative evidence, the primary behaviour, or a necessary safety or permission boundary requires it. Existing and new skills reach one explicit behavioural contract with a dominant thread and only its material exceptions. +Inspect the request, an existing skill and its direct composition when revising, and task-scoped evidence without changing the target. Invoke `$elicit-with-context` in a software project and `$elicit` elsewhere to confirm the recurring job or capability gap; task triggers and non-triggers; skill type; inputs and prerequisites; required actions, material branches, authority, and stopping boundary; expected output or handoff; direct composition; necessary resources; and observable success evidence. Keep the target unchanged until elicitation returns the confirmed synthesis. The authoring contract is explicit and closed. -### 2. Compare governing methodologies +### 2. Establish the matched baseline -Use the confirmed behavioural contract as the fixed scope and decision authority for both research passes; evidence selects how to teach the confirmed behaviour. Invoke `$research` to compare credible governing methodologies, then **design it twice**: continue until at least two credible options emerge or the evidence reaches saturation. Present the supported options, behavioural consequences, and recommendation for the user to choose. Offer only evidence-supported alternatives; when one methodology survives, compare it with a methodology-free process. The user's selection or evidence-backed absence is explicit. +Freeze one representative common-path task, harness, tools, permissions, and task-scoped inputs from the confirmed success evidence. Before designing the candidate, run isolated fresh agents: -### 3. Select supporting concepts +- New skill: no skill. +- Revised skill: no skill and the current skill. -Invoke `$research` to find established principles, theories, methods, or techniques that reinforce distinct concerns without competing with the selected governor. Explain each candidate's intended behavioural effect and let the user decide; let the evidence determine the count. Every retained concept earns a distinct role. +Record each result, loaded path, output, tool calls, and iterations. Design only against observed failure or excess burden. Stop when no skill fulfils the confirmed behaviour and no current-skill defect, contract change, or burden remains. -### 4. Confirm the design +### 3. Bound one capability -Present one complete synthesis of the behavioural contract, selected concepts, structure, resources, main success scenario, material exceptions, and observable success conditions. Obtain explicit confirmation before following the remaining process. +Apply the **KISS principle**: retain the common path and material branches; remove speculative edge cases, unnecessary artefacts, and ceremony that cannot change the evaluated outcome. Keep coupled actions and artefacts together when they serve one outcome. Split independently useful capabilities when their trigger families, outcomes, authority, or success boundaries differ. The candidate has one coherent behavioural purpose. -### 5. Write the bundle +Classify the skill by the authority it owns, not by whether it calls tools or fresh agents: -Create or update through one path. Treat the confirmed design as closed: encode its main success scenario and retained material exceptions without adding new behaviour during drafting. Give every `SKILL.md` frontmatter, one H1, a concise introduction, and exactly one `## Process`; place a selected governing methodology in bold where it fits naturally in the introduction. Bold each supporting concept at its first behaviour-governing use. Consult [Skill Sections](references/SECTIONS.md) when invocation metadata, optional sections, or resource placement needs detail. The bundle expresses the confirmed design. +- A **performer** owns one bounded requested outcome end to end, including actions, artefacts, verification, handoff, and stopping. +- A **router** resolves inputs and coordinates other skills' public contracts, adding only routing unique to the combined outcome. +- A **teaching** skill supplies knowledge and decision rules inside a caller's workflow without owning an independent operation, mutation, artefact, verification, handoff, or stopping decision. +- A **utility** owns one bounded reusable operation and returns its result. -### 6. Separate the concerns +Set `metadata.type` to exactly `performer`, `router`, `teaching`, or `utility`. Remove responsibilities that belong to another type or split them when each capability is independently useful. -Apply **separation of concerns** so each step or subsection carries one coherent behavioural idea and observable outcome. Split independently actionable instructions, concepts, or completion criteria; keep sentences together when they jointly govern the same action. Consult [Skill Craft](references/CRAFT.md) when the split, vocabulary, emphasis, or disclosure boundary is unclear. Every section remains focused and substantial. +Choose invocation from actual use. Make regularly useful skills model-invoked. Make occasional, deliberate, or composition-only skills user-invoked. Set `disable-model-invocation` and `agents/openai.yaml` consistently. The skill enters context only through its intended route. -### 7. Compress the language +### 4. Design the loading path -Apply minimalist instruction and **DRY** until every remaining word changes behaviour, preserves a condition, or improves navigation. Replace explanations with canonical leading words when the agent already knows the concept and keep each meaning in one authoritative location. Use **ironic process theory** as a salience check: state the positive target behaviour and pair an essential prohibition with the safe action that satisfies it. Consult [Skill Craft](references/CRAFT.md) when negative framing or semantic duplication remains unclear. Every remaining instruction is behaviourally necessary, authoritative, and positively framed. +Use a 1-64 character lowercase name with single hyphen separators and match the directory name. Write the description as one line that starts with a third-person action verb, says what the skill does, includes `Use when`, `Use for`, or `Use to`, and front-loads natural task triggers derived from its content. Describe the skill in isolation as something the agent may select; base its trigger on the work, not whether the user, caller, or another skill invoked it or the current invocation policy. Add a human-readable display name and short description to `agents/openai.yaml`. -### 8. Validate the mechanics +Use **progressive disclosure**: -Run [scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled script, and execute each within a disposable filesystem using inert fixtures, isolated credentials, and an environment incapable of external mutation. When that boundary is unavailable, leave the script unexecuted and report the limitation. The mechanical contract passes within the safe execution boundary. +- Put concise discovery and invocation metadata in frontmatter and `agents/openai.yaml`. +- Put every-run decisions, actions, authority, branches, and stopping conditions in `SKILL.md`. +- Link conditional detail inline at the branch that needs it. +- Put reusable output material in `assets/`. +- Put deterministic transformations and checks in `scripts/`. -### 9. Forward-test the behaviour +Keep required coupled guidance together. Prefer direct one-level references. Remove unreachable and unlinked resources. Trace direct composition across trigger, inputs, authority, result, owner, and stopping boundary. A composed skill consumes current caller evidence and loads only missing or stale evidence; an independently invokable skill remains self-sufficient; a fresh agent receives a complete task-scoped packet. A router relies on each invoked skill's public contract and does not repeat its loading, process, or result handling. The smallest sufficient context is reachable when needed. -Give a fresh agent only the finished bundle and a realistic main-success invocation, then compare its observable process and result with the confirmed contract. Add the smallest scenario for each retained material exception. Consult [Forward Testing](references/TESTING.md) when scenario selection, isolation, or pass evidence needs detail. Repair, recompress, revalidate, and retest until the skill reliably invokes the intended behaviour. +### 5. Draft the isolated candidate -### 10. Report the result +Create the candidate outside the requested destination. For revisions, start from the current bundle and preserve behaviour outside the confirmed change. -Return the changed files, research evidence, mechanical results, forward-test scenarios and outcomes, unexecuted scripts, and remaining uncertainty. The user receives the finished bundle and evidence that its contract holds. +Use [the skill template](assets/skill-template.md). Load [the section guide](references/SECTIONS.md) only when optional sections or subsection layout are needed. Write commands, not essays: + +- Use direct verbs such as _Load_, _Check_, _Run_, _Fix_, _Stop_, and _Return_. +- Match commands to the declared type: performers direct the complete outcome; routers direct only input resolution, invocation, and result routing; teaching skills state principles and decisions for the caller to apply; utilities direct one operation and its result. +- Give each step or subsection one coherent behavioural idea and one observable outcome. +- Use short concrete words and clear fragments; expand conditions, risks, and handoffs that compression could hide. +- State each normative meaning once. Remove filler, hedging, generic knowledge, and repeated enforcement. +- State the intended action first. Retain prohibitions only for essential safety, permission, scope, factual, or deterministic boundaries, paired with the safe action. +- Use a recognised method, principle, theory, or technique only when its canonical name replaces explanation or sharpens a decision, action, or stopping condition. Bold key concepts where they occur naturally. Remove terms that forward testing shows are decorative. +- Match **degrees of freedom** to variability and fragility. Use exact commands or scripts only when the operation requires them. +- Apply **context isolation** to every independently actionable step. Write an explicit fresh-agent step when task-scoped inputs are sufficient and main-thread context is irrelevant or could bias the result; pass only the required inputs and retain only its result. Keep shared understanding, user authority, accumulated state, and process continuity in the main thread. Name the execution boundary instead of leaving delegation optional. +- Give agents a direct result and stopping condition. Add review or feedback only in response to observable evidence, never as recurring ceremony. + +The candidate contains only behaviour-changing instructions and reachable resources. + +### 6. Validate and measure + +Run [scripts/validate-skill.js](scripts/validate-skill.js) and [scripts/measure-context.js](scripts/measure-context.js) with Bun: + +```sh +bun scripts/validate-skill.js /path/to/candidate-skill +bun scripts/measure-context.js /path/to/skill \ + --include references/loaded-reference.md \ + --output /path/to/agent-output.md +``` + +Fix mechanical failures. Repeat `--include` for every reference an arm loaded and `--output` for every arm output; omit unused options. Tokenize a no-skill output through an evaluated bundle and record its discovery and loaded-path cost as zero. Treat exact `o200k_base` counts as comparative evidence, not a target or quality score. Keep discovery metadata, selected path, generated output, and bundle inventory separate. + +### 7. Complete the forward comparison + +Run the candidate on the frozen common-path task in an isolated fresh agent with the same harness, tools, permissions, and task-scoped inputs as the recorded arms. Record its result, loaded path, agent output, tool calls, and iterations. + +Give the anonymised no-skill and candidate results, plus the current-skill result for revisions, to a separate fresh evaluator with only the confirmed behaviour, expected outcome, and efficiency criteria. Require a meaningful behavioural shift over no skill; for revisions, also require preserved or improved behaviour over the current skill. Among behaviourally equivalent candidates, prefer the lower context and execution burden. The candidate's effect is independently evidenced. + +### 8. Refine and publish + +Change the candidate only to correct a specific evaluator failure or remove measured burden, then rerun the affected mechanical and forward checks. Stop when the candidate passes, a smaller equivalent candidate wins, or further change lacks observed justification. + +Publish the passing candidate to the requested destination and rerun validation and measurement there. When the candidate is not justified, keep the existing destination unchanged and return the evidence. The published bundle is the smallest evaluated version that fulfils the confirmed contract. + +## Rules + +- Preserve exact technical meaning: required keywords, paths, commands, API names, error text, safety boundaries, and ordering constraints. +- Treat output tokens, tool calls, and iterations as part of skill cost. Accept extra work only when it changes the required outcome. +- Keep mechanical checks deterministic. Judge semantic force, routing language, useful concepts, and unnecessary ceremony through the forward comparison. + +## Handoff + +Return the destination, confirmed contract, validation result, published files, evaluator verdict, residual uncertainty, and this comparison. Use `n/a` for Current on new skills. Compare Candidate delta with No skill for creation and Current for revision; also state a revision's behavioural shift over No skill. + +| Metric | No skill | Current | Candidate | Candidate delta | +| ----------------------------------------- | -------- | ------- | --------- | --------------- | +| Behavioural result and evaluator evidence | | | | | +| Discovery metadata tokens | | | | | +| Loaded skill-path tokens | | | | | +| Agent output tokens | | | | | +| Tool calls | | | | | +| Iterations | | | | | +| Total measured token burden | | | | | diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml index 2223e0f..e1917b9 100644 --- a/skills/write-skill/agents/openai.yaml +++ b/skills/write-skill/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Write Skill' - short_description: 'Create and update predictable agent skills' + short_description: 'Author skills through controlled evaluation' policy: allow_implicit_invocation: false diff --git a/skills/write-skill/assets/skill-template.md b/skills/write-skill/assets/skill-template.md new file mode 100644 index 0000000..1db761a --- /dev/null +++ b/skills/write-skill/assets/skill-template.md @@ -0,0 +1,15 @@ +--- +name: skill-name +description: Creates the intended outcome. Use when the skill's confirmed trigger applies. +metadata: + type: performer +disable-model-invocation: true +--- + +# Skill Name + +States what the skill enables in one sentence. + +## Process + +Describe the minimum-sufficient behaviour in the form best suited to the work. diff --git a/skills/write-skill/references/CRAFT.md b/skills/write-skill/references/CRAFT.md deleted file mode 100644 index d55e740..0000000 --- a/skills/write-skill/references/CRAFT.md +++ /dev/null @@ -1,45 +0,0 @@ -# Skill Craft - -Use this reference when a methodology, supporting concept, section boundary, leading word, or disclosure decision remains unclear. - -## Compare methodologies - -Research methods against the confirmed behaviour rather than selecting one for familiarity. Use **design it twice** to compare credible candidates through: - -- the process each method would impose; -- the behaviours it strengthens or suppresses; -- its fit across the main success scenario and retained material exceptions; -- the local adaptations it would require; and -- the evidence supporting its published meaning. - -Continue until multiple credible choices emerge or further research is unlikely to change the set. Recommend the strongest fit and expose its trade-offs. When only one survives, compare it with a methodology-free process. - -## Select supporting concepts - -A supporting concept earns inclusion only when it governs a concern the selected methodology leaves unresolved. Name its behavioural job in one sentence and test whether removing it changes the instructions. Use the governor and plain language alone when they already determine the behaviour; retain as many concepts as distinct concerns require. - -## Choose leading words - -Prefer the canonical name of a recognised method, principle, theory, or technique already present in the agent's knowledge. A leading word earns its place when it replaces explanation and sharpens a decision, action, or stopping condition. Remove or replace a term that forward testing shows to be decorative. - -Bold the governing methodology naturally within the introduction when one was selected. Bold a supporting concept where it first governs behaviour, then use plain text unless renewed emphasis changes the instruction. - -## Separate concerns - -Give a step or subsection one coherent behavioural idea and one observable outcome. Split it when any sentence could be acted on, tested, reordered, or completed independently. Keep supporting detail together when separating it would make the action harder to understand or create headings without meaningful content. - -## Disclose depth - -Keep knowledge inline when every invocation needs it to act correctly. Move a retained exception to a reference when its detail would obscure the common path. Write every pointer as the precise loading condition. Pull must-have material back inline when forward tests show that a sharper pointer still misses the behaviour. - -## Remove no-ops - -Test each sentence in isolation: would deleting it change agent behaviour, preserve a necessary condition, or impair navigation? Delete the whole sentence when the answer is no. Prefer a stronger canonical term over several weak adjectives, and prefer one checkable bound over exhortations to be careful or thorough. - -## Remove duplication - -Apply **DRY** to meaning rather than tokens. Give each behaviour, rule, and definition one authoritative expression. Repeating a canonical term can focus attention; repeating its explanation inflates prominence and creates competing authorities. - -## State positive behaviour - -Use ironic process theory as a salience check during final compression. Describe the action the agent should perform, replace avoidable negative framing with that target, and reserve prohibitions for essential safety boundaries that cannot be expressed positively. Pair each retained prohibition with the safe action that satisfies it. The instruction keeps the intended behaviour most salient. diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md index 572f708..aa1a6a7 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -1,50 +1,21 @@ # Skill Sections -Use this reference when invocation metadata, optional sections, or bundled resource placement needs more detail than the fixed skill spine. +Use a section only when it changes execution, constrains the finished result, or transfers responsibility. -## Frontmatter +| Order | Section | Use when | Contains | +| ----- | ------------------ | --------------------------------------------------------------- | ---------------------------------------------------------------------- | +| 1 | `# Skill Name` | Always | Human-readable skill name. | +| 2 | Introduction | Always | One sentence stating what the skill enables. | +| 3 | `## Prerequisites` | Execution must check conditions before starting | Required state and the action taken when it is absent. | +| 4 | `## Process` | Always | The behaviour that produces the result. | +| 5 | `## Rules` | One invariant governs several steps or the finished result | Cross-cutting constraints stated once. | +| 6 | `## Handoff` | An artefact, decision, or responsibility meaningfully transfers | Recipient, transferred result, evidence, and remaining responsibility. | -Include the skill's discovery and invocation contract: +Add another H2 only for a distinct behavioural concern that does not fit this spine. Never create an empty or decorative section. -- `name` matches its directory, uses lowercase letters, digits, and single hyphens, and reads naturally when invoked. -- `description` is one action-oriented line containing the capability and natural trigger conditions. -- `metadata.invocation` records `user` or `model`. -- `disable-model-invocation` and `agents/openai.yaml` use the matching policy. +Within `## Process`: -Use user invocation by default. Use model invocation only when autonomous discovery would naturally help during ordinary coding work often enough to earn the permanent description context. - -| Invocation | `disable-model-invocation` | `policy.allow_implicit_invocation` | -| ---------- | -------------------------- | ---------------------------------- | -| `user` | `true` | `false` | -| `model` | `false` | `true` | - -Add `agents/openai.yaml` with a human-readable `interface.display_name`, a 25–64-character `interface.short_description`, and the matching policy. - -## Introduction - -The fixed spine and emphasis rules in the main workflow are authoritative. Use the introduction to explain only the selected methodology's context-specific adaptation. - -## Process details - -Within `## Process`, use numbered H3 headings when order matters, descriptive H3 headings for distinct non-sequential concerns, or direct prose for a truly thin process. For branches, use descriptive H3 headings and numbered H4 steps only when the nested sequence improves execution. Each section carries one coherent behavioural idea; each ordered step ends in an observable postcondition. - -## Optional sections - -Add an H2 when it communicates the content more clearly than placement beside the process instruction it governs: - -- `## Prerequisites` states external conditions and the safe route when absent. -- `## Rules` holds invariants that constrain multiple instructions or the finished result. -- `## Handoff` states a meaningful transfer, its evidence, and unresolved uncertainty. - -Rename or combine optional sections when that improves the confirmed behaviour. Every optional section earns its place through clearer execution. - -## Bundled resources - -Use **progressive disclosure** as an information hierarchy: - -- Keep the common execution path in `SKILL.md`. -- Put conditional or extensive runtime guidance in `references/`. -- Put files consumed or copied into generated output in `assets/`. -- Put deterministic, repeated, or fragile operations in `scripts/`. - -Add a resource when a retained material exception or other conditional depth improves execution. Link every resource directly from `SKILL.md` beside a precise condition that tells the agent when it may help. Keep references one level deep and each meaning in one authoritative location. References contain runtime guidance rather than general concept explanations. +- Use an ordered list or numbered H3s when order changes the result. +- Use H3s when actions can be tested, reordered, or completed independently. +- Keep supporting detail with its action when separation would hide meaning or create a hollow heading. +- Use bullets for independent items, tables for fixed mappings or comparisons, blockquotes for exact authority, and code fences for literal content. diff --git a/skills/write-skill/references/TESTING.md b/skills/write-skill/references/TESTING.md deleted file mode 100644 index 263937e..0000000 --- a/skills/write-skill/references/TESTING.md +++ /dev/null @@ -1,29 +0,0 @@ -# Forward Testing - -Use this reference when scenario selection, context isolation, or observable pass evidence needs more detail than the main success scenario. - -## Preserve the evaluation boundary - -Give the fresh agent the finished bundle and a realistic user request. Keep the intended answer, design rationale, suspected failure, and prior test output outside the evaluation context. Use an inert workspace or read-only artifacts; permit safe local writes only when the scenario requires them. A test demonstrates transferable steering when the finished bundle and task-local evidence supply the result. - -## Select scenarios - -Run the main success scenario for every created or rewritten skill. Add the smallest scenario for a retained material exception when it distinguishes: - -- an evidenced invocation that changes the required process or result; -- a necessary safety, permission, or prerequisite boundary; -- an optional reference needed by the retained exception; -- a fragile script or deterministic output contract; or -- wording whose effect depends on a leading word. - -Prefer one scenario that distinguishes several competing behaviours when its failure remains diagnosable. The scenario set contains only confirmed behaviour or material risk rather than hypothetical combinations. - -## Define evidence - -Translate the confirmed contract into observable pass conditions before reading the result. Inspect the agent's actions, resource reads, decisions, output, and postconditions. Pass only when the skill invokes the confirmed process, loads relevant context, follows every required branch, and derives its result from the evaluation boundary. - -## Repair the smallest cause - -Trace each failure to the smallest instruction, pointer, section boundary, or missing resource that explains it. Repair that cause, then rerun the failed scenario and a common-path scenario. Recompress and mechanically revalidate after every material change. - -Stop when every confirmed scenario passes or reducing the remaining variance would change the confirmed contract. Report unresolved variance plainly. diff --git a/skills/write-skill/scripts/measure-context.js b/skills/write-skill/scripts/measure-context.js new file mode 100644 index 0000000..77e2f8c --- /dev/null +++ b/skills/write-skill/scripts/measure-context.js @@ -0,0 +1,347 @@ +#!/usr/bin/env bun + +import fs from 'node:fs'; +import path from 'node:path'; +import process from 'node:process'; +import { pathToFileURL } from 'node:url'; + +const args = process.argv.slice(2); +const target = args.shift(); + +if (!target) { + console.error( + 'Usage: bun scripts/measure-context.js [--include relative/path ...] [--output file ...] [--json]', + ); + process.exit(2); +} + +const includes = []; +const outputs = []; +let json = false; + +while (args.length) { + const option = args.shift(); + if (option === '--include') includes.push(args.shift()); + else if (option === '--output') outputs.push(args.shift()); + else if (option === '--json') json = true; + else { + console.error(`Unknown option: ${option}`); + process.exit(2); + } +} + +if ([...includes, ...outputs].some((value) => !value)) { + console.error('--include and --output require a path.'); + process.exit(2); +} + +const root = path.resolve(target); +const rootReal = fs.existsSync(root) ? fs.realpathSync(root) : root; +const skillPath = path.join(root, 'SKILL.md'); +if (!fs.existsSync(skillPath) || !fs.statSync(skillPath).isFile()) { + console.error(`Missing SKILL.md: ${skillPath}`); + process.exit(1); +} +if (!isWithinRoot(skillPath, true)) { + console.error(`SKILL.md resolves outside the skill bundle: ${skillPath}`); + process.exit(1); +} + +function measureText(label, filePath, text) { + return { + label, + path: filePath, + kind: 'text', + tokens: encoder.encode(text).length, + bytes: Buffer.byteLength(text, 'utf8'), + characters: [...text].length, + lines: + text === '' + ? 0 + : text.split(/\r?\n/).length - (/\r?\n$/.test(text) ? 1 : 0), + }; +} + +function isWithinRoot(candidate, resolveSymlinks = false) { + const comparable = resolveSymlinks ? fs.realpathSync(candidate) : candidate; + const base = resolveSymlinks ? rootReal : root; + return comparable === base || comparable.startsWith(`${base}${path.sep}`); +} + +function isInside(base, candidate) { + const relativePath = path.relative(base, candidate); + return relativePath !== '' && !relativePath.startsWith('..'); +} + +function nearestAncestor(startDirectory, matches) { + let directory = path.resolve(startDirectory); + + while (true) { + if (matches(directory)) return directory; + const parent = path.dirname(directory); + if (parent === directory) return null; + directory = parent; + } +} + +function propulsionRoot() { + return nearestAncestor(import.meta.dir, (directory) => { + const manifestPath = path.join(directory, 'package.json'); + if (!fs.existsSync(manifestPath)) return false; + const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); + return manifest.name === 'propulsion'; + }); +} + +function executionProjectRoot() { + const gitRoot = nearestAncestor(process.cwd(), (directory) => + fs.existsSync(path.join(directory, '.git')), + ); + if (gitRoot) return gitRoot; + + return nearestAncestor(process.cwd(), (directory) => + fs.existsSync(path.join(directory, 'package.json')), + ); +} + +function installedTokenizerEntry() { + const searchRoots = [propulsionRoot(), executionProjectRoot()].filter( + Boolean, + ); + const visited = new Set(); + const foundVersions = new Set(); + + for (const searchRoot of searchRoots) { + if (visited.has(searchRoot)) continue; + visited.add(searchRoot); + const packageRoot = path.join(searchRoot, 'node_modules', 'tiktoken'); + const manifestPath = path.join(packageRoot, 'package.json'); + if (!fs.existsSync(manifestPath)) continue; + + const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); + if (manifest.version !== '1.0.22') { + foundVersions.add(manifest.version ?? 'an unversioned package'); + continue; + } + + const canonicalRoot = fs.realpathSync(packageRoot); + const entry = fs.realpathSync( + path.join(canonicalRoot, manifest.main ?? 'tiktoken.cjs'), + ); + + if (!isInside(canonicalRoot, entry) || !fs.statSync(entry).isFile()) { + throw new Error('Refusing an invalid installed tiktoken entry.'); + } + + return pathToFileURL(entry).href; + } + + const found = foundVersions.size + ? `; found ${[...foundVersions].join(', ')}` + : ''; + throw new Error( + `Exact context measurement requires tiktoken@1.0.22 installed in Propulsion or the execution project${found}.`, + ); +} + +function readArtifact(absolutePath) { + const buffer = fs.readFileSync(absolutePath); + const binaryExtensions = new Set([ + '.7z', + '.avi', + '.avif', + '.bin', + '.docx', + '.gif', + '.gz', + '.ico', + '.jpeg', + '.jpg', + '.m4a', + '.mov', + '.mp3', + '.mp4', + '.otf', + '.pdf', + '.png', + '.pptx', + '.tar', + '.tgz', + '.ttf', + '.wasm', + '.webp', + '.woff', + '.woff2', + '.xlsx', + '.zip', + ]); + if (binaryExtensions.has(path.extname(absolutePath).toLowerCase())) + return { kind: 'binary', buffer }; + if (buffer.includes(0)) return { kind: 'binary', buffer }; + try { + return { + kind: 'text', + text: new TextDecoder('utf-8', { fatal: true }).decode(buffer), + }; + } catch { + return { kind: 'binary', buffer }; + } +} + +function measureFile(label, absolutePath, displayPath = absolutePath) { + const artifact = readArtifact(absolutePath); + if (artifact.kind === 'binary') { + return { + label, + path: displayPath, + kind: 'binary', + tokens: null, + bytes: artifact.buffer.length, + }; + } + return measureText(label, displayPath, artifact.text); +} + +function readPath(value, base = root, requireInsideRoot = false) { + const absolutePath = path.resolve(base, value); + if (requireInsideRoot && !isWithinRoot(absolutePath)) { + throw new Error( + `Selected-path file is outside the skill bundle: ${absolutePath}`, + ); + } + if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { + throw new Error(`File not found: ${absolutePath}`); + } + if (requireInsideRoot && !isWithinRoot(absolutePath, true)) { + throw new Error( + `Selected-path file resolves outside the skill bundle: ${absolutePath}`, + ); + } + return { absolutePath, artifact: readArtifact(absolutePath) }; +} + +function walkFiles(directory) { + const files = []; + for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { + if (['.git', 'node_modules'].includes(entry.name)) continue; + const absolutePath = path.join(directory, entry.name); + if (entry.isDirectory()) files.push(...walkFiles(absolutePath)); + if (entry.isFile()) files.push(absolutePath); + } + return files; +} + +let encoder; + +try { + const tokenizerEntry = installedTokenizerEntry(); + const { get_encoding: getEncoding } = await import(tokenizerEntry); + encoder = getEncoding('o200k_base'); + const skillText = fs.readFileSync(skillPath, 'utf8'); + const frontmatterMatch = skillText.match( + /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/, + ); + if (!frontmatterMatch) + throw new Error('SKILL.md has no valid frontmatter block.'); + const frontmatter = Bun.YAML.parse(frontmatterMatch[1]); + const discoveryText = `${frontmatter.name}\n${frontmatter.description}`; + const skillBody = skillText.slice(frontmatterMatch[0].length); + + const selectedFiles = [ + measureText('SKILL.md body', 'SKILL.md', skillBody), + ...includes.map((relativePath) => { + const { absolutePath, artifact } = readPath( + relativePath, + root, + true, + ); + if (artifact.kind === 'binary') { + throw new Error( + `Selected-path file is binary and cannot be tokenized: ${relativePath}`, + ); + } + return measureText( + relativePath, + path.relative(root, absolutePath), + artifact.text, + ); + }), + ]; + + const outputFiles = outputs.map((filePath) => { + const { absolutePath } = readPath(filePath, process.cwd()); + return measureFile(path.basename(absolutePath), absolutePath); + }); + + const bundleFiles = walkFiles(root).map((absolutePath) => + measureFile( + path.relative(root, absolutePath), + absolutePath, + path.relative(root, absolutePath), + ), + ); + + const result = { + encoding: 'o200k_base', + scope: 'Exact o200k_base counts for text artefacts; binary artefacts, host wrappers, and hidden instructions are excluded.', + discovery: measureText( + 'name + description', + 'SKILL.md frontmatter', + discoveryText, + ), + selected_path: { + files: selectedFiles, + tokens: selectedFiles.reduce((sum, item) => sum + item.tokens, 0), + }, + generated_output: { + files: outputFiles, + tokens: outputFiles.reduce( + (sum, item) => sum + (item.tokens ?? 0), + 0, + ), + }, + bundle_inventory: { + files: bundleFiles, + tokens: bundleFiles.reduce( + (sum, item) => sum + (item.tokens ?? 0), + 0, + ), + binary_files: bundleFiles.filter((item) => item.kind === 'binary') + .length, + }, + }; + + if (json) { + console.log(JSON.stringify(result, null, 2)); + } else { + console.log(`Encoding: ${result.encoding}`); + console.log(`Scope: ${result.scope}`); + console.log(`Discovery metadata: ${result.discovery.tokens} tokens`); + console.log(`Selected path: ${result.selected_path.tokens} tokens`); + for (const file of result.selected_path.files) + console.log(` ${file.path}: ${file.tokens}`); + if (outputFiles.length) { + console.log( + `Generated output: ${result.generated_output.tokens} tokens`, + ); + for (const file of outputFiles) { + console.log( + ` ${file.path}: ${file.tokens ?? `binary, ${file.bytes} bytes`}`, + ); + } + } + console.log( + `Bundle inventory: ${result.bundle_inventory.tokens} tokens`, + ); + if (result.bundle_inventory.binary_files) { + console.log( + `Binary artefacts excluded: ${result.bundle_inventory.binary_files}`, + ); + } + } +} catch (error) { + console.error(`Measurement failed: ${error.message}`); + process.exitCode = 1; +} finally { + encoder?.free(); +} diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js index 0878316..1e8a74a 100644 --- a/skills/write-skill/scripts/validate-skill.js +++ b/skills/write-skill/scripts/validate-skill.js @@ -1,328 +1,595 @@ #!/usr/bin/env bun -import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'; -import { basename, join, relative, resolve, sep } from 'node:path'; - -const errors = []; -const warnings = []; +import fs from 'node:fs'; +import path from 'node:path'; +import process from 'node:process'; +import { pathToFileURL } from 'node:url'; + +function nearestAncestor(startDirectory, matches) { + let directory = path.resolve(startDirectory); + + while (true) { + if (matches(directory)) return directory; + const parent = path.dirname(directory); + if (parent === directory) return null; + directory = parent; + } +} -function addError(message) { - errors.push(message); +function propulsionRoot() { + return nearestAncestor(import.meta.dir, (directory) => { + const manifestPath = path.join(directory, 'package.json'); + if (!fs.existsSync(manifestPath)) return false; + const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); + return manifest.name === 'propulsion'; + }); } -function isRecord(value) { - return value !== null && typeof value === 'object' && !Array.isArray(value); +function executionProjectRoot() { + const gitRoot = nearestAncestor(process.cwd(), (directory) => + fs.existsSync(path.join(directory, '.git')), + ); + if (gitRoot) return gitRoot; + + return nearestAncestor(process.cwd(), (directory) => + fs.existsSync(path.join(directory, 'package.json')), + ); } -function parseYaml(raw, label) { - try { - const value = Bun.YAML.parse(raw); +function installedPackageEntry(packageName, expectedVersion) { + const searchRoots = [propulsionRoot(), executionProjectRoot()].filter( + Boolean, + ); + const visited = new Set(); + const foundVersions = new Set(); + + for (const searchRoot of searchRoots) { + if (visited.has(searchRoot)) continue; + visited.add(searchRoot); + const packageRoot = path.join(searchRoot, 'node_modules', packageName); + const manifestPath = path.join(packageRoot, 'package.json'); + if (!fs.existsSync(manifestPath)) continue; + + const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); + if (manifest.version !== expectedVersion) { + foundVersions.add(manifest.version ?? 'an unversioned package'); + continue; + } - if (!isRecord(value)) { - addError(`Make ${label} a YAML mapping.`); - return {}; + const canonicalRoot = fs.realpathSync(packageRoot); + const entry = fs.realpathSync( + path.join(canonicalRoot, manifest.main ?? 'index.js'), + ); + const relativeEntry = path.relative(canonicalRoot, entry); + + if ( + relativeEntry === '' || + relativeEntry.startsWith('..') || + !fs.statSync(entry).isFile() + ) { + throw new Error( + `Refusing an invalid installed ${packageName} entry.`, + ); } - return value; - } catch (error) { - addError(`Parse ${label} as valid YAML: ${error.message}`); - return {}; + return pathToFileURL(entry).href; } + + const found = foundVersions.size + ? `; found ${[...foundVersions].join(', ')}` + : ''; + throw new Error( + `Validation requires ${packageName}@${expectedVersion} installed in Propulsion or the execution project${found}.`, + ); } -function parseFrontmatter(content) { - const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/); +const semverEntry = installedPackageEntry('semver', '7.8.5'); +const { satisfies, validRange } = await import(semverEntry); - if (!match) { - addError('Add YAML frontmatter at the start of SKILL.md.'); - return { body: content, data: {}, raw: '' }; - } +const target = process.argv[2]; - return { - body: content.slice(match[0].length), - data: parseYaml(match[1], 'SKILL.md frontmatter'), - raw: match[1], - }; +if (!target) { + console.error('Usage: bun scripts/validate-skill.js '); + process.exit(2); } -function validateName(frontmatter, skillPath) { - const { name } = frontmatter; +const root = path.resolve(target); +const rootReal = fs.existsSync(root) ? fs.realpathSync(root) : root; +const errors = []; - if (typeof name !== 'string' || !name) { - addError('Add the skill name to frontmatter.'); - return; - } +function fail(message) { + errors.push(message); +} - if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) { - addError( - `Use lowercase letters, digits, and single hyphens for name: ${name}`, - ); +function readRequired(relativePath) { + const absolutePath = path.join(root, relativePath); + if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) { + fail(`Missing required file: ${relativePath}`); + return null; } - - if (name.length > 64) { - addError(`Keep name at most 64 characters; found ${name.length}.`); + if (!isWithinRoot(absolutePath, true)) { + fail( + `Required file resolves outside the skill bundle: ${relativePath}`, + ); + return null; } + return fs.readFileSync(absolutePath, 'utf8'); +} - if (name !== basename(skillPath)) { - addError(`Match name "${name}" to directory "${basename(skillPath)}".`); +function parseYaml(source, relativePath) { + if (source === null) return null; + try { + const value = Bun.YAML.parse(source); + if (!value || typeof value !== 'object' || Array.isArray(value)) { + fail(`${relativePath} must contain a YAML mapping.`); + return null; + } + return value; + } catch (error) { + fail(`${relativePath} contains invalid YAML: ${error.message}`); + return null; } } -function validateDescription(frontmatter, raw) { - const { description } = frontmatter; - const descriptionLine = raw - .split(/\r?\n/) - .find((line) => line.startsWith('description:')); +function analyseMarkdown(source) { + const lines = source.split(/\r?\n/); + let fence = null; + return lines.map((line) => { + const opening = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/); + if (!fence && opening) { + fence = { character: opening[1][0], length: opening[1].length }; + return { raw: line, structural: null, content: false }; + } + const closing = line.match(/^ {0,3}(`{3,}|~{3,})[ \t]*$/); + if ( + fence && + closing && + closing[1][0] === fence.character && + closing[1].length >= fence.length + ) { + fence = null; + return { raw: line, structural: null, content: false }; + } + if (fence) + return { raw: line, structural: null, content: line.trim() !== '' }; + return { + raw: line, + structural: line, + content: line.trim() !== '' && !/^#{1,6}\s/.test(line), + }; + }); +} - if (typeof description !== 'string' || !description) { - addError('Add a one-line description to frontmatter.'); - return; - } +function isWithinRoot(candidate, resolveSymlinks = false) { + const comparable = resolveSymlinks ? fs.realpathSync(candidate) : candidate; + const base = resolveSymlinks ? rootReal : root; + return comparable === base || comparable.startsWith(`${base}${path.sep}`); +} - if (descriptionLine?.match(/^description:\s*[|>]/)) { - addError('Write description on one YAML line.'); - } +function stripNonRenderedText(source) { + const withoutComments = source.replace(/|$)/g, ''); + return withoutComments + .split(/\r?\n/) + .map((line) => { + let result = line; + const runs = [...result.matchAll(/`+/g)]; + for (let index = 0; index + 1 < runs.length; index += 2) { + const opening = runs[index]; + const closing = runs + .slice(index + 1) + .find( + (candidate) => + candidate[0].length === opening[0].length, + ); + if (!closing) break; + const start = opening.index; + const end = closing.index + closing[0].length; + result = `${result.slice(0, start)}${' '.repeat(end - start)}${result.slice(end)}`; + } + return result; + }) + .join('\n'); +} - if (description.length > 200) { - addError( - `Keep description at most 200 characters; found ${description.length}.`, - ); +function markdownLinkTargets(line) { + const targets = []; + for (let index = 0; index < line.length; index += 1) { + if (line[index] !== '[') continue; + let backslashes = 0; + for ( + let cursor = index - 1; + cursor >= 0 && line[cursor] === '\\'; + cursor -= 1 + ) + backslashes += 1; + if (backslashes % 2 === 1) continue; + const labelEnd = line.indexOf('](', index + 1); + if (labelEnd < 0) continue; + let depth = 1; + let cursor = labelEnd + 2; + let escaped = false; + for (; cursor < line.length; cursor += 1) { + const character = line[cursor]; + if (escaped) { + escaped = false; + continue; + } + if (character === '\\') { + escaped = true; + continue; + } + if (character === '(') depth += 1; + if (character === ')') depth -= 1; + if (depth === 0) break; + } + if (depth !== 0) continue; + const inside = line.slice(labelEnd + 2, cursor).trim(); + const destination = inside.startsWith('<') + ? inside.slice(1, inside.indexOf('>')) + : inside.match(/^(?:\\.|[^\s])+/)?.[0]; + if (destination) targets.push(destination.replace(/\\([ ()])/g, '$1')); + index = cursor; } + return targets; +} - if (!/\bUse (?:when|for|to)\b/.test(description)) { - addError( - 'State invocation conditions with Use when, Use for, or Use to.', - ); - } +function equalStringMaps(left, right) { + const leftKeys = Object.keys(left).toSorted(); + const rightKeys = Object.keys(right).toSorted(); + return ( + leftKeys.length === rightKeys.length && + leftKeys.every( + (key, index) => + key === rightKeys[index] && left[key] === right[key], + ) + ); +} - if (/\b(?:I|me|my|mine|we|us|our|ours)\b/i.test(description)) { - addError( - 'Write description in third-person, action-oriented language.', - ); +function walkFiles(directory) { + const files = []; + for (const entry of fs.readdirSync(directory, { withFileTypes: true })) { + if (['.git', 'node_modules'].includes(entry.name)) continue; + const absolutePath = path.join(directory, entry.name); + if (entry.isDirectory()) files.push(...walkFiles(absolutePath)); + if (entry.isFile()) files.push(absolutePath); } + return files; } -function validateInvocation(frontmatter, openai) { - const invocation = isRecord(frontmatter.metadata) - ? frontmatter.metadata.invocation - : null; - const disableModel = frontmatter['disable-model-invocation']; - const allowImplicit = isRecord(openai.policy) - ? openai.policy.allow_implicit_invocation - : null; - - if (!['user', 'model'].includes(invocation)) { - addError('Set metadata.invocation to user or model.'); - return; - } +const skillSource = readRequired('SKILL.md'); +const openaiSource = readRequired('agents/openai.yaml'); - const expectedDisable = invocation === 'user'; - const expectedImplicit = invocation === 'model'; +let frontmatter = null; +let body = ''; - if (disableModel !== expectedDisable) { - addError( - `Set disable-model-invocation to ${expectedDisable} for ${invocation} invocation.`, - ); +if (skillSource !== null) { + const match = skillSource.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/); + if (!match) { + fail('SKILL.md must start with YAML frontmatter delimited by ---.'); + } else { + frontmatter = parseYaml(match[1], 'SKILL.md frontmatter'); + body = skillSource.slice(match[0].length); + + const descriptionLine = match[1] + .split(/\r?\n/) + .find((line) => /^description\s*:/.test(line)); + if ( + !descriptionLine || + /^description\s*:\s*[>|]/.test(descriptionLine) + ) { + fail('description must be a single-line YAML scalar.'); + } } +} - if (allowImplicit !== expectedImplicit) { - addError( - `Set policy.allow_implicit_invocation to ${expectedImplicit} for ${invocation} invocation.`, +if (frontmatter) { + const { name, description } = frontmatter; + if (typeof name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) { + fail( + 'name must use lowercase letters or digits with single hyphen separators.', ); + } else { + if (name.length > 64) fail('name must be 1-64 characters.'); + if (name !== path.basename(root)) + fail('name must match the parent directory name.'); } -} -function validateOpenaiYaml(skillPath, frontmatter) { - const openaiPath = join(skillPath, 'agents', 'openai.yaml'); - - if (!existsSync(openaiPath)) { - addError('Add agents/openai.yaml.'); - return ''; + if (typeof description !== 'string' || description.trim() === '') { + fail('description must be a non-empty string.'); + } else { + if (!/^[A-Z][A-Za-z-]*s\b/.test(description)) { + fail('description must start with a third-person action verb.'); + } + if (!/\bUse (when|for|to)\b/.test(description)) { + fail( + "description must include 'Use when', 'Use for', or 'Use to'.", + ); + } } - const openaiRaw = readFileSync(openaiPath, 'utf8'); - const openai = parseYaml(openaiRaw, 'agents/openai.yaml'); - const skillInterface = isRecord(openai.interface) ? openai.interface : {}; - const displayName = skillInterface.display_name; - const shortDescription = skillInterface.short_description; - - if (typeof displayName !== 'string' || !displayName) - addError('Set interface.display_name in agents/openai.yaml.'); - - if (typeof shortDescription !== 'string' || !shortDescription) { - addError('Set interface.short_description in agents/openai.yaml.'); - } else if (shortDescription.length < 25 || shortDescription.length > 64) { - addError( - `Keep interface.short_description between 25 and 64 characters; found ${shortDescription.length}.`, - ); + if (typeof frontmatter['disable-model-invocation'] !== 'boolean') { + fail('disable-model-invocation must be a boolean.'); } - validateInvocation(frontmatter, openai); - return openai; -} - -function collectMarkdownHeadings(lines) { - const headings = []; - let fence = null; - - for (const line of lines) { - const trimmed = line.trim(); - const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/); - - if (fenceMatch) { - const marker = fenceMatch[1]; - - if (fence === null) { - fence = marker; - } else if ( - marker[0] === fence[0] && - marker.length >= fence.length - ) { - fence = null; - } - - continue; - } - - if (fence === null && /^#{1,6}\s+\S/.test(trimmed)) { - headings.push(trimmed); + const metadata = frontmatter.metadata; + if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) { + fail('metadata must be a YAML mapping.'); + } else { + const allowedTypes = new Set([ + 'performer', + 'router', + 'teaching', + 'utility', + ]); + if (!allowedTypes.has(metadata.type)) { + fail( + 'metadata.type must be performer, router, teaching, or utility.', + ); } } - - return headings; } -function validateBody(body) { - const lines = body.split(/\r?\n/); - const headings = collectMarkdownHeadings(lines); - const firstContentIndex = lines.findIndex((line) => line.trim()); - const firstContent = lines[firstContentIndex]?.trim(); - - if (!firstContent?.match(/^#\s+\S/)) { - addError('Start the skill body with a human-readable H1.'); - return; +const openai = parseYaml(openaiSource, 'agents/openai.yaml'); +if (openai) { + if ( + typeof openai.interface?.display_name !== 'string' || + openai.interface.display_name.trim() === '' + ) { + fail('agents/openai.yaml requires interface.display_name.'); } - - const h1Headings = headings.filter((line) => /^#\s+\S/.test(line)); - - if (h1Headings.length !== 1) { - addError('Add exactly one H1 heading to the skill body.'); + const shortDescription = openai.interface?.short_description; + if ( + typeof shortDescription !== 'string' || + shortDescription.length < 25 || + shortDescription.length > 64 + ) { + fail('interface.short_description must be 25-64 characters.'); } - - const firstH2Index = lines.findIndex((line) => - /^##\s+\S/.test(line.trim()), - ); - const introEnd = firstH2Index === -1 ? lines.length : firstH2Index; - const introduction = lines - .slice(firstContentIndex + 1, introEnd) - .map((line) => line.trim()) - .find((line) => line && !line.startsWith('#')); - - if (!introduction) { - addError('Follow the H1 with a concise introductory paragraph.'); + if (typeof openai.policy?.allow_implicit_invocation !== 'boolean') { + fail( + 'agents/openai.yaml requires boolean policy.allow_implicit_invocation.', + ); } - - const processHeadings = headings.filter((line) => line === '## Process'); - - if (processHeadings.length !== 1) { - addError('Add exactly one ## Process heading to the skill body.'); + if ( + frontmatter && + typeof frontmatter['disable-model-invocation'] === 'boolean' && + typeof openai.policy?.allow_implicit_invocation === 'boolean' && + frontmatter['disable-model-invocation'] === + openai.policy.allow_implicit_invocation + ) { + fail( + 'Claude and OpenAI invocation settings must describe the same invocation mode.', + ); } } -function collectFiles(directory, prefix) { - if (!existsSync(directory)) return []; +if (fs.existsSync(path.join(root, 'agents/openai.yml'))) { + fail('Use agents/openai.yaml, not agents/openai.yml.'); +} - return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => { - const absolute = join(directory, entry.name); - const relativePath = `${prefix}/${entry.name}`; +if (skillSource !== null) { + if (body.trim() === '') + fail('SKILL.md must contain a non-empty body after frontmatter.'); - return entry.isDirectory() - ? collectFiles(absolute, relativePath) - : [relativePath]; + const lines = analyseMarkdown(body); + const headings = []; + lines.forEach(({ structural }, index) => { + const match = structural?.match(/^(#{1,6})\s+(\S.*)$/); + if (match) + headings.push({ + level: match[1].length, + text: match[2].trim(), + line: index, + }); }); -} -function validateResources(skillPath, body) { - const resources = ['references', 'assets', 'scripts'].flatMap((directory) => - collectFiles(join(skillPath, directory), directory), - ); - const linked = new Set(); - const linkPattern = /\[[^\]]*\]\(([^)]+)\)/g; - - for (const match of body.matchAll(linkPattern)) { - const rawTarget = match[1].split('#')[0]; - const target = rawTarget.startsWith('./') - ? rawTarget.slice(2) - : rawTarget; - const normalized = target.split('/').join(sep); + const h1s = headings.filter(({ level }) => level === 1); + if (h1s.length !== 1) + fail( + 'SKILL.md must contain exactly one H1 outside fenced code blocks.', + ); - if (!/^(?:references|assets|scripts)\//.test(target)) continue; + const processHeadings = headings.filter( + ({ level, text }) => level === 2 && text === 'Process', + ); + if (processHeadings.length !== 1) + fail('SKILL.md must contain exactly one ## Process heading.'); + + if (h1s.length === 1) { + const firstContentLine = lines.findIndex(({ raw }) => raw.trim()); + if (firstContentLine !== h1s[0].line) + fail('The H1 must be the first body content.'); + + const firstH2 = headings.find(({ level }) => level === 2); + const introduction = lines + .slice(h1s[0].line + 1, firstH2?.line ?? lines.length) + .filter(({ raw }) => raw.trim()); + if ( + introduction.length !== 1 || + introduction[0].structural === null || + introduction[0].raw.startsWith('#') + ) { + fail( + 'The H1 must be followed by one non-empty introduction line before the first H2.', + ); + } + } - linked.add(target); - if (!existsSync(join(skillPath, normalized))) { - addError(`Create linked resource ${target} or update its pointer.`); + const h2s = headings.filter(({ level }) => level === 2); + for (const reserved of ['Prerequisites', 'Process', 'Rules', 'Handoff']) { + if (h2s.filter(({ text }) => text === reserved).length > 1) { + fail(`## ${reserved} may appear at most once.`); } } - for (const resource of resources) { - if (!linked.has(resource)) { - addError( - `Link ${resource} beside the step or branch that uses it.`, + const sectionIndex = Object.fromEntries( + h2s.map(({ text }, index) => [text, index]), + ); + if ( + sectionIndex.Prerequisites !== undefined && + sectionIndex.Prerequisites > sectionIndex.Process + ) { + fail('## Prerequisites must appear before ## Process.'); + } + if ( + sectionIndex.Rules !== undefined && + sectionIndex.Rules < sectionIndex.Process + ) { + fail('## Rules must appear after ## Process.'); + } + if (sectionIndex.Handoff !== undefined) { + const lowerBound = sectionIndex.Rules ?? sectionIndex.Process; + if (sectionIndex.Handoff < lowerBound) + fail( + '## Handoff must appear after ## Process and ## Rules when present.', ); - } } - return resources.length; + for (let index = 0; index < headings.length; index += 1) { + const heading = headings[index]; + const next = headings + .slice(index + 1) + .find(({ level }) => level <= heading.level); + const content = lines + .slice(heading.line + 1, next?.line ?? lines.length) + .some(({ content: hasContent }) => hasContent); + if (!content) fail(`Heading '${heading.text}' has no content.`); + } } -function validateSkill(skillPath) { - if (!existsSync(skillPath)) { - addError(`Provide an existing skill directory: ${skillPath}`); - return null; +if (fs.existsSync(root)) { + const files = walkFiles(root); + const markdownFiles = files.filter((file) => file.endsWith('.md')); + const linkedFromSkill = new Set(); + + for (const file of markdownFiles) { + const source = fs.readFileSync(file, 'utf8'); + const linkSource = file === path.join(root, 'SKILL.md') ? body : source; + for (const { structural } of analyseMarkdown( + stripNonRenderedText(linkSource), + )) { + if (structural === null) continue; + for (const linkTarget of markdownLinkTargets(structural)) { + const rawTarget = linkTarget.trim().split('#')[0]; + if (!rawTarget || /^(?:[a-z]+:|#)/i.test(rawTarget)) continue; + const resolved = path.resolve( + path.dirname(file), + decodeURIComponent(rawTarget), + ); + if (!isWithinRoot(resolved)) { + fail( + `${path.relative(root, file)} links outside the skill bundle: ${rawTarget}`, + ); + continue; + } + if (!fs.existsSync(resolved)) { + fail( + `${path.relative(root, file)} links to missing path: ${rawTarget}`, + ); + continue; + } + if (!isWithinRoot(resolved, true)) { + fail( + `${path.relative(root, file)} links through a symlink outside the skill bundle: ${rawTarget}`, + ); + continue; + } + if (file === path.join(root, 'SKILL.md')) + linkedFromSkill.add(resolved); + } + } } - if (!statSync(skillPath).isDirectory()) { - addError(`Provide a skill directory: ${skillPath}`); - return null; + for (const file of files.filter((candidate) => + candidate.startsWith(path.join(root, 'references') + path.sep), + )) { + if (!linkedFromSkill.has(file)) { + fail( + `Reference must be linked directly from SKILL.md: ${path.relative(root, file)}`, + ); + } } - const skillFile = join(skillPath, 'SKILL.md'); - if (!existsSync(skillFile)) { - addError('Add SKILL.md to the skill directory.'); - return null; + const packagePath = path.join(root, 'package.json'); + if (fs.existsSync(packagePath)) { + let packageJson = null; + try { + packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8')); + } catch (error) { + fail(`package.json contains invalid JSON: ${error.message}`); + } + const lockPath = path.join(root, 'package-lock.json'); + if (!fs.existsSync(lockPath)) { + fail('package-lock.json is required when package.json exists.'); + } else { + try { + const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8')); + const lockRoot = lock.packages?.['']; + if (![2, 3].includes(lock.lockfileVersion) || !lockRoot) { + fail( + 'package-lock.json must use lockfileVersion 2 or 3 and contain a root package entry.', + ); + } else if (packageJson) { + if ( + lockRoot.name !== packageJson.name || + lockRoot.version !== packageJson.version + ) { + fail( + 'package-lock.json root name and version must match package.json.', + ); + } + const declared = packageJson.dependencies ?? {}; + const locked = lockRoot.dependencies ?? {}; + if (!equalStringMaps(declared, locked)) { + fail( + 'package-lock.json root dependencies must match package.json.', + ); + } + for (const dependency of Object.keys(declared)) { + const entry = + lock.packages?.[`node_modules/${dependency}`]; + if (!entry?.version) { + fail( + `package-lock.json lacks a complete entry for dependency: ${dependency}`, + ); + continue; + } + const range = validRange(declared[dependency]); + if ( + range && + !satisfies(entry.version, range, { + includePrerelease: true, + }) + ) { + fail( + `package-lock.json version for ${dependency} does not satisfy package.json.`, + ); + } + if ( + entry.resolved?.startsWith('http') && + !/^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/.test( + entry.integrity ?? '', + ) + ) { + fail( + `package-lock.json has invalid integrity for dependency: ${dependency}`, + ); + } + } + } + } catch (error) { + fail( + `package-lock.json contains invalid JSON: ${error.message}`, + ); + } + } } - - const content = readFileSync(skillFile, 'utf8'); - const { body, data, raw } = parseFrontmatter(content); - - validateName(data, skillPath); - validateDescription(data, raw); - validateOpenaiYaml(skillPath, data); - validateBody(body); - const resourceCount = validateResources(skillPath, body); - - return { - resources: resourceCount, - }; } -const cliArguments = process.argv.slice(2); -let target = null; - -if (cliArguments.length !== 1 || cliArguments[0].startsWith('--')) { - addError('Run bun validate-skill.js .'); -} else { - target = resolve(cliArguments[0]); +if (errors.length) { + console.error('Status: invalid'); + for (const error of errors) console.error(`- ${error}`); + process.exit(1); } -const stats = target ? validateSkill(target) : null; -const result = { - path: target ? relative(process.cwd(), target) || '.' : null, - valid: errors.length === 0, - errors, - warnings, - stats, -}; - -console.log(JSON.stringify(result, null, 2)); -process.exitCode = result.valid ? 0 : 1; +console.log(`Status: valid\nSkill: ${root}`);