From 130c7955981a9db1407ddf06c5a431dcd34d58c1 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter Date: Mon, 13 Jul 2026 13:58:29 +0100 Subject: [PATCH 01/52] Reset --- .agents/skills | 1 - .agents/skills/domain-modeling/ADR-FORMAT.md | 47 ++ .../skills/domain-modeling/CONTEXT-FORMAT.md | 60 ++ .agents/skills/domain-modeling/SKILL.md | 74 +++ .agents/skills/grill-with-docs/SKILL.md | 7 + .agents/skills/grilling/SKILL.md | 12 + .oxfmtrc.json | 6 +- CONTEXT.md | 83 +++ hooks/hooks.json | 17 - hooks/run-hook.cmd | 7 - hooks/session-start | 14 - index.mjs | 54 -- lib/bootstrap-guidance.js | 32 -- opencode.json | 4 - package.json | 4 +- skills/brainstorm/SKILL.md | 60 -- skills/brainstorm/references/prd-template.md | 86 --- skills/commit/SKILL.md | 54 -- skills/commit/references/workflow.md | 48 -- skills/debug/SKILL.md | 66 --- .../debug/references/bug-feedback-prompt.md | 76 --- .../debug/references/bug-reviewer-prompt.md | 135 ----- skills/debug/references/bug-worker-prompt.md | 72 --- skills/debug/references/debug-template.md | 145 ----- skills/debug/references/investigation-loop.md | 84 --- skills/discover-project/SKILL.md | 72 --- .../references/discovery-checklist.md | 55 -- .../project-brief-reviewer-prompt.md | 92 ---- .../references/project-brief-template.md | 172 ------ skills/execute/SKILL.md | 74 --- skills/execute/references/reviewer-prompt.md | 120 ---- .../references/worker-feedback-prompt.md | 102 ---- skills/execute/references/worker-prompt.md | 83 --- skills/init-project/SKILL.md | 49 -- skills/init-project/references/examples.md | 86 --- skills/init-project/references/process.md | 83 --- skills/interrogate/SKILL.md | 47 -- .../references/interrogate-protocol.md | 54 -- skills/plan/SKILL.md | 63 --- .../plan/references/plan-reviewer-prompt.md | 100 ---- skills/plan/references/plan-template.md | 103 ---- skills/pr/SKILL.md | 59 -- skills/pr/references/workflow.md | 106 ---- skills/propulsion/SKILL.md | 62 --- skills/review/SKILL.md | 59 -- skills/review/references/issue-schema.md | 54 -- skills/review/references/mode-selection.md | 40 -- skills/review/references/report-format.md | 97 ---- skills/review/references/review-axes.md | 47 -- skills/review/references/reviewer-prompt.md | 59 -- skills/review/references/validation-rubric.md | 62 --- skills/review/references/validator-prompt.md | 48 -- skills/tdd/SKILL.md | 59 -- skills/tdd/references/refactor-candidates.md | 84 --- skills/tdd/references/testing-patterns.md | 112 ---- skills/write-skill/SKILL.md | 58 +- skills/write-skill/agents/openai.yaml | 2 + skills/write-skill/assets/skill-template.md | 97 ---- skills/write-skill/references/FORMAT.md | 50 ++ skills/write-skill/references/checklist.md | 76 --- skills/write-skill/scripts/validate-skill.js | 426 --------------- tests/codex-hook.test.js | 111 ---- tests/opencode-plugin.test.js | 117 ---- tests/write-skill-validator.test.js | 513 ------------------ 64 files changed, 363 insertions(+), 4638 deletions(-) delete mode 120000 .agents/skills create mode 100644 .agents/skills/domain-modeling/ADR-FORMAT.md create mode 100644 .agents/skills/domain-modeling/CONTEXT-FORMAT.md create mode 100644 .agents/skills/domain-modeling/SKILL.md create mode 100644 .agents/skills/grill-with-docs/SKILL.md create mode 100644 .agents/skills/grilling/SKILL.md create mode 100644 CONTEXT.md delete mode 100644 hooks/hooks.json delete mode 100755 hooks/run-hook.cmd delete mode 100755 hooks/session-start delete mode 100644 index.mjs delete mode 100644 lib/bootstrap-guidance.js delete mode 100644 opencode.json delete mode 100644 skills/brainstorm/SKILL.md delete mode 100644 skills/brainstorm/references/prd-template.md delete mode 100644 skills/commit/SKILL.md delete mode 100644 skills/commit/references/workflow.md delete mode 100644 skills/debug/SKILL.md delete mode 100644 skills/debug/references/bug-feedback-prompt.md delete mode 100644 skills/debug/references/bug-reviewer-prompt.md delete mode 100644 skills/debug/references/bug-worker-prompt.md delete mode 100644 skills/debug/references/debug-template.md delete mode 100644 skills/debug/references/investigation-loop.md delete mode 100644 skills/discover-project/SKILL.md delete mode 100644 skills/discover-project/references/discovery-checklist.md delete mode 100644 skills/discover-project/references/project-brief-reviewer-prompt.md delete mode 100644 skills/discover-project/references/project-brief-template.md delete mode 100644 skills/execute/SKILL.md delete mode 100644 skills/execute/references/reviewer-prompt.md delete mode 100644 skills/execute/references/worker-feedback-prompt.md delete mode 100644 skills/execute/references/worker-prompt.md delete mode 100644 skills/init-project/SKILL.md delete mode 100644 skills/init-project/references/examples.md delete mode 100644 skills/init-project/references/process.md delete mode 100644 skills/interrogate/SKILL.md delete mode 100644 skills/interrogate/references/interrogate-protocol.md delete mode 100644 skills/plan/SKILL.md delete mode 100644 skills/plan/references/plan-reviewer-prompt.md delete mode 100644 skills/plan/references/plan-template.md delete mode 100644 skills/pr/SKILL.md delete mode 100644 skills/pr/references/workflow.md delete mode 100644 skills/propulsion/SKILL.md delete mode 100644 skills/review/SKILL.md delete mode 100644 skills/review/references/issue-schema.md delete mode 100644 skills/review/references/mode-selection.md delete mode 100644 skills/review/references/report-format.md delete mode 100644 skills/review/references/review-axes.md delete mode 100644 skills/review/references/reviewer-prompt.md delete mode 100644 skills/review/references/validation-rubric.md delete mode 100644 skills/review/references/validator-prompt.md delete mode 100644 skills/tdd/SKILL.md delete mode 100644 skills/tdd/references/refactor-candidates.md delete mode 100644 skills/tdd/references/testing-patterns.md create mode 100644 skills/write-skill/agents/openai.yaml delete mode 100644 skills/write-skill/assets/skill-template.md create mode 100644 skills/write-skill/references/FORMAT.md delete mode 100644 skills/write-skill/references/checklist.md delete mode 100644 skills/write-skill/scripts/validate-skill.js delete mode 100644 tests/codex-hook.test.js delete mode 100644 tests/opencode-plugin.test.js delete mode 100644 tests/write-skill-validator.test.js diff --git a/.agents/skills b/.agents/skills deleted file mode 120000 index 42c5394..0000000 --- a/.agents/skills +++ /dev/null @@ -1 +0,0 @@ -../skills \ No newline at end of file diff --git a/.agents/skills/domain-modeling/ADR-FORMAT.md b/.agents/skills/domain-modeling/ADR-FORMAT.md new file mode 100644 index 0000000..da7e78e --- /dev/null +++ b/.agents/skills/domain-modeling/ADR-FORMAT.md @@ -0,0 +1,47 @@ +# ADR Format + +ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. + +Create the `docs/adr/` directory lazily — only when the first ADR is needed. + +## Template + +```md +# {Short title of the decision} + +{1-3 sentences: what's the context, what did we decide, and why.} +``` + +That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. + +## Optional sections + +Only include these when they add genuine value. Most ADRs won't need them. + +- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited +- **Considered Options** — only when the rejected alternatives are worth remembering +- **Consequences** — only when non-obvious downstream effects need to be called out + +## Numbering + +Scan `docs/adr/` for the highest existing number and increment by one. + +## When to offer an ADR + +All three of these must be true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing." + +### What qualifies + +- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres." +- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." +- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out. +- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s. +- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate. +- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract." +- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months. diff --git a/.agents/skills/domain-modeling/CONTEXT-FORMAT.md b/.agents/skills/domain-modeling/CONTEXT-FORMAT.md new file mode 100644 index 0000000..eaf2a18 --- /dev/null +++ b/.agents/skills/domain-modeling/CONTEXT-FORMAT.md @@ -0,0 +1,60 @@ +# CONTEXT.md Format + +## Structure + +```md +# {Context Name} + +{One or two sentence description of what this context is and why it exists.} + +## Language + +**Order**: +{A one or two sentence description of the term} +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request + +**Customer**: +A person or organization that places orders. +_Avoid_: Client, buyer, account +``` + +## Rules + +- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`. +- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. +- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. +- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. + +## Single vs multi-context repos + +**Single context (most repos):** One `CONTEXT.md` at the repo root. + +**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other: + +```md +# Context Map + +## Contexts + +- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders +- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments +- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping + +## Relationships + +- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking +- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices +- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money` +``` + +The skill infers which structure applies: + +- If `CONTEXT-MAP.md` exists, read it to find contexts +- If only a root `CONTEXT.md` exists, single context +- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved + +When multiple contexts exist, infer which one the current topic relates to. If unclear, ask. diff --git a/.agents/skills/domain-modeling/SKILL.md b/.agents/skills/domain-modeling/SKILL.md new file mode 100644 index 0000000..d0f7e1a --- /dev/null +++ b/.agents/skills/domain-modeling/SKILL.md @@ -0,0 +1,74 @@ +--- +name: domain-modeling +description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. +--- + +# Domain Modeling + +Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) + +## File structure + +Most repos have a single context: + +``` +/ +├── CONTEXT.md +├── docs/ +│ └── adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +└── src/ +``` + +If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: + +``` +/ +├── CONTEXT-MAP.md +├── docs/ +│ └── adr/ ← system-wide decisions +├── src/ +│ ├── ordering/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ ← context-specific decisions +│ └── billing/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. + +## During the session + +### Challenge against the glossary + +When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" + +### Sharpen fuzzy language + +When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." + +### Discuss concrete scenarios + +When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. + +### Cross-reference with code + +When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" + +### Update CONTEXT.md inline + +When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). + +`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. + +### Offer ADRs sparingly + +Only offer to create an ADR when all three are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful +2. **Surprising without context** — a future reader will wonder "why did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons + +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md new file mode 100644 index 0000000..bed05d2 --- /dev/null +++ b/.agents/skills/grill-with-docs/SKILL.md @@ -0,0 +1,7 @@ +--- +name: grill-with-docs +description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. +disable-model-invocation: true +--- + +Run a `/grilling` session, using the `/domain-modeling` skill. diff --git a/.agents/skills/grilling/SKILL.md b/.agents/skills/grilling/SKILL.md new file mode 100644 index 0000000..219930f --- /dev/null +++ b/.agents/skills/grilling/SKILL.md @@ -0,0 +1,12 @@ +--- +name: grilling +description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases. +--- + +Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. + +Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. + +If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. + +Do not enact the plan until I confirm we have reached a shared understanding. diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 398f676..3528913 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -1,6 +1,10 @@ { "$schema": "./node_modules/oxfmt/configuration_schema.json", - "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], + "ignorePatterns": [ + "node_modules/**", + ".opencode/node_modules/**", + ".agents/**" + ], "printWidth": 80, "tabWidth": 4, "singleQuote": true, diff --git a/CONTEXT.md b/CONTEXT.md new file mode 100644 index 0000000..afca342 --- /dev/null +++ b/CONTEXT.md @@ -0,0 +1,83 @@ +# 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 for skills expected to be invoked often enough that automatic discovery earns 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 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 + +**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 + +**Leading word**: +An established concept specific enough for the agent to identify the intended technique without additional explanation. A skill explains only its Propulsion-specific adaptation or constraints. +_Avoid_: Coined term, theme, slogan + +**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 + +**Positive framing**: +Steering that states the desired behaviour directly. Use a negative instruction only for a necessary hard guardrail and pair it with the corrective behaviour. +_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**: +An action the agent performs as part of the skill, ordered when sequence matters and ended by 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 steps or the finished output. +_Avoid_: Step, reminder + +**Handoff**: +A transfer or route that becomes available after the skill's steps are complete. +_Avoid_: Next step, final step + +**Reference**: +Focused supporting documentation linked once beside the condition that requires it and loaded only when that branch is reached. +_Avoid_: Background, resource + +**Dry run**: +A semantic validation that traces concrete use cases through a finished skill before handoff. +_Avoid_: Checklist, structural validation diff --git a/hooks/hooks.json b/hooks/hooks.json deleted file mode 100644 index 499e20f..0000000 --- a/hooks/hooks.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "hooks": { - "SessionStart": [ - { - "matcher": "startup|clear|compact|resume", - "hooks": [ - { - "type": "command", - "command": "\"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}/hooks/run-hook.cmd\" session-start", - "timeout": 10, - "statusMessage": "Loading Propulsion workflow" - } - ] - } - ] - } -} diff --git a/hooks/run-hook.cmd b/hooks/run-hook.cmd deleted file mode 100755 index 8041bfd..0000000 --- a/hooks/run-hook.cmd +++ /dev/null @@ -1,7 +0,0 @@ -#!/bin/sh -set -eu - -script_name="${1:?missing hook script name}" -script_dir="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)" - -exec "$script_dir/$script_name" diff --git a/hooks/session-start b/hooks/session-start deleted file mode 100755 index f27cd64..0000000 --- a/hooks/session-start +++ /dev/null @@ -1,14 +0,0 @@ -#!/bin/sh -set -eu - -plugin_dir="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)" -PLUGIN_DIR="$plugin_dir" node <<'JS' -const { PROPULSION_BOOTSTRAP_GUIDANCE } = require(`${process.env.PLUGIN_DIR}/lib/bootstrap-guidance.js`); - -process.stdout.write(JSON.stringify({ - hookSpecificOutput: { - hookEventName: 'SessionStart', - additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE, - }, -})); -JS diff --git a/index.mjs b/index.mjs deleted file mode 100644 index d4f3f13..0000000 --- a/index.mjs +++ /dev/null @@ -1,54 +0,0 @@ -import { createRequire } from 'node:module'; -import { dirname, join } from 'node:path'; -import { fileURLToPath } from 'node:url'; - -const require = createRequire(import.meta.url); -const { - getPropulsionBootstrapGuidance, -} = require('./lib/bootstrap-guidance.js'); -const PROPULSION_SKILLS_DIR = join( - dirname(fileURLToPath(import.meta.url)), - 'skills', -); - -async function PropulsionPlugin() { - return { - config: async (config) => { - config.skills = config.skills || {}; - config.skills.paths = config.skills.paths || []; - - if (!config.skills.paths.includes(PROPULSION_SKILLS_DIR)) { - config.skills.paths.push(PROPULSION_SKILLS_DIR); - } - }, - 'experimental.chat.messages.transform': async (_input, output) => { - const bootstrap = getPropulsionBootstrapGuidance(); - const firstUser = output.messages?.find( - (message) => message.info.role === 'user', - ); - - if (!firstUser?.parts?.length) { - return; - } - - if ( - firstUser.parts.some( - (part) => - part.type === 'text' && - part.text.includes(''), - ) - ) { - return; - } - - const ref = firstUser.parts[0]; - firstUser.parts.unshift({ - ...ref, - type: 'text', - text: bootstrap, - }); - }, - }; -} - -export default { server: PropulsionPlugin }; diff --git a/lib/bootstrap-guidance.js b/lib/bootstrap-guidance.js deleted file mode 100644 index 6f3f8b3..0000000 --- a/lib/bootstrap-guidance.js +++ /dev/null @@ -1,32 +0,0 @@ -const { readFileSync } = require('node:fs'); -const { join } = require('node:path'); - -const PROPULSION_SKILL_PATH = join( - __dirname, - '..', - 'skills', - 'propulsion', - 'SKILL.md', -); - -function buildPropulsionBootstrapGuidance() { - const propulsionSkill = readFileSync(PROPULSION_SKILL_PATH, 'utf8').trim(); - - return ` -Propulsion workflow entry point: load and follow the propulsion skill when the request is software work. -Route software work through Propulsion before downstream stages. - -${propulsionSkill} -`; -} - -const PROPULSION_BOOTSTRAP_GUIDANCE = buildPropulsionBootstrapGuidance(); - -function getPropulsionBootstrapGuidance() { - return PROPULSION_BOOTSTRAP_GUIDANCE; -} - -module.exports = { - PROPULSION_BOOTSTRAP_GUIDANCE, - getPropulsionBootstrapGuidance, -}; diff --git a/opencode.json b/opencode.json deleted file mode 100644 index 7fc46d3..0000000 --- a/opencode.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "$schema": "https://opencode.ai/config.json", - "default_agent": "plan" -} diff --git a/package.json b/package.json index 58e68cc..7485c6e 100644 --- a/package.json +++ b/package.json @@ -4,12 +4,10 @@ "main": "./index.mjs", "exports": "./index.mjs", "scripts": { - "checks": "bun run lint && bun run format && bun run test", + "checks": "bun run lint && bun run format", "format": "oxfmt .", "format:check": "oxfmt --check .", "lint": "oxlint", - "test": "bun test ./tests", - "test:unit": "bun test ./tests" }, "devDependencies": { "oxfmt": "^0.44.0", diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md deleted file mode 100644 index d509c66..0000000 --- a/skills/brainstorm/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -name: brainstorm -description: Create an approved PRD through repo inspection and interrogation. Use when scope, UX, constraints, or success criteria are unclear, or when user needs a PRD. ---- - -# Brainstorm - -Turn feature, UX, API, product-scope, or requirements work into an approved PRD. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- If user provides an approved `docs/propulsion/.../prd.md`, STOP. Enter the `plan` skill. -- If the request is greenfield project discovery and no target-root `project-brief.md` exists, STOP. Enter the `discover-project` skill. -- If an approved target-root `project-brief.md` exists, read it before interrogation and treat approved discovery decisions as durable PRD inputs. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Load `interrogate` skill and interview the user about their request. -2. Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` from [references/prd-template.md](references/prd-template.md). -3. Meticulously sanity-check `prd.md` against the conversation and add any missing decisions, facts, constraints, behaviours, or success criteria. -4. Ask the user to review and approve `prd.md`. -5. After explicit approval, enter the `plan` skill. - -## Rules - -These rules are MANDATORY. - -- ALWAYS use `interrogate` skill to reach shared understanding BEFORE writing the PRD. -- ALWAYS use the PRD template for structure and section order. -- MUST keep the PRD product-facing and record durable implementation and testing decisions. -- MUST preserve approved discovery decisions from target-root `project-brief.md` unless the user asks to revise them. -- ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor. -- USE supporting documents such as `docs/propulsion/.../diagrams.md` if needed. -- If you cannot write files, STOP, ask the user to enable write mode before continuing the PRD. -- NEVER print the full PRD in the chat, ONLY write it to the file. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Used `interrogate` skill to gather every last detail about the request. -- [ ] Written PRD to `docs/propulsion/.../prd.md`. -- [ ] Compared PRD against conversation and added any missing content. -- [ ] User has explicitly approved `prd.md`. - -## Next Steps - -Once the completion gate is fully checked: - -- If `prd.md` is approved, enter the `plan` skill. - -## References - -Use these references when you need detail. - -- [references/prd-template.md](references/prd-template.md) - PRD shape and output path. diff --git a/skills/brainstorm/references/prd-template.md b/skills/brainstorm/references/prd-template.md deleted file mode 100644 index 7c14716..0000000 --- a/skills/brainstorm/references/prd-template.md +++ /dev/null @@ -1,86 +0,0 @@ -# PRD Template - -Write `docs/propulsion/{yyyymmdd}-{feature-name}/prd.md` using this exact section order. - -```md -# PRD - -## Problem Statement - -State the problem in user language. - -## Solution - -Describe the proposed behaviour end-to-end from the user's perspective. - -## Goals - -- Goal - -## Non-Goals - -- Explicit non-goal - -## User Stories - -| ID | User Story | -| ------ | ---------------------------------------------------- | -| US-001 | As a , I want , so that . | - -## Functional Requirements - -| ID | Requirement | -| ------ | -------------------------------------------- | -| FR-001 | When , the system must . | - -## Non-Functional Requirements - -| ID | Category | Requirement | -| ------- | ----------- | --------------------------------------------- | -| NFR-001 | Performance | must complete within . | - -## Implementation Decisions - -- Durable module or boundary decisions -- Data shape or API contract decisions -- Interaction rules that the `plan` skill should not re-litigate - -## Implementation Inputs - -- External links, tickets, docs, or references -- Business rules or constraints - -## Testing Decisions - -- What public behaviour matters -- Which modules or seams deserve tests -- Prior art worth copying from the repo - -## Out Of Scope - -- Deferred idea -- Thing that must not be implemented - -## Notes - -- Any further notes about the feature -``` - -## Rules - -These rules are MANDATORY. - -- ALWAYS follow the template structure and section order exactly as specified. -- MUST use the following non-functional requirement categories: - - Performance: response times, throughput, resource use. - - Reliability: availability, fault tolerance, recovery. - - Security: data protection, authn/authz, compliance. - - Usability: UX, accessibility, ease of use. - - Scalability: growth in load, users, or data. - - Maintainability: code quality, docs, future changes. - - Compatibility: platform, browser, integration support. - - Portability: deployment across environments. - - Compliance: standards, regulations, policies. - - Monitoring: observability, logging, alerting. -- MUST ensure user stories, functional requirements, and non-functional requirements cover all feature aspects. -- DO create supporting documents with mermaid diagrams, data models, or other relevant artefacts if they help clarify the feature or implementation. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md deleted file mode 100644 index 666db3b..0000000 --- a/skills/commit/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: commit -description: Create one safe local git commit from current changes. Use when asked to commit, save changes, or make a local checkpoint. ---- - -# Commit - -Create one safe local git commit and report the result. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- The current directory is inside a git repository with a writable index. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Inspect state with `git status --short`, `git diff HEAD`, and `git branch --show-current`. -2. Stage all local changes with `git add -A`, including untracked files. -3. Unstage every staged secret-like file matching [references/workflow.md](references/workflow.md). -4. Check staged changes after exclusions; if none remain, stop and output exactly `No changes to commit.` -5. Generate a one-line imperative commit subject from the staged diff. -6. Create exactly one local commit with that subject. -7. Run `git status --short` before the final response. -8. Report the result using the exact success format in [references/workflow.md](references/workflow.md). - -## Rules - -These rules are MANDATORY. - -- MUST create exactly one local commit when committable changes remain after exclusions. -- MUST stage with `git add -A` before applying exclusions. -- MUST unstage secret-like files before committing when they are staged. -- MUST stop with exactly `No changes to commit.` when exclusions leave no committable changes. -- NEVER commit secret-like files. -- NEVER push, open pull requests, amend, reset, force, or run destructive git commands unless user explicitly instructs. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] `git add -A` was run. -- [ ] Secret-like staged files were unstaged or none were present. -- [ ] Exactly one local commit was created, or `No changes to commit.` was returned. -- [ ] No push, pull request, amend, reset, force, or destructive git command was run. -- [ ] Final output matches the required contract. - -## References - -Use these references when you need detail. - -- [references/workflow.md](references/workflow.md) - Secret-like exclusion patterns, commit message rules, and output contract. diff --git a/skills/commit/references/workflow.md b/skills/commit/references/workflow.md deleted file mode 100644 index 937f71d..0000000 --- a/skills/commit/references/workflow.md +++ /dev/null @@ -1,48 +0,0 @@ -# Commit Workflow Reference - -## Inputs - -- Current git status: `git status --short` -- Current git diff, staged and unstaged: `git diff HEAD` -- Current branch: `git branch --show-current` - -## Secret-Like Exclusions - -Never commit likely secret files. Always unstage these patterns before committing: - -- `.env` -- `*.pem` -- `*.key` -- `*.p12` -- `*.pfx` -- `credentials.json` -- `*credentials*` -- `*secret*` -- `*token*` -- `.ssh/*` - -## Commit Message - -Use a normal imperative commit subject: - -- one line only -- short, descriptive, imperative, natural wording -- no trailing punctuation - -## No Committable Changes Output - -If no staged changes remain after exclusions, stop and output exactly: - -```md -No changes to commit. -``` - -## Success Output - -Run `git status --short` before producing the final response. When the commit succeeds, output exactly: - -```md -Commit created: -Message: -Excluded secret-like files: -``` diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md deleted file mode 100644 index cc663dc..0000000 --- a/skills/debug/SKILL.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -name: debug -description: Handle concrete failures through intake, diagnosis, one-hypothesis fixes, review, reset, and escalation. Use when bugs or failures need repair. ---- - -# Debug - -Diagnose concrete failures before one evidence-backed fix loop. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- The request is a concrete failure: bug, regression, crash, failing test/build, incorrect output, flaky behaviour, or runtime error. -- If the request is feature-shaped, product-scope work, expected-behaviour design, refactor, optimisation, or enhancement, STOP and load `brainstorm`. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Create or resume `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` from [references/debug-template.md](references/debug-template.md) before diagnosis work. -2. Record provenance, expected and actual behaviour, impact, environment, reproduction, prior attempts, and blockers in `debug.md`. -3. Load `interrogate` ONLY when missing user-answerable intake blocks expected behaviour, reproduction, impact, or environment; record answers and resolved decisions in `debug.md`. -4. Explore only relevant code, tests, logs, recent changes, ownership, and likely boundaries; record facts and limits in `debug.md`. -5. Use [references/investigation-loop.md](references/investigation-loop.md) to reproduce, read the full error, reduce, compare working examples, isolate the first bad boundary, and test one diagnosis hypothesis at a time. -6. Gate fix dispatch until `debug.md` has grounded diagnosis evidence, the first bad state or divergence, fix constraints, a falsifier, and one chosen fix hypothesis. -7. Dispatch one fresh bug-worker with [references/bug-worker-prompt.md](references/bug-worker-prompt.md), then dispatch one fresh reviewer with [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md). -8. If review rejects the fix and diagnosis still holds, return findings to the active worker with [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md). -9. If verification, review, or new evidence contradicts the diagnosis, reset to investigation and record the contradicted evidence before any new fix attempt. -10. After 3 failed fix loops, reassess architecture and patterns, record it, then escalate with evidence and next options. -11. Close only when fixed and verified, blocked by missing intake, no-repro after documented attempts, or escalated after the 3-loop reassessment path. - -## Rules - -These rules are MANDATORY. - -- MUST keep `debug.md` current from entry through closure. -- MUST diagnose before fixing; NEVER make permanent production-code edits in the controller stage. -- MUST use `interrogate` only for missing user-answerable intake, not repo facts the agent can inspect. -- MUST reset when evidence contradicts the diagnosis or chosen fix hypothesis. -- EVERY fix loop MUST target one chosen fix hypothesis and start with a failing regression test unless `tdd` declares no valuable test. -- MUST record failed hypotheses, blocked/no-repro status, rejected reviews, resets, failed loops, verification, escalation, and closure. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] `debug.md` exists or is resumed at `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md`. -- [ ] Intake, user-answerable `interrogate` decisions if any, targeted exploration, reproduction or no-repro attempts, full error reading, reduction, evidence, hypotheses, diagnosis gate, fix loops, reviews, resets, and verification are recorded. -- [ ] Outcome is one of: fixed and verified; blocked on missing intake; no-repro with documented attempts; reset to diagnosis with contradicted evidence; review-rejected and returned to worker; escalated after 3 failed loops plus architecture and pattern reassessment. - -## Next Steps - -Once the completion gate is fully checked: - -- Return a concise status with the `debug.md` path, final outcome, checks run, and any user decision needed. - -## References - -Use these references when you need detail. - -- [references/debug-template.md](references/debug-template.md) - Living `debug.md` template for the bug dossier. -- [references/investigation-loop.md](references/investigation-loop.md) - Evidence-first reproduce, reduce, isolate, diagnose, reset, and escalate loop. -- [references/bug-worker-prompt.md](references/bug-worker-prompt.md) - Prompt template for one diagnosis-gated TDD fix attempt. -- [references/bug-reviewer-prompt.md](references/bug-reviewer-prompt.md) - Prompt template for independent review of one bug fix attempt. -- [references/bug-feedback-prompt.md](references/bug-feedback-prompt.md) - Prompt template for returning review findings to the active worker. diff --git a/skills/debug/references/bug-feedback-prompt.md b/skills/debug/references/bug-feedback-prompt.md deleted file mode 100644 index ab042f6..0000000 --- a/skills/debug/references/bug-feedback-prompt.md +++ /dev/null @@ -1,76 +0,0 @@ -# Bug Feedback Prompt Template - -Use this template when returning reviewer findings to the active bug-worker during a bug-fix loop in `debug`. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -Your bug-fix attempt was independently reviewed. Treat review items as technical claims to verify. - -## Review Report - - - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Read the review report, current `debug.md`, and active diff. -2. Triage every reviewer finding as `valid`, `invalid`, or `unclear` before changing code. -3. If any finding is `unclear`, STOP and report `Status: unclear` with the missing evidence; do not change code. -4. Confirm each `valid` finding fits the active hypothesis and does not require a new one. -5. If a valid finding or new evidence contradicts diagnosis, hypothesis, or constraints, STOP, update `debug.md`, and reset to diagnosis. -6. For each valid in-scope finding, make the minimal correction within the active hypothesis only. -7. Preserve regression-test-first for any code change; if no new test is valuable, record the `tdd` rationale and fallback proof. -8. Re-run relevant checks and update `debug.md` with triage, code changes, verification, and diagnosis status. -9. Return an implementation report in the exact format defined below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Report - -**Status**: - -**What Changed**: - -- - -**Checks Run**: - -- : -- : - -**Files Changed**: - -- - -**Diagnosis Status**: - -- - - Evidence: - -**Review Feedback Triage**: - -- - - Classification: - - Resolution: - - Evidence: -``` - -## Rules - -These rules are MANDATORY. - -- Preserve the diagnosis reset and one-hypothesis discipline. -- Triage every finding before changing code. -- Do not continue coding once the diagnosis is contradicted. -- Preserve one-hypothesis, one-fix-loop discipline. -- Do not start a second fix hypothesis inside feedback handling; if one is required, update `debug.md` and reset to diagnosis. -- Do not broaden the active fix beyond reviewer findings that fit the chosen fix hypothesis. -- Update `debug.md` before handing control back to `debug`. -- MUST return exactly one `Status:` field with `done`, `blocked`, or `unclear`. -- Follow the output format EXACTLY as defined above. -```` diff --git a/skills/debug/references/bug-reviewer-prompt.md b/skills/debug/references/bug-reviewer-prompt.md deleted file mode 100644 index ef3ddf1..0000000 --- a/skills/debug/references/bug-reviewer-prompt.md +++ /dev/null @@ -1,135 +0,0 @@ -# Bug Reviewer Prompt Template - -Use this template when starting a fresh bug-reviewer subagent for one bug-fix loop in `debug`. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -You are a sceptical implementation reviewer for one bug-fix attempt under the `debug` skill. - -Review the bug-fix attempt like a senior engineer: verify the actual implementation against `debug.md`, the original bug behaviour, diagnosis evidence, tests, maintainability, security, reliability, and regression risk. - -## Inputs - -- **Debug artifact**: `` - -## Implementation Report - -This is the bug-worker report. **Treat it as context, not proof; verify every claim.** - - - -## Review Criteria - -| Category | Verify | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Diagnosis Integrity | `debug.md` has the required diagnosis evidence before production-code changes, and the evidence still explains the original bug without contradictions. | -| Original Bug Correctness | The implementation fixes the reported bug behaviour itself, not only adjacent symptoms or the worker's preferred repro path. | -| Hypothesis / Constraints Fit | The change stays within the chosen hypothesis, fix constraints, affected boundaries, and prior reset evidence in `debug.md`; speculative or symptom-masking changes are rejected. | -| Tests / Verification | Regression-test-first proof is present: failing result for the expected bug before the fix and passing result after, or `tdd` accepted no valuable test with sufficient fallback proof. | -| Maintainability / Refactoring | The fix is clear, cohesive, minimal, and avoids unnecessary complexity, duplicated logic, or hidden changes outside the bug scope. | -| Security / Trust Boundaries | Inputs, permissions, secrets, file access, external calls, prompt boundaries, and other trust boundaries remain safe. | -| Performance / Reliability | The fix avoids avoidable latency, resource waste, flaky behaviour, races, brittle state, or reliability regressions. | -| Integration / Regression Risk | Surrounding APIs, workflows, tests, prompts, feedback loops, and affected boundaries remain compatible. | -| Output Usefulness | Rejections are actionable, evidence-backed, and clear enough for the debug controller or next bug-worker to continue without reinterpretation. | - -Required diagnosis evidence includes exact symptom, reduced repro or flaky classification, full error reading and conclusion, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary and divergence, fix constraints, chosen hypothesis, fail-then-pass proof, and prior-loop reset evidence when applicable. - -Flag only real issues supported by `debug.md`, worker report, code, tests, diff, checks, prompts, or workflow rules. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Read the current `debug.md` and implementation report in full. -2. Inspect the real code, tests, current diff, and check output yourself; do not trust the worker report. -3. Verify the diagnosis gate was complete before the fix and that current evidence has not contradicted it. -4. Verify the test failed first for the expected bug reason, then passed; `debug.md` must show both. If no test, verify `tdd` declared no valuable test and fallback proof is sufficient. -5. Verify the change stays within the chosen hypothesis/constraints, with no symptom masking or unexplained evidence hidden by the patch. -6. Verify checks cover the reported behaviour and affected boundaries. -7. Use the criteria table to evaluate every criterion with evidence. -8. Approve only if gate, hypothesis fit, regression-first proof or accepted no-test rationale, diagnosis status, verification, and every criterion all hold. -9. If anything fails or is unclear, reject the attempt and state whether `debug` must reset back to diagnosis. -10. Return the implementation review report in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Review Report - -**Status**: - -**Criteria Results** - -- : - - Evidence: - -**Diagnosis Status** - -- - - Evidence: - -**Verification Status** - -- Regression-test-first requirement: - - Evidence: -- Failing result before fix and passing result after fix: - - Evidence: -- Chosen fix hypothesis respected: - - Evidence: -- Verification sufficient for bug behaviour: - - Evidence: - - - -**Findings** - -- [] - - Location: - - Issue: - - Impact: - - Evidence: - - Fix: - - - -**Reset Guidance** - -- Reset to diagnosis: - - Reason: -``` - -## Rules - -These rules are MANDATORY. - -- NEVER approve from the worker report alone; review `debug.md`, real code, tests, current diff, and check output. -- NEVER make code changes; review only. -- ENSURE every review criterion is evaluated as `met`, `not met`, or `unclear`, with evidence. -- RETURN exactly one `Status:` line with either `approved` or `rejected`. -- Status CAN be `approved` only when every criterion is `met`, diagnosis still holds, verification is met, and there are no blocking findings. -- Status MUST be `rejected` if any criterion, diagnosis, or verification item is `not met` or `unclear`. -- TREAT `critical`, `high`, `medium`, and `low` findings as blocking. -- TREAT `nitpick` findings as non-blocking only when every criterion, diagnosis, and verification item is met and no blocking findings exist. -- INCLUDE at least one actionable finding when using `rejected`. -- ORDER findings by severity, highest first, with `nitpick` findings last. -- If rejected, say whether the result should reset back to diagnosis. -- If diagnosis, hypothesis fit, or verification is unclear or contradicted, use evidence-backed `Diagnosis Status`, `Verification Status`, and `Reset Guidance` to preserve the debug control-loop decision. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Current `debug.md` reviewed in full. -- [ ] Worker implementation report reviewed as context, not proof. -- [ ] Real implementation inspected in the repo, including relevant code, tests, current diff, and check output. -- [ ] Every review criterion evaluated with evidence. -- [ ] Diagnosis status and verification status evaluated with evidence. -- [ ] Findings categorised with the required severity rules. -- [ ] Reset guidance provided when diagnosis, hypothesis fit, or verification is unclear or contradicted. -- [ ] Approval decision set to `approved` or `rejected` according to criteria, diagnosis, verification, and finding severity rules. -- [ ] Output implementation review report in the exact format specified. -```` diff --git a/skills/debug/references/bug-worker-prompt.md b/skills/debug/references/bug-worker-prompt.md deleted file mode 100644 index 627fe2a..0000000 --- a/skills/debug/references/bug-worker-prompt.md +++ /dev/null @@ -1,72 +0,0 @@ -# Bug Worker Prompt Template - -Use this template when starting a fresh bug-worker subagent for one bug-fix loop in `debug`. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -Implement exactly one diagnosis-gated bug-fix attempt under the `debug` skill. - -## Bug Context - -- **Debug artifact**: `` -- **Chosen fix hypothesis**: `` -- **Fix constraints**: `` - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review context; ask if the diagnosis gate, chosen hypothesis, fix constraints, or repo state is unclear. -2. Verify `debug.md` has: exact symptom, reduced repro or flaky classification, full error reading, recent-change conclusion, working example or explicit N/A, boundary tracing, first bad boundary/divergence, fix constraints, chosen fix hypothesis, falsifier, and prior-loop reset evidence if any. -3. If the gate is incomplete, contradicted, or not tied to the hypothesis, STOP and report `Status: blocked` or `Status: unclear`; do not edit production code. -4. Load the `tdd` skill NOW and follow it before any production-code change. -5. Add/update the smallest valuable regression test first and verify the expected failure. If `tdd` declares no valuable test, record the rationale plus strongest fallback verification in `debug.md` before fixing. -6. Implement one minimal fix for the chosen hypothesis within constraints. -7. Re-run regression proof and relevant checks. -8. Update `debug.md` with gate verification, regression-first evidence or no-test rationale, fix attempt, verification, and contradictions. -9. Return an implementation report in the exact format defined below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Report - -**Status**: - -**What Changed**: - -- - -**Checks Run**: - -- : -- : - -**Files Changed**: - -- - -**Diagnosis Status**: - -- - - Evidence: -``` - -## Rules - -These rules are MANDATORY. - -- MUST return exactly one `Status:` field with `done`, `blocked`, or `unclear`. -- ALWAYS load and follow the `tdd` skill. -- ALWAYS check for relevant non-Propulsion skills and load them IMMEDIATELY. -- Propulsion skills and workflow MUST take precedence over any conflicting non-Propulsion skill UNLESS the user instructions state otherwise. -- NO PRODUCTION CODE before a failing regression test unless `tdd` declares no valuable test and `debug.md` records rationale plus fallback verification. -- Only bug-worker subagents make permanent code changes; debug controller diagnostic edits must be recorded and reverted before fix handoff. -- Work only on the chosen fix hypothesis for this loop; do not broaden or replace it. -- Make one minimal fix attempt only; do not stack speculative fixes. -- If evidence contradicts the diagnosis or chosen hypothesis, STOP, update `debug.md`, and reset back to diagnosis. -- Follow the output format EXACTLY as defined above. -```` diff --git a/skills/debug/references/debug-template.md b/skills/debug/references/debug-template.md deleted file mode 100644 index baff84e..0000000 --- a/skills/debug/references/debug-template.md +++ /dev/null @@ -1,145 +0,0 @@ -# Debug Template - -Create or resume one living `docs/propulsion/{yyyymmdd}-{bug-slug}/debug.md` dossier. Keep it concise, evidence-backed, and append-only for failed hypotheses, resets, diagnostic edits, and fix loops. - -```md -# Debug Note: - -## Intake - -- Source/time: `` -- Original report: `` -- Exact symptom: `` -- Expected behaviour: `` -- Actual behaviour: `` -- Impact: `` -- Environment: `` -- Questions answered: `` -- Open blockers: `` - -## Targeted Exploration - -- Areas inspected: `` -- Relevant tests/commands/logs: `` -- Ownership/prior context: `` -- Likely seams: `` -- Exploration limits: `` - -## Reproduction / No-Repro - -- Status: `` -- Exact command/path: `` -- Expected vs actual: `` -- Full output: `` -- Reduced repro: `` -- No-repro/blocking rationale: `` - -## Full Error Reading - -- Complete error: `` -- First meaningful frame/signal: `` -- Surrounding context: `` -- Conclusion: `` - -## Environment And Recent Changes - -- Revision/build: `` -- Runtime/config/data: `` -- Worktree/staged diff: `` -- Recent delta: `` -- Change conclusion: `` - -## Reduction And Comparison - -- Smallest failing case: `` -- Variables removed/controlled: `` -- Working example: `` -- Broken vs working diff: `` -- First observed divergence: `` - -## Boundary Tracing - -- Boundary map: `` -- Handoff observations: `` -- Config/data/state propagation: `` -- First bad boundary: `` - -## Diagnostic Edits - -- Temporary edits: `` -- Revert status: `` -- Outcome: `` - -## Evidence - -- E1. `` -- E2. `` - -## Hypotheses And Experiments - -- H1. `` - - Evidence for: `` - - Strongest alternative: `` - - Experiment: `` - - Expected result: `` - - Actual result: `` - - Falsifier: `` - - Conclusion: `` -- H2. `` - -## Diagnosis Gate - -- First bad state/divergence: `` -- Root cause: ` caused because ` -- Falsifier: `` -- Fix constraints: `` -- Gate status: `` - -## Regression Test - -- Test location: `` -- Behaviour under test: `` -- Failing proof before fix: `` -- Passing proof after fix: `` - -## Fix Attempts - -- Attempt 1: `` - - Files changed: `` - - Verification: `` - - Review result: `` - - Outcome: `` -- Attempt 2: `` - -## Verification - -- Targeted checks: `` -- Wider regression checks: `` -- Remaining unexplained evidence: `` - -## Reassessment - -- Trigger: `` -- Failed loop summary: `` -- Architecture/pattern reassessment: `` -- Next direction/escalation: `` - -## Closure - -- Final status: `` -- Resolution: `` -- Closure evidence: `` -- Follow-ups: `` -``` - -## Rules - -- `debug.md` is the single audit trail from intake through closure. -- Reproduce before theorising; read the full error before summarising; reduce before widening search. -- If expected behaviour, reproduction, or environment is unknowable, record the blocker and do not dispatch a fix. -- Ground the diagnosis gate before any production-code change or fix dispatch. -- Use one hypothesis, one experiment, and one fix at a time; record expected experiment results before running them. -- Use the same sections for flaky, no-repro, regression-window, performance, environment/config, data-dependent, concurrency, and multi-component evidence. -- Record diagnostic edits with file, purpose, marker when relevant, observation, and revert status; revert them before fix handoff. -- Preserve failed hypotheses, contradicted evidence, rejected reviews, reset reasons, failed fix loops, and escalations. -- After 3 failed fix loops, reassess architecture and patterns before escalating. diff --git a/skills/debug/references/investigation-loop.md b/skills/debug/references/investigation-loop.md deleted file mode 100644 index 0a0b2a9..0000000 --- a/skills/debug/references/investigation-loop.md +++ /dev/null @@ -1,84 +0,0 @@ -# Investigation Loop - -Use this loop to keep `debug.md` evidence-first and block fixes before root cause is grounded. - -## Loop - -1. Capture the feedback signal. - -- Record the exact symptom: failing command, assertion, crash, wrong output, visible behaviour, alert, metric. -- Record expected versus actual behaviour and the user impact. -- Freeze relevant environment facts: revision, runtime, platform, flags, config, inputs, time/locale, dataset, tenant, CI/prod scope. - -2. Reproduce or block. - -- Reproduce before theorising using one command, script, URL, or manual path. -- If it will not reproduce, record no-repro attempts, environment gaps, and the next needed signal before blocking or asking. -- For flaky failures, prove pass/fail variation, capture run counts, freeze seed/time/order where possible, and record changing factors. - -3. Read the failure fully. - -- Read the complete error, stack, warning, assertion, logs, exit code, and first meaningful frame before summarising. -- Separate what the output proves from what it merely suggests. - -4. Scan recent changes. - -- Check working tree diff, staged diff, recent commits, dependencies, config, environment, CI, runtime drift, release delta before broad code reading. -- If a good/bad window exists, record the smallest credible window and isolate it before guessing. - -5. Reduce the case. - -- Remove fixtures, services, flags, data, timing, and setup while preserving the same symptom. -- If the symptom changes, record that the problem changed and reset the reduction. -- For performance/resource failures, reduce to the threshold and boundary where cost first diverges from a good baseline. -- For data-dependent failures, shrink to the smallest input, fixture, stored state, or tenant dataset that still fails. - -6. Compare with working evidence. - -- Compare against a passing test, adjacent feature, prior release, reference implementation, known-good trace, good environment. -- For environment/config failures, compare runtime, flags, env, and config propagation at each boundary. -- Record the first meaningful broken-versus-working difference. - -7. Isolate the first bad boundary. - -- Trace ingress, egress, config propagation, data, state, and timing at each component handoff. -- For concurrency/order bugs, serialise when possible, use logpoints/watchpoints, and capture the first ordering change that turns good into bad. -- For multi-component failures, inspect each handoff until the earliest bad boundary is visible. - -8. Hypothesize one cause. - -- Keep one current best hypothesis plus the strongest alternative and unexplained evidence. -- Define the falsifier and one discriminating experiment before running it. -- Prefer logs, traces, dumps, breakpoints, logpoints, watchpoints, and debugger inspection before mutating code. - -9. Experiment once. - -- Run one experiment at a time and record expected result, actual result, and conclusion. -- Temporary diagnostic edits are allowed only for investigation; record file, purpose, tag/comment marker when relevant, observation, revert status in `debug.md`. -- Revert temporary diagnostic edits before fix handoff. - -10. Diagnose and gate the fix. - -- Ground the diagnosis only when evidence explains the earliest bad state or divergence, not just late symptoms. -- Record root cause, falsifier, fix constraints, and one chosen fix hypothesis. -- Dispatch one fix at a time; if evidence no longer fits, reset diagnosis instead of pushing through. - -11. Reset or escalate. - -- If verification, review, or new evidence contradicts the model, return to the earliest loop step affected and record the reset reason. -- After 3 failed fix loops, reassess architecture and patterns before escalating to the user. -- Escalate with reproduced facts, failed hypotheses, experiments, fix attempts, reassessment, and the exact decision or access needed. - -## Rules - -- No permanent production-code changes in the controller before a grounded diagnosis. -- Reproduce before theorising. -- Read full errors before summarising. -- Scan changes and reduce before widening search. -- Isolate before fixing. -- Use one hypothesis, one experiment, and one fix at a time. -- Record expected experiment results before running experiments. -- Record, tag where relevant, and revert temporary diagnostic edits before fix handoff. -- Treat flaky, regression-window, performance, environment/config, data-dependent, concurrency, and multi-component cases as evidence patterns, not shortcuts to a fix. -- Reset when evidence breaks the current model. -- Reassess architecture and patterns after 3 failed fix loops before user escalation. diff --git a/skills/discover-project/SKILL.md b/skills/discover-project/SKILL.md deleted file mode 100644 index be96a8b..0000000 --- a/skills/discover-project/SKILL.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -name: discover-project -description: Create root project briefs for greenfield products and system blueprints. Use when starting project discovery, positioning, competitor research, or full project definition. ---- - -# Discover Project - -Turn a rough software idea into an approved root `project-brief.md` for later Propulsion PRDs. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- If an approved target-root `project-brief.md` already exists, STOP. Ask which feature should enter `brainstorm`. -- If current external evidence is required and browsing is unavailable, STOP. Ask the user to enable browsing or provide sources. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Resolve the target project root; default to the current workspace root unless the user names another path. -2. Load `interrogate` and close every discovery decision using [references/discovery-checklist.md](references/discovery-checklist.md). -3. Gather problem, users, business model, explicit user-chosen stack, features, MVP boundary, risks, and success metrics. -4. Research competitors, alternatives, market, and positioning claims when they need current evidence. -5. Write `/project-brief.md` from [references/project-brief-template.md](references/project-brief-template.md). -6. Sanity-check the brief against the conversation, research, and repo context. Remove contradictions, placeholders, and unanswered questions. -7. Start a fresh project brief reviewer subagent with [references/project-brief-reviewer-prompt.md](references/project-brief-reviewer-prompt.md). -8. Fix reviewer findings, then repeat step 7 until the latest review returns exact `Status: approved`. -9. Ask the user to review and approve `project-brief.md`. -10. After user approval, update `/project-brief.md` metadata to `Status: Approved` and set `Last reviewed` to the approval date. - -## Rules - -These rules are MANDATORY. - -- ALWAYS use `interrogate` before writing the brief. -- MUST keep asking until there are no open questions in the approved brief. -- MUST separate sourced evidence from inference and include research dates and confidence. -- MUST use current web evidence for competitor, market, positioning, or similar external claims. -- MUST include monetisation or business model, with explicit `N/A` allowed. -- MUST record explicit user-chosen architecture, language, framework, storage, deployment, and integrations. -- MUST include a full feature inventory grouped by product area with MVP, later, and suggested PRD slices. -- USE `Status: approved` as the ONLY valid project brief reviewer approval signal. -- MUST block user approval and repeat review when reviewer status is rejected, missing, or unclear. -- DO NOT decide detailed UI style beyond minimal platform or UI-presence context; defer UI style to feature PRDs. -- DO NOT write `plan.md`; discovery output is root `project-brief.md` only. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Target project root is resolved. -- [ ] Interrogation closed every discovery question. -- [ ] Current evidence supports all competitor, market, and positioning claims. -- [ ] Root `project-brief.md` is written and cross-checked. -- [ ] Project brief reviewer returned exact `Status: approved`. -- [ ] User explicitly approved `project-brief.md`. -- [ ] Approved `project-brief.md` metadata was written with `Status: Approved` and `Last reviewed` set to the approval date. - -## Next Steps - -Once the completion gate is fully checked: - -- STOP after approved metadata is written. Do not enter `brainstorm` until the user chooses a feature for PRD work. - -## References - -Use these references when you need detail. - -- [references/discovery-checklist.md](references/discovery-checklist.md) - Required discovery decision tree. -- [references/project-brief-template.md](references/project-brief-template.md) - Root project brief structure. -- [references/project-brief-reviewer-prompt.md](references/project-brief-reviewer-prompt.md) - Project brief reviewer subagent prompt. diff --git a/skills/discover-project/references/discovery-checklist.md b/skills/discover-project/references/discovery-checklist.md deleted file mode 100644 index 7ea6529..0000000 --- a/skills/discover-project/references/discovery-checklist.md +++ /dev/null @@ -1,55 +0,0 @@ -# Discovery Checklist - -Use this checklist with `interrogate`. Close every branch before approving `project-brief.md`; do not leave open questions in the final brief. - -## Project Identity - -- Project name, one-sentence concept, target project root, and intended first operating context. -- Product category or market frame the user wants the project to occupy. -- Non-goals that prevent the project from becoming a generic platform. - -## Problem And Users - -- Primary user segments and the job each segment needs done. -- Current pain, workaround, substitute tool, or manual process. -- Trigger moments, frequency of use, and consequences of failure. -- Desired user outcome and desired business or owner outcome. - -## Evidence And Landscape - -- Evidence for the problem: user context, interviews, observations, market signals, or repo facts. -- Direct competitors, substitute products, and DIY/manual alternatives. -- Current external sources for competitor, market, positioning, or similar claims. -- Confidence labels for evidence and clear separation between facts and inference. - -## Positioning - -- Unique attributes the product can credibly claim. -- Value themes linked to the best-fit segment. -- Market frame of reference. -- USP in this form: For ``, `` is the `` that ``, unlike `
`. - -## Business Model - -- Monetisation, funding, or ownership model. -- Pricing, plan shape, license, or explicit `N/A`. -- Primary success metrics and how they will be measured. - -## Technical Blueprint - -- User-chosen architecture and stack; do not pick the stack for the user. -- Language, framework, storage, deployment target, and key integrations. -- Data ownership, privacy, compliance, monitoring, and portability constraints. -- Non-functional requirements across performance, reliability, security, usability, scalability, maintainability, compatibility, portability, compliance, and monitoring. - -## Feature Inventory - -- Product areas and all known features. -- MVP versus later classification for each feature. -- Suggested future PRD slices that can enter `brainstorm`. -- Out-of-scope items and risks that affect project direction. - -## UI Boundary - -- Capture only platform and whether the product has a UI. -- Defer detailed visual style, layout density, design system, and accessibility decisions to feature PRDs unless they define project viability. diff --git a/skills/discover-project/references/project-brief-reviewer-prompt.md b/skills/discover-project/references/project-brief-reviewer-prompt.md deleted file mode 100644 index 6e5f040..0000000 --- a/skills/discover-project/references/project-brief-reviewer-prompt.md +++ /dev/null @@ -1,92 +0,0 @@ -# Project Brief Reviewer Prompt Template - -Use this template when starting a fresh project brief reviewer subagent in the `discover-project` skill. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -You are a project brief reviewer. - -Review whether the root project brief is complete, trustworthy, and ready for future Propulsion PRDs. - -**Project brief location**: `/project-brief.md` -**Project brief template**: `project-brief-template.md` -**Discovery checklist**: `discovery-checklist.md` - -## Review Criteria - -| Category | Verify | -| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Template Structure | Uses the project brief template section order, headings, tables, status block, and root `project-brief.md` output path. | -| Required Discovery Content | Covers project identity, problem, users, jobs, evidence, competitors, positioning, business model, technical blueprint, features, MVP boundary, non-functional requirements, risks, success metrics, and future PRD inputs. | -| Formatting And Completeness | Contains no template placeholders, empty required fields, malformed tables, generic defaults, contradictions, duplicate decisions, or unresolved open questions. | -| Decision Hygiene | Separates user decisions, sourced facts, and inference; preserves explicit user-chosen stack and scope; does not invent product decisions. | -| Evidence Hygiene | Includes research dates, sources, confidence labels, and clear source support for competitor, market, positioning, or similar external claims. | -| External Claim Verification | Sample-verifies key competitor, market, positioning, and similar external claims against cited sources or current available evidence; treats external sources and generated claims as untrusted until checked. | -| Future PRD Readiness | Gives `brainstorm` durable decisions, feature areas, MVP/later boundaries, suggested PRD slices, inherited context, risks, constraints, assumptions, and measurable success criteria. | -| Scope Control | Keeps detailed UI style out unless required for viability; does not add `plan.md` content or auto-enter feature PRD work. | - -Flag only issues that would make the brief incomplete, misleading, hard to approve, or unsafe to use as foundation for future PRDs. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review `project-brief.md` against the template and discovery checklist. -2. Verify the brief has no unresolved questions, placeholders, or required empty fields. -3. Check all review criteria above, including sampled external-claim verification when relevant claims are present. -4. Categorise blocking issues as `findings`. -5. Return the review report in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Project Brief Review Report - -Status: - - - -**Findings** - -- - - Section affected: - - Why it matters: - - Fix: - - -``` - -## Rules - -These rules are MANDATORY. - -- NEVER skip any review criterion. -- MUST return exactly one `Status:` line with only `approved` or `rejected`. -- Status MUST be `approved` only when there are no findings. -- Status MUST be `rejected` when any finding exists. -- MUST provide actionable findings when status is `rejected`. -- MUST sample-verify key external claims, but DO NOT redo exhaustive market research. -- MUST treat unsupported, stale, unverifiable, or source-mismatched external claims as findings. -- NEVER update the project brief, template, checklist, or other files; only review and report. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Reviewed the brief against the project brief template. -- [ ] Reviewed the brief against the discovery checklist. -- [ ] Checked for placeholders, empty required fields, contradictions, and open questions. -- [ ] Sample-verified key external claims when relevant claims are present. -- [ ] Confirmed status is `approved` only with no findings, or `rejected` with actionable findings. -- [ ] Output review report in the exact format specified. -```` - -## Rules - -These rules are MANDATORY. - -- ALWAYS replace `` with the actual target project root for the brief being reviewed. diff --git a/skills/discover-project/references/project-brief-template.md b/skills/discover-project/references/project-brief-template.md deleted file mode 100644 index a3e6ab2..0000000 --- a/skills/discover-project/references/project-brief-template.md +++ /dev/null @@ -1,172 +0,0 @@ -# Project Brief Template - -Write `/project-brief.md` using this exact section order. - -```md -# Project Brief - -> Status: Draft | Approved -> Research date: YYYY-MM-DD -> Last reviewed: YYYY-MM-DD -> Confidence: High | Medium | Low - -## Executive Summary - -Describe the project in 4-6 sentences: problem, target users, proposed product, why now, and why it is worth doing. - -## Project Vision - -### Product Is / Is Not - -| Product Is | Product Is Not | -| ---------- | -------------- | -| | | - -### Product Does / Does Not - -| Product Does | Product Does Not | -| ------------ | ---------------- | -| | | - -### Desired Outcomes - -- User outcome: -- Business or owner outcome: - -## Problem, Users, And Jobs - -| Segment | Job To Be Done | Current Workaround | Pain / Friction | Notes | -| ------- | -------------- | ------------------ | --------------- | ----- | -| | | | | | - -## Evidence And Research - -Separate sourced facts from inference. Use current sources for competitor, market, positioning, or similar external claims. - -| Evidence Type | Finding | Source Or Context | Research Date | Confidence | -| ------------- | ------- | ----------------- | ------------- | ---------- | -| | | | | | - -## Alternatives And Competitors - -Include direct competitors, substitute tools, and DIY/manual alternatives. - -| Type | Name | Target User | Core Promise | Strengths | Weaknesses / Gaps | Evidence | -| ------------ | ---- | ----------- | ------------ | --------- | ----------------- | -------- | -| Direct | | | | | | | -| Substitute | | | | | | | -| DIY / Manual | | | | | | | - -## Differentiation And Positioning - -### Unique Attributes - -- Attribute - -### Value Themes - -- Value theme - -### Best-Fit Segment - -State which users should care most and why. - -### Market Frame Of Reference - -State the category or market frame that makes the value obvious. - -### USP - -For ``, `` is the `` that ``, unlike `
`. - -## Monetisation And Business Model - -State the monetisation, funding, ownership, license, or explicit `N/A`. - -| Item | Decision | -| ----------------------- | -------- | -| Model | | -| Pricing / License | | -| Revenue Or Value Metric | | - -## Technical Blueprint - -Record explicit user-chosen technical decisions. Do not leave stack choices undecided. - -| Area | Decision | Rationale Or Constraint | -| ------------------ | -------- | ----------------------- | -| Architecture | | | -| Language / Runtime | | | -| Frameworks | | | -| Storage | | | -| Deployment | | | -| Integrations | | | - -## Feature Inventory - -| Product Area | Feature | User Outcome | MVP / Later | Suggested PRD Slice | -| ------------ | ------- | ------------ | ----------- | ------------------- | -| | | | | | - -## Recommended MVP Boundary - -### In Scope - -- Item - -### Out Of Scope - -- Item - -### Suggested First PRD Slices - -1. Slice -2. Slice -3. Slice - -## Non-Functional Requirements - -Use these categories: Performance, Reliability, Security, Usability, Scalability, Maintainability, Compatibility, Portability, Compliance, Monitoring. - -| ID | Category | Requirement | -| ------- | ----------- | ----------- | -| NFR-001 | Performance | | - -## Risks, Constraints, And Assumptions - -| Type | Item | Impact | Mitigation Or Decision | -| ---------- | ---- | ------ | ---------------------- | -| Risk | | | | -| Constraint | | | | -| Assumption | | | | - -## Resolved Discovery Decisions - -- Decision: - -## Success Metrics - -| Metric | Baseline | Target | Measurement Approach | -| ------ | -------- | ------ | -------------------- | -| | | | | - -## Inputs For Future Propulsion PRDs - -- Durable decisions that `brainstorm` must preserve: -- Feature areas ready for PRD work: -- Context each PRD should inherit: - -## Sources - -- Source name - URL or citation - what it supports - access date -``` - -## Rules - -These rules are MANDATORY. - -- MUST write the brief at the target project root as `project-brief.md`. -- MUST NOT include an open questions section. -- MUST mark the brief `Approved` only after explicit user approval. -- MUST use current evidence for competitor, market, positioning, or similar external claims. -- MUST keep detailed UI style decisions out of the brief unless they define project viability. diff --git a/skills/execute/SKILL.md b/skills/execute/SKILL.md deleted file mode 100644 index 6396013..0000000 --- a/skills/execute/SKILL.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: execute -description: Execute a feature plan through subagent implementation and review one phase at a time. Use when current `plan.md` exists and the user wants feature implementation to start. ---- - -# Execute - -Execute a feature plan one phase at a time. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- If no `docs/propulsion/.../plan.md` exists for this work, STOP. Load `plan`. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review and select the first incomplete phase in `plan.md`. -2. Start a fresh worker subagent with [references/worker-prompt.md](references/worker-prompt.md). -3. Wait for the worker to finish and handle the status: - - If `Status: unclear`, provide additional context or clarification. - - If `Status: blocked`, triage the blocker and resolve it. - - If you cannot resolve `unclear` or `blocked` from the plan, codebase, or tools, escalate to the user. - - If `Status: done`, continue to review. -4. Start a fresh reviewer subagent with [references/reviewer-prompt.md](references/reviewer-prompt.md). -5. Wait for the reviewer to finish and handle the status: - - If `Status: approved`, mark the current phase complete in `plan.md`. - - If `Status: rejected`, send the findings back to the same worker subagent with the prompt in [references/worker-feedback-prompt.md](references/worker-feedback-prompt.md). -6. Repeat steps 3-5 until the worker reports `Status: done` and the latest reviewer reports `Status: approved`. -7. Repeat steps 1-6 for each incomplete phase in `plan.md`. -8. Infer and run repo-wide checks, such as tests and linters. -9. Inform the user that implementation is complete. -10. Ask whether the user has feedback on the implementation. - -## Rules - -These rules are MANDATORY. - -- NEVER implement a phase without a worker subagent. -- ALWAYS use a fresh reviewer subagent for every review. -- NEVER resolve `Status: unclear` or `Status: blocked` by guessing; if the answer is not in the plan, codebase, or tools, escalate to the user. -- ALWAYS update `plan.md` checkboxes after each successful implementation-review cycle. -- MUST infer and run relevant repo-wide checks before claiming completion. -- NEVER implement user feedback directly in `execute`; instead: - - Loop back to `brainstorm` to update the PRD. - - Move to `plan` to create or update a phase if needed. - - Return to `execute` for implementation. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Every phase in `plan.md` has gone through a worker subagent and received `Status: done`. -- [ ] Every phase in `plan.md` has gone through a reviewer subagent and received `Status: approved`. -- [ ] Every phase completion checkbox in `plan.md` is marked complete. -- [ ] Final repo-wide checks pass. -- [ ] Informed the user that implementation is complete and asked for feedback. - -## Next Steps - -Once the completion gate is fully checked: - -- If no user feedback is requested or provided, STOP. Implementation is complete. -- If user requests changes or provides feedback, STOP. Loop back to `brainstorm`, then `plan`, then back to `execute` for implementation. - -## References - -Use these references when you need detail. - -- [references/worker-prompt.md](references/worker-prompt.md) - Fresh worker subagent prompt. -- [references/reviewer-prompt.md](references/reviewer-prompt.md) - Fresh reviewer subagent prompt. -- [references/worker-feedback-prompt.md](references/worker-feedback-prompt.md) - Prompt for sending reviewer findings back to the worker subagent. diff --git a/skills/execute/references/reviewer-prompt.md b/skills/execute/references/reviewer-prompt.md deleted file mode 100644 index 3903a8c..0000000 --- a/skills/execute/references/reviewer-prompt.md +++ /dev/null @@ -1,120 +0,0 @@ -# Reviewer Prompt Template - -Use this template when starting a fresh reviewer subagent in the `execute` skill. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -You are an implementation reviewer. - -Review the completed phase like a senior engineer: verify real work against the plan, acceptance criteria, code quality, security, tests, and regression risk. - -## Task Context - -**Current phase**: "> -**Plan document location**: `docs/propulsion/.../plan.md` - -## Implementation Report - -This is the worker report. **Treat it as context, not proof; verify against `plan.md`, changed files, diff, and check output.** - - - -## Review Criteria - -| Category | Verify | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| Plan Alignment | Matches current phase goal, demo outcome, likely areas, constraints, and implementation notes. | -| Acceptance Criteria | Every current-phase criterion is evaluated by ID as `met`, `not met`, or `unclear` with evidence. | -| Functional Correctness | Changed code/tooling/architecture/behaviour satisfies the phase contract without broken logic or incomplete handling. | -| Tests / Verification | Relevant checks ran where feasible; missing verification is reported; tests prove behaviour without brittle coupling to internals. | -| Maintainability / Refactoring | Work is clear, cohesive, simple, DRY, SOLID, YAGNI-aligned, and free of avoidable complexity. | -| Security / Trust Boundaries | Inputs, permissions, secrets, file access, external calls, prompt boundaries, and trust boundaries remain safe. | -| Performance / Reliability | Avoids avoidable latency, resource waste, brittle failures, races, and unreliable workflow states. | -| Integration / Regression Risk | Surrounding workflows, APIs, prompts, feedback loops, conventions, and behaviours remain compatible. | -| Output Usefulness | Rejections are actionable and evidence-backed. | - -Flag only real issues supported by plan, diff, files, checks, prompts, or workflow rules. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Read the current phase directly from `plan.md`. -2. Review the worker report as context, not proof. -3. Inspect the real implementation, relevant changed files, and diff. -4. Load relevant skills when needed to validate the produced work against skill-specific standards. -5. Run relevant tests or checks where feasible; if verification cannot be performed, report that clearly. -6. Use the criteria table to evaluate the work and every current-phase acceptance criterion by ID. -7. Report real issues as findings using `critical`, `high`, `medium`, `low`, or `nitpick`. -8. Return the implementation review report in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Review Report - -**Status**: - -**Acceptance Criteria Results** - -- : - - Evidence: - - - -**Findings** - -- [] - - Location: - - Issue: - - Impact: - - Evidence: - - Fix: - - -``` - -## Rules - -These rules are MANDATORY. - -- NEVER approve from the worker report alone; review the actual implementation, relevant changed files, and current diff. -- VERIFY the current phase directly from `plan.md` before assessing the work. -- ENSURE every current-phase acceptance criterion is evaluated by ID as `met`, `not met`, or `unclear`, with evidence. -- RETURN exactly one `Status:` line with either `approved` or `rejected`. -- Status CAN be `approved` only when every acceptance criterion is `met` and there are no blocking findings. -- Status MUST be `rejected` if any acceptance criterion is `not met` or `unclear`. -- TREAT `critical`, `high`, `medium`, and `low` findings as blocking. -- TREAT `nitpick` findings as non-blocking when all acceptance criteria are met and no blocking findings exist. -- DO NOT approve tests that assert implementation details in a way that would fail under behaviour-preserving refactors. -- INCLUDE at least one actionable finding when using `rejected`. -- ORDER findings by severity, highest first, with `nitpick` findings last. -- ENSURE findings are evidence-based, actionable, and specific enough to verify or challenge. -- NEVER make code changes; review only. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Current phase details reviewed directly from `plan.md`. -- [ ] Worker implementation report reviewed as context, not proof. -- [ ] Real implementation inspected in the repo, including relevant files and current diff. -- [ ] Relevant skills loaded when needed for validation. -- [ ] Relevant tests ran and checked. -- [ ] Every current-phase acceptance criterion evaluated by ID with evidence. -- [ ] Findings categorised with the required severity rules. -- [ ] Approval decision set to `approved` or `rejected` according to acceptance criteria and finding severity rules. -- [ ] Output implementation review report in the exact format specified. -```` - -## Rules - -These rules are MANDATORY. - -- MUST copy and paste the correct phase number and title from the plan. -- ALWAYS replace the plan path with the actual path for the plan being reviewed. -- ALWAYS paste the full worker implementation report into `Implementation Report` before dispatching the reviewer. diff --git a/skills/execute/references/worker-feedback-prompt.md b/skills/execute/references/worker-feedback-prompt.md deleted file mode 100644 index 3b497dc..0000000 --- a/skills/execute/references/worker-feedback-prompt.md +++ /dev/null @@ -1,102 +0,0 @@ -# Worker Feedback Prompt Template - -Use this template when returning review findings to the active worker subagent in the `execute` skill. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -Your work has been reviewed. Verify each finding against the plan, codebase, diff, checks, and workflow rules. Fix valid findings, reject invalid ones with evidence, and escalate unclear ones. - -## Review Report - - - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review the current phase details directly from `plan.md`. -2. Review the full implementation review report. -3. Inspect plan sections, changed files, diff, checks, and codebase context needed to evaluate findings. -4. Triage every review finding as `valid`, `invalid`, or `unclear` before making any code change. -5. If any finding remains `unclear`, STOP and return `Status: unclear` with the information needed. -6. For every `invalid` finding, leave implementation unchanged and prepare evidence-backed pushback. -7. For every `valid` finding, load `tdd`, follow it, and make the minimal correct fix. -8. Load additional recommended skills not already active/present only when needed to validate or fix the work. -9. Verify the implementation works and conforms to the current phase in `plan.md`. -10. Re-evaluate every current-phase acceptance criterion by ID. -11. Return your implementation report in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Report - -**Status**: - -**Review Feedback Triage**: - -- - - Classification: - - Resolution: - - Evidence: - -**What Changed**: - -- - -**Checks Run**: - -- : -- : - -**Files Changed**: - -- - -**Acceptance Criteria Status**: - -- : - - Evidence: -``` - -## Rules - -These rules are MANDATORY. - -- NEVER treat reviewer findings as automatically correct; verify each finding against the real implementation. -- ALWAYS triage every review finding as `valid`, `invalid`, or `unclear` before changing code. -- Status MUST be `unclear` if any finding cannot be triaged after inspecting the plan, codebase, diff, checks, and available evidence. -- Status MUST be `blocked` if a valid finding cannot be fixed because of missing access, failing tooling, contradictory requirements, or another blocker. -- Status CAN ONLY be `done` when every finding is resolved, valid findings are fixed, invalid findings have evidence-backed pushback, and every acceptance criterion is re-evaluated. -- DO NOT change code for invalid findings. -- DO NOT make speculative changes beyond the current phase or review findings. -- ALWAYS use the `tdd` skill to fix valid findings, loading it only when it is not already active or present in context. -- MUST verify implementation against the plan before claiming `Status: done`. -- ENSURE pushback is technical, evidence-based, and specific enough for the reviewer to verify or challenge. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Current phase details reviewed directly from `plan.md`. -- [ ] Full implementation review report reviewed. -- [ ] Relevant plan sections, changed files, current diff, checks, and codebase context inspected. -- [ ] Every review finding triaged as `valid`, `invalid`, or `unclear` before coding. -- [ ] Every `valid` finding fixed using the `tdd` skill. -- [ ] Every `invalid` finding answered with evidence-backed pushback. -- [ ] Any unresolved `unclear` finding surfaced through `Status: unclear`. -- [ ] Any unresolved implementation blocker surfaced through `Status: blocked`. -- [ ] Relevant verification checks rerun after changes where feasible. -- [ ] Every current-phase acceptance criterion re-evaluated by ID with evidence. -- [ ] Output implementation report in the exact format specified. -```` - -## Rules - -These rules are MANDATORY. - -- ALWAYS paste the full review report into `Review Report` before dispatching the worker. diff --git a/skills/execute/references/worker-prompt.md b/skills/execute/references/worker-prompt.md deleted file mode 100644 index 06c26b6..0000000 --- a/skills/execute/references/worker-prompt.md +++ /dev/null @@ -1,83 +0,0 @@ -# Worker Prompt Template - -Use this template when starting a fresh worker subagent in the `execute` skill. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -Implement the current phase defined below. - -## Task Context - -**Current phase**: "> -**Plan document location**: `docs/propulsion/.../plan.md` - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review current phase details in `plan.md`. -2. Load any recommended skills for this phase immediately. -3. Gather needed context from the codebase, PRD, and tools. -4. Ask any clarifying questions if the requirements, scope, or repo state are unclear. -5. Load the `tdd` skill and follow it to implement the requirements. -6. Verify your implementation works and conforms to the plan. -7. Return your implementation report in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Implementation Report - -**Status**: - -**What Changed**: - -- - -**Checks Run**: - -- : -- : - -**Files Changed**: - -- - -**Acceptance Criteria Status**: - -- : - - Evidence: -``` - -## Rules - -These rules are MANDATORY. - -- MUST start by reviewing the current phase details in `plan.md`. -- ALWAYS load missing recommended skills and gather additional context before asking questions or implementing. -- ALWAYS ask questions if anything in the task is unclear, NEVER guess or make assumptions. -- ALWAYS load and use the `tdd` skill. -- MUST verify implementation against the plan before claiming `Status: done`. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Reviewed the current phase details in `plan.md`. -- [ ] Loaded any missing recommended skills and gathered additional context. -- [ ] Asked clarifying questions for any unclear requirements, scope, or repo state. -- [ ] Followed the `tdd` skill to implement the requirements. -- [ ] Verified implementation works and conforms to the plan. -- [ ] Output the implementation report in the exact format specified. -```` - -## Rules - -These rules are MANDATORY. - -- MUST copy and paste the correct phase number and title from the plan. -- ALWAYS replace the plan path with the actual path for the plan being implemented. diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md deleted file mode 100644 index a43a2cc..0000000 --- a/skills/init-project/SKILL.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: init-project -description: Create or prune AGENTS.md into minimal global steering for agents. Use when initializing, updating, or reducing repo-wide agent rules. ---- - -# Init Project - -Create or prune `AGENTS.md` as tiny global protocol, not a repo overview. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Launch a fresh explorer subagent before editing to inspect existing `AGENTS.md` files, package/tool configs, docs, scripts, and visible conventions. -2. Load `interrogate` to gather global, non-discoverable instructions the repository cannot reveal, including human protocol, hidden landmines, environment gotchas, and verification timing. -3. Preserve or add the default correction rule near the top of `AGENTS.md`. -4. Apply the line admission test to every candidate rule: global, non-discoverable, and operationally important. -5. Challenge weak or bloated candidates before keeping them; remove rules that fail the admission test or belong in code, config, docs, skills, or commands. -6. Draft the smallest useful `AGENTS.md`, keeping always-followed rules near the top. -7. Handoff with the changed file path plus kept, removed, and challenged rule categories. - -## Rules - -These rules are MANDATORY. - -- MUST launch a fresh explorer subagent before creating, pruning, or rewriting `AGENTS.md`. -- MUST use `interrogate` skill for human-only, repo-wide rules that repository inspection cannot discover. -- MUST keep only rules that pass all admission checks: global, non-discoverable, operationally important. -- MUST challenge or remove vague, task-specific, discoverable, duplicated, or low-impact instructions. -- MUST use this default correction rule: "- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`." -- DO NOT include tech stack summaries, folder maps, command inventories, architecture recaps, or style rules already enforced by tooling. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Fresh explorer subagent completed repository inspection before edits. -- [ ] `interrogate` skill was used for non-discoverable global rules or existing user-provided rules were explicitly classified. -- [ ] Default correction rule is present once and near the top. -- [ ] Every retained non-default line passes the admission test. -- [ ] Weak or bloated candidates were challenged or removed. -- [ ] Intended `AGENTS.md` behaviour is preserved and summarised before handoff. - -## References - -Use these references when you need detail. - -- [references/process.md](references/process.md) - End-to-end creation and pruning process for minimal `AGENTS.md` files. -- [references/examples.md](references/examples.md) - Good examples, pruning examples, and anti-patterns. diff --git a/skills/init-project/references/examples.md b/skills/init-project/references/examples.md deleted file mode 100644 index 773775e..0000000 --- a/skills/init-project/references/examples.md +++ /dev/null @@ -1,86 +0,0 @@ -# AGENTS.md Examples - -Examples of minimal protocol-style `AGENTS.md` files and pruning decisions. - -## Default Rule Only - -Use this when no repo-specific rule passes the admission test. - -```markdown -# AGENTS.md - -- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. -``` - -## Environment Gotcha - -Keep invisible environment constraints causing repeated failures. - -```markdown -# AGENTS.md - -- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. -- This repo is developed inside a Linux container mounted from macOS; run file-watching commands inside the container to avoid missed changes. -``` - -## Hidden Landmine - -Keep repo-wide operational facts hidden by code structure. - -```markdown -# AGENTS.md - -- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. -- `legacy/` appears unused but is imported dynamically in production; do not delete or bulk-move it without explicit approval. -- Never regenerate checked-in fixtures in `fixtures/prod/`; they are hand-sanitized production snapshots. -``` - -## Pruning Examples - -Remove discoverable project summaries: - -```markdown -- This project uses Bun, TypeScript, and React. -``` - -Reason: package and config files reveal the stack. - -Keep mandatory verification timing when the obligation or timing is not discoverable: - -```markdown -- After implementing changes run `bun run test` before handoff. -``` - -Reason: this defines mandatory per-change timing that scripts alone do not reveal. - -Remove command inventories: - -```markdown -- Run `bun test` for tests and `bun run lint` for linting. -``` - -Reason: scripts and CI already document commands. Keep only non-discoverable caveats, such as a cache flag required to avoid false positives. - -Challenge vague preferences: - -```markdown -- Write clean code and keep files organized. -``` - -Reason: not operationally specific. Ask for a concrete repo-wide failure mode or delete. - -Relocate task-specific workflow: - -```markdown -- For payment changes, update the billing PRD and run card network sandbox tests. -``` - -Reason: not global to every task. Move to a domain skill, command, or docs unless it truly applies to all sessions. - -## Anti-Patterns - -- Architecture overviews copied from docs or inferred from folders. -- Full setup instructions copied from README. -- Formatting or naming rules already enforced by tooling. -- Multiple paragraphs explaining why a rule exists inside `AGENTS.md`. -- Product-specific agent instructions instead of generic agent protocol. diff --git a/skills/init-project/references/process.md b/skills/init-project/references/process.md deleted file mode 100644 index 7249b91..0000000 --- a/skills/init-project/references/process.md +++ /dev/null @@ -1,83 +0,0 @@ -# Minimal AGENTS.md Process - -Use when creating, pruning, or updating `AGENTS.md` under the strict minimal-context policy. - -## 1. Inspect Before Editing - -Launch a fresh explorer subagent to read enough evidence to avoid duplicating discoverable facts: - -- Existing applicable `AGENTS.md` files, including parent or nested files. -- Package manifests, task runners, Makefiles, build files, and test configs. -- Formatter, linter, TypeScript, CI, and editor config. -- Docs describing setup, scripts, architecture, or conventions. -- Source layout and naming patterns when they answer a proposed rule. - -Do not add repository summaries. Inspection exists to identify what does not belong in `AGENTS.md`. - -## 2. Ask For Invisible Rules - -Use the existing `interrogate` skill to ask for rules the repository cannot reveal. Focus on: - -- Human protocol persisting across sessions. -- Hidden operational landmines, unsafe directories, or legacy coupling. -- Environment quirks not encoded in config. -- Repo-wide constraints not enforced by code, tests, lint, CI, or docs. -- Mandatory verification timing for every change when not encoded in scripts, docs, or CI. - -If the user gives candidate rules, classify them instead of accepting them uncritically. - -## 3. Preserve The Default Correction Rule - -Keep this rule near the top, even when it is the only surviving rule: - -```markdown -- When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. -``` - -Do not keep older variants that prescribe loading a skill or editing the file after the user answers. Replace them with the ask-only wording. - -## 4. Apply The Admission Test - -Keep non-default lines only if all checks pass: - -- Global: applies to every task or session in this repository. -- Non-discoverable: an agent cannot reliably infer it from repository files, tooling, docs, or scripts. -- Operationally important: missing it is likely to cause mistakes, wasted effort, unsafe edits, or broken workflow. - -Mandatory per-change verification timing can pass when the obligation or handoff timing is not encoded in tooling, scripts, docs, or CI. - -If any check fails, challenge the rule or remove it. - -## 5. Challenge Weak Instructions - -Push back on candidates that are: - -- Discoverable from source, config, packages, or docs. -- Task-specific workflows that belong in a skill, command, issue, or PRD. -- Style preferences enforced by formatter, linter, types, or tests. -- Generic good advice that applies to all repositories. -- Vague intent without operational consequence. -- Multi-line explanations compressible into one actionable rule. - -When challenging, explain the failed admission check and suggest a smaller replacement, better home, or deletion. - -## 6. Draft The Smallest Useful File - -Prefer a short protocol file: - -1. Put the default correction rule first or near the top. -2. Put always-followed repo-wide rules after it. -3. Group only when grouping improves scanning; avoid section filler. -4. Keep only the final accepted rules, not the rationale. -5. If nothing repo-specific qualifies, leave a one-rule file. - -## 7. Validate Before Handoff - -Before finishing, verify: - -- The default correction rule appears exactly once and is ask-only. -- Every retained non-default line passes the admission test. -- Discoverable facts are not duplicated from repository evidence. -- Always-followed rules remain near the top. -- Existing intended behaviour is preserved unless explicitly removed after challenge. -- Handoff reports kept, removed, challenged, and relocated categories. diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md deleted file mode 100644 index aab5402..0000000 --- a/skills/interrogate/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: interrogate -description: Manage interrogation, intake, interviews, scope clarification, requirements gathering, and shared understanding. Use when missing decisions must be resolved. ---- - -# Interrogate - -Reach shared understanding through project context and one-question-at-a-time user interrogation. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Launch a fresh explorer subagent to inspect project facts relevant to the request. -2. Interrogate the user about every aspect of the request until shared understanding is reached. - - Ask questions one at a time, provide your recommended answer first, then 2-3 viable alternatives. - - Walk down each branch of the decision tree resolving dependencies between decisions. - - Keep asking until shared understanding is reached. -3. Return a concise summary to the caller. - -## Rules - -These rules are MANDATORY. - -- MUST use explorer subagent for entry exploration. -- ALWAYS interrogate the user until shared understanding is reached. -- NEVER think "this is too many questions", it isn't. -- DO NOT limit the number of questions; keep asking until EVERY blocking branch is closed. -- MUST ask user exactly one question at a time, provide a recommended answer, then 2-3 viable alternatives. -- ALWAYS check if a question can be answered by project inspection before asking. -- MUST walk the decision tree until EVERY blocking branch is closed by project facts or user answers. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Fresh explorer subagent completed entry project-context inspection. -- [ ] Decision tree branches were explored and attempted to answer with code exploration. -- [ ] Remaining open branches were closed by relentlessly interrogating the user. -- [ ] Shared understanding was reached with no open blocking branches. -- [ ] Resolved decisions were summarised for the caller. - -## References - -Use these references when you need detail. - -- [references/interrogate-protocol.md](references/interrogate-protocol.md) - Detailed intake protocol, question format, and branch handling. diff --git a/skills/interrogate/references/interrogate-protocol.md b/skills/interrogate/references/interrogate-protocol.md deleted file mode 100644 index df9654b..0000000 --- a/skills/interrogate/references/interrogate-protocol.md +++ /dev/null @@ -1,54 +0,0 @@ -# Interrogate Protocol - -Use when a request needs missing information resolved before safe progress. - -## Entry Exploration - -Launch a fresh explorer subagent before asking the user anything. Inspect project context needed to avoid answerable questions, then seed the initial decision tree. - -## Decision Tree - -Build an explicit decision tree before the first user question. Include branches that could affect the answer or next action, especially: - -- intended outcome and non-goals -- user workflow, UX, API, CLI, or agent-facing behaviour -- inputs, outputs, data shape, state, persistence, and side effects -- scope boundaries, compatibility, migration, rollback, and rollout -- architecture, dependencies, integration points, and ownership -- errors, edge cases, security, privacy, and performance constraints -- tests, acceptance criteria, verification, and handoff expectations - -Track each branch as open or closed. Work the highest-impact blocker first, then update the tree after every project finding or user answer. Close a branch only when project facts or the user fully answer it. - -## Codebase-Answerable Branches - -Before asking the user, decide whether project inspection could fully answer the branch. If yes, inspect focused evidence: patterns, APIs, file locations, naming, tests, config, dependencies, shipped behaviour. - -Do not treat existing code as product intent when intent is unclear. If inspection reveals current state but not desired outcome, use it to recommend an answer, then ask. - -## User Questioning - -Relentlessly ask one question at a time. Keep each question decision-oriented and easy to answer. Keep going until shared understanding is reached; do not stop because the answer seems obvious, many questions were asked, or inspection found adjacent facts. - -```markdown -Question: - -Options: - -- (recommended) -- -- -- -``` - -Do not list more than 3 alternatives beyond the recommendation. Do not ask multi-part questions. If decisions are related, ask the prerequisite first and let the next branch depend on that answer. - -## Shared Understanding - -Walk the decision tree until no blocking branches remain. Shared understanding means the agent can state outcome, constraints, tradeoffs, and acceptance criteria without inventing product or codebase facts. - -When unsure whether a branch blocks, treat it as blocking and ask. Do not finish with silent assumptions, unresolved branches, or TODO-style follow-ups. - -## Handoff Summary - -When interrogation is complete, return a concise summary to the caller. diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md deleted file mode 100644 index caeb500..0000000 --- a/skills/plan/SKILL.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: plan -description: Create an implementation-ready feature plan from an approved PRD using phases scoped as thin vertical slices. Use when an approved `docs/propulsion/.../prd.md` exists. ---- - -# Plan - -Turn an approved PRD into a phased, vertical-slice implementation plan. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- If a `docs/propulsion/.../plan.md` already exists for this work, STOP. Ask the user whether to enter `execute`. -- If no approved `docs/propulsion/.../prd.md` exists, STOP. Enter the `brainstorm` skill. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review the approved `prd.md` to understand the feature completely. -2. Explore relevant areas of the codebase for fresh context. -3. Load relevant non-Propulsion skills not already active or present in context, and use them to inform the plan. -4. Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` from [references/plan-template.md](references/plan-template.md). -5. Start a fresh plan review subagent with the prompt in [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md). -6. Review and implement feedback from the plan review. -7. Repeat steps 5 and 6 until the review returns `Status: approved`. -8. Ask the user to review and approve the plan. -9. After explicit approval, enter the `execute` skill. - -## Rules - -These rules are MANDATORY. - -- NEVER skip reviewing the PRD, exploring the codebase, or loading missing relevant skills. -- ALWAYS use the plan template for structure, section order, and completion rules. -- NEVER print the full plan in the chat, ONLY write it to the file. -- MUST use ALL information from the PRD, DO NOT leave any details out even if they seem obvious or minor. -- USE `Status: approved` as the ONLY valid review approval signal. -- MUST treat review `findings` as fixable issues and `suggestions` as helpful improvements. -- NEVER invent product decisions that are not in the PRD; if a decision is missing, enter `brainstorm` to resolve it before planning. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Reviewed the PRD, codebase, and relevant skills. -- [ ] Written plan to `docs/propulsion/.../plan.md`. -- [ ] Plan reviewed by a subagent which returned `Status: approved`. -- [ ] User has explicitly approved `plan.md`. - -## Next Steps - -Once the completion gate is fully checked: - -- If `plan.md` is approved, enter the `execute` skill. - -## References - -Use these references when you need detail. - -- [references/plan-template.md](references/plan-template.md) - Plan shape and phase format. -- [references/plan-reviewer-prompt.md](references/plan-reviewer-prompt.md) - Plan-reviewer subagent prompt. diff --git a/skills/plan/references/plan-reviewer-prompt.md b/skills/plan/references/plan-reviewer-prompt.md deleted file mode 100644 index 104333d..0000000 --- a/skills/plan/references/plan-reviewer-prompt.md +++ /dev/null @@ -1,100 +0,0 @@ -# Plan Reviewer Prompt Template - -Use this template when starting a fresh plan review subagent in the `plan` skill. - -````markdown -**You are a subagent completing work in the Propulsion workflow.** - -Review whether the plan is implementation-ready and conforms to the plan template. - -**Plan document location**: `docs/propulsion/.../plan.md` -**Source PRD location**: `docs/propulsion/.../prd.md` - -## Review Criteria - -| Category | Verify | -| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Source Alignment | Preserves PRD decisions, inputs, testing decisions, constraints, and scope boundaries. | -| Requirements Traceability | Every PRD user story, functional requirement, and non-functional requirement appears in the matrix and is covered by at least one phase and criterion. | -| Acceptance Criteria Coverage | Criteria use exact PRD IDs, cover mapped requirements, are observable/testable, and specific enough to verify. | -| Vertical Slice Design | Phases are thin vertical slices delivering narrow end-to-end behaviour, not horizontal layers or vague milestones. | -| Phase Completeness | Each phase includes enough relevant layer work to deliver its stated behaviour. | -| Skills Coverage | Relevant skills are recommended globally/per phase; no obviously required skill is missing; no irrelevant skill is recommended. | -| Testing Coverage | Each phase has a testing plan that validates criteria and important public behaviours/seams. | -| Scope Control | Required work is included, speculative work is excluded, and no product behaviour is invented beyond the PRD. | -| Sequencing & Dependencies | Phase order is workable, dependencies are respected, and avoidable rework/dead ends are not forced. | -| Phase Specificity | Each phase gives enough context: goal, demo outcome, likely areas, constraints, notes, criteria, and testing plan. | -| Decision Hygiene | Durable decisions are captured once at the right level without contradictions or re-litigation points. | -| Template Conformity | Required template structure, section order, tables, and conventions are followed. | - -Flag only issues that would make implementation build the wrong thing, miss required scope, get stuck, or require re-planning. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review the plan against the source PRD for implementation-readiness. -2. Use the review criteria table above to guide your review. -3. Categorise issues that would cause real problems during implementation as `findings`. -4. Categorise issues that are more about improving implementation readiness without blocking the next stage as `suggestions`. -5. Return your findings and suggestions in the exact format below. - -## Output - -Use this exact format for your output. - -```markdown -# Plan Review Report - -**Status**: - - - -**Findings** - -- - - Phase or section affected: - - Why it matters: - - - - - -**Suggestions** - -- - - Phase or section affected: - - Why it matters: - - -``` - -## Rules - -These rules are MANDATORY. - -- NEVER skip any review criterion. -- ENSURE every part of the PRD is considered in the review, even if it seems obvious or minor. -- EVERY PRD user story, functional requirement, and non-functional requirement MUST be traceable to at least one phase and one acceptance criterion in the plan. -- MUST return exactly one `Status:` line with either `approved` or `rejected`. -- Status CAN be `approved` if there are only suggestions but NO findings. -- Status MUST be `rejected` if there are ANY findings. -- NEVER update the plan document or source PRD, only review and provide feedback in this output. -- ALWAYS follow the output structure and section order exactly as specified. - -## Completion Gate - -Do NOT output your response until ALL items are complete. - -- [ ] Thoroughly reviewed Plan against source PRD. -- [ ] Used the review criteria to identify issues and improvements. -- [ ] Categorised issues as findings or suggestions based on their impact on implementation readiness. -- [ ] Status is set to `approved` if no findings, or `rejected` if there are any blocking issues. -- [ ] Output review report in the exact format specified. -```` - -## Rules - -These rules are MANDATORY. - -- ALWAYS replace the plan and PRD paths with the actual paths for the plan being reviewed. diff --git a/skills/plan/references/plan-template.md b/skills/plan/references/plan-template.md deleted file mode 100644 index 83b9a88..0000000 --- a/skills/plan/references/plan-template.md +++ /dev/null @@ -1,103 +0,0 @@ -# Plan Template - -Write `docs/propulsion/{yyyymmdd}-{feature-name}/plan.md` using this exact section order. - -```md -# Plan - -> Source PRD: `docs/propulsion/.../prd.md` - -Use the `execute` skill to implement this plan and track progress using the checkboxes. - -## Durable Decisions - -List global phase decisions. - -- Decision 1 -- Decision 2 - -## Relevant Skills - -List every agentic skill that may be needed during implementation. - -| Skill | Required For | Details | -| -------------- | ---------------- | ------------------------------------------ | -| `` | Phase 1, Phase 3 | Declares how UI components should be used. | - -## Requirements Coverage Matrix - -Every PRD user story, functional requirement, and non-functional requirement MUST appear here. Use exact PRD IDs; do NOT rename, merge, or invent IDs. - -| PRD ID | Type | Covered By Phase(s) | Covered By Acceptance Criteria | Notes | -| ------- | -------------------------- | ------------------- | ------------------------------ | ----- | -| US-001 | User Story | Phase 1 | AC-001, AC-002 | | -| FR-001 | Functional Requirement | Phase 1 | AC-001 | | -| NFR-001 | Non-Functional Requirement | Phase 1 | AC-002 | | - -## Phase 1: - -**Status**: [ ] Phase complete - -**Goal**: Describe the narrow end-to-end behaviour this phase implements as a complete user-visible, system-visible, or test-verifiable outcome. - -**Demo / Verification Outcome**: Describe exactly how someone can verify this phase is complete without inspecting implementation details. - -**Skills To Load**: - -| Skill | Why This Phase Needs It | -| -------------- | ----------------------- | -| `` | `` | - -**Likely Areas**: - -Use exact paths only when durable and important. Prefer directories or modules when files may change. - -- `src/...` -- `tests/...` - -**Constraints**: - -List durable constraints this phase MUST respect. - -- Constraint 1 -- Constraint 2 - -**Implementation Notes**: - -Provide enough context to start without rediscovering scope. Do NOT invent product decisions absent from the PRD. - -- Note 1 -- Note 2 - -**Acceptance Criteria**: - -Each acceptance criterion MUST reference at least one PRD user story, functional requirement, or non-functional requirement unless purely functional with no NFR. - -| ID | Acceptance Criterion | User Story ID(s) | Functional Requirement ID(s) | Non-Functional Requirement ID(s) | -| ------ | ---------------------------------------------------------- | ---------------- | ---------------------------- | -------------------------------- | -| AC-001 | Given , when , then . | US-001 | FR-001 | NFR-001 | - -**Testing Plan**: - -Describe public behaviours and seams that MUST be tested for this phase. - -| Test Level | Required Coverage | -| --------------------- | ----------------- | -| Unit | | -| Feature / Integration | | -| Browser / UI | | -| Regression | | -| Manual Verification | | -``` - -## Rules - -These rules are MANDATORY. - -- MUST decompose the approved PRD into thin vertical slices (tracer bullets). -- Each phase MUST cut through every integration layer needed for that behaviour. -- PREFER many thin vertical phases over few thick phases. -- ONLY identify skills relevant to each phase by their description, DO NOT load the skills now. -- ENSURE every PRD user story, functional requirement, and non-functional requirement is covered in the Requirements Coverage Matrix. -- NEVER invent product decisions, business rules, UX behaviour, or edge-case handling not present in the approved PRD. -- EVERY acceptance criterion MUST have a unique ID. diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md deleted file mode 100644 index 7d66933..0000000 --- a/skills/pr/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: pr -description: Create or reuse a GitHub pull request from the current branch with safe commit and push. Use when opening, updating, or reporting a PR. ---- - -# Pull Request - -Create or reuse one GitHub pull request and report the verified result. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- GitHub CLI `gh` is installed and authenticated for the target repository (may need to run outside sandbox). -- The current directory is a git repository with an `origin` remote. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Resolve the base branch from optional user input, or default to the repo's main development branch. -2. Collect context first with [references/workflow.md](references/workflow.md). -3. If the current branch equals the base branch, stop and ask the user to confirm the intended base. -4. If the worktree is dirty, load and invoke the `commit` skill with no extra instructions, then refresh branch context before PR metadata. -5. Push safely: use `git push -u origin ` when no upstream exists; otherwise use `git push`. -6. Check for an existing open PR for the current head branch. -7. If an open PR exists with a different base, stop and ask whether to update it; only if confirmed, run `gh pr edit --base ` before title or body refresh. -8. If an open PR exists on the chosen base, reuse it unchanged when no commit delta exists; otherwise ask whether to refresh title and body, then use `gh pr edit` only after explicit confirmation. -9. If no open PR exists and no commit delta exists, output exactly `No PR changes to open.` -10. Generate a Conventional Commit PR title and summary body from the complete `...HEAD` history and diff. -11. Create the PR with `gh pr create --base --title "" --body "<body>"` when no reusable open PR exists. -12. Verify the final PR with `gh pr view --json url,number,title,baseRefName,headRefName,state` and return the output contract. - -## Rules - -These rules are MANDATORY. - -- ALWAYS collect context before committing, pushing, creating, editing, or reusing a PR. -- MUST use the complete branch history and diff, not only the latest commit, for title and body. -- MUST keep the PR title a valid Conventional Commit subject suitable for squash merge history. -- NEVER force push, reset, amend older commits, change git config, or bypass hooks. -- ALWAYS stop and report the failing command plus one unblock action for GitHub CLI auth, permission, or remote access failures. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Base branch, current branch, status, history, diff, and diff stat were collected. -- [ ] Dirty worktree was handled through the `commit` skill, or no dirty work existed. -- [ ] Push completed without force, or the workflow stopped for auth, permission, or access action. -- [ ] Existing PR reuse or refresh rules were followed, or a new PR was created. -- [ ] Final PR state was verified with `gh pr view`. -- [ ] Final response matches the required contract in [references/workflow.md](references/workflow.md). - -## References - -Use these references when you need detail. - -- [references/workflow.md](references/workflow.md) - Commands, PR metadata rules, body shape, and output contract. diff --git a/skills/pr/references/workflow.md b/skills/pr/references/workflow.md deleted file mode 100644 index 0c8da32..0000000 --- a/skills/pr/references/workflow.md +++ /dev/null @@ -1,106 +0,0 @@ -# Pull Request Workflow Reference - -## Inputs - -- Treat any explicit user-provided branch name as `<base>`. -- If no base is provided, use the repo's main development branch, such as `main` or `origin/HEAD`. - -## Context Commands - -Collect context before any mutation: - -- `git status --short` -- `git branch --show-current` -- `git log --oneline <base>...HEAD` -- `git diff <base>...HEAD` -- `git diff --stat <base>...HEAD` - -After invoking the `commit` skill for a dirty worktree, refresh: - -- `git status --short` -- `git log --oneline <base>...HEAD` -- `git diff <base>...HEAD` -- `git diff --stat <base>...HEAD` - -## Existing PR Handling - -Check for an open PR for the current head branch: - -```sh -gh pr list --head <branch> --state open --json url,number,title,body,baseRefName,headRefName -``` - -- If the PR base differs from `<base>`, stop and ask whether to correct the PR base. -- If the user explicitly agrees, update the base before any title or body refresh: `gh pr edit --base <base>`. -- If the user declines or gives an unclear answer, stop and ask them to rerun the PR skill with the intended base branch. -- If the PR base matches `<base>` and no commit delta exists, reuse unchanged, verify, and report success output. -- If the PR base matches `<base>` and a commit delta exists, show the URL and ask whether to refresh title and summary. -- If the user explicitly agrees, update only title and body with `gh pr edit --title "<title>" --body "<body>"`. -- If the user declines or gives an unclear answer, reuse unchanged, verify, and report success output. - -## Push Safety - -- If the branch has no upstream, run `git push -u origin <branch>`. -- If the branch has an upstream, run `git push`. -- Never force push. -- If push fails due to auth, permissions, or remote access, stop and report the failing command plus one concrete unblock action. - -## PR Metadata - -Infer title and summary from the full `<base>...HEAD` commit history, diff, and diff stat. - -Allowed Conventional Commit title types: - -- `build`: production dependencies or build-system changes -- `chore`: maintenance, admin, or dev-only dependency work -- `ci`: CI or automation pipeline changes -- `docs`: documentation-only changes -- `feat`: a new feature or functionality -- `fix`: a bug fix for incorrect behaviour -- `perf`: a performance improvement -- `refactor`: code changes without behaviour changes -- `revert`: reverts an earlier change -- `style`: formatting or style-only clean-up -- `test`: adds or updates tests - -Make the title a valid Conventional Commit subject suitable for squash merge history. - -Use this exact PR body shape: - -```md -## Summary - -- <bullet derived from the full PR scope> -``` - -If no open PR exists, create one with: - -```sh -gh pr create --base <base> --title "<title>" --body "<body>" -``` - -Verify the final PR with: - -```sh -gh pr view --json url,number,title,baseRefName,headRefName,state -``` - -## No Changes Output - -If no open PR exists and no commit delta exists against the base branch, output exactly: - -```md -No PR changes to open. -``` - -## Success Output - -When PR creation or reuse succeeds, output exactly: - -```md -PR URL: <url> -Title: <final PR title> -Base branch: <base> -Head branch: <head> -State: <state> -``` diff --git a/skills/propulsion/SKILL.md b/skills/propulsion/SKILL.md deleted file mode 100644 index da1e9e7..0000000 --- a/skills/propulsion/SKILL.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -name: propulsion -description: Execute structured AI software development from planning through execution. Use when implementing or updating code, debugging issues, or starting software work. ---- - -# Propulsion - -Route software-work requests into the right Propulsion entry stage before any other action. - -<SUBAGENT_STOP> -If you were dispatched as a subagent to execute a specific task, SKIP THIS SKILL. -</SUBAGENT_STOP> - -<EXTREMELY_IMPORTANT> -ONCE YOU ARE FOLLOWING PROPULSION WORKFLOW, DO NOT LEAVE IT UNTIL COMPLETION. DO NOT SKIP STEPS. FOLLOW THE RULES OF EACH SKILL. -</EXTREMELY_IMPORTANT> - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Determine whether the request is software work. -2. If it is not software work, ignore Propulsion and respond normally. -3. If it is a concrete failure, emit `Propulsion workflow enabled, routing to debug...`, then load and follow `debug` skill. -4. If it is a greenfield project, new product idea, project discovery, competitor research, positioning, or full system blueprint request, emit `Propulsion workflow enabled, routing to discover-project...`, then load and follow `discover-project` skill. -5. If it is mature feature or product-scope work, emit `Propulsion workflow enabled, routing to brainstorm...`, then load and follow `brainstorm` skill. -6. The loaded Propulsion skill now owns the workflow stage. - -## Rules - -These rules are MANDATORY. - -- ALWAYS follow instructions in this order: - 1. User instructions are the highest priority (Direct requests or AGENTS.md, CLAUDE.md). - 2. Propulsion skills override default system behaviour. - 3. Default system behaviour is the lowest priority. -- NEVER route non-software-work request to Propulsion. -- ONLY route concrete failures to `debug` (bug reports, regressions, failing tests, failing builds, runtime errors, crashes). -- MUST route greenfield products, project discovery, competitor research, positioning, or full system blueprint work to `discover-project`. -- MUST route mature feature and product-scope work to `brainstorm` (new features in an existing project, unclear feature scope, UX/product shaping, requirements discovery, behaviour changes, refactors, optimisations). -- ALWAYS fall back to `brainstorm` if the request is ambiguous. -- DO NOT leave a Propulsion skill until ALL completion gate items are complete. -- NEVER reload skills (Propulsion or non-Propulsion) that are already active or present in context; continue following the loaded copy instead. -- NEVER rationalise skipping Propulsion with thoughts like: - - "I need more context first" - - "I'll inspect the repo first" - - "This is too small for Propulsion" - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Determined whether the request is software work. -- [ ] Kept non-software-work outside Propulsion. -- [ ] Routed concrete failures to `debug`. -- [ ] Routed greenfield discovery work to `discover-project`. -- [ ] Routed mature feature and product-scope work to `brainstorm`. -- [ ] Emitted the route-specific required response before any other user-visible text. - -## References - -Use these references when you need detail. diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md deleted file mode 100644 index 2255386..0000000 --- a/skills/review/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: review -description: Review PRs and ref ranges with senior-level findings, validation, and exact reports. Use when reviewing PRs or base...head changes. ---- - -# Review - -Review a PR or ref range and return a validated senior-engineer report. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- If review scope is unclear, STOP. Ask for a PR number, PR URL, or `base...head` ref range. -- GitHub CLI `gh` is installed and authenticated when reviewing a PR number or PR URL. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Resolve review scope and allowed context with [references/mode-selection.md](references/mode-selection.md); stop and ask for a PR number, PR URL, or `base...head` when scope is unclear. -2. Dispatch fresh reviewer subagents in parallel with [references/reviewer-prompt.md](references/reviewer-prompt.md). Cover the axes in [references/review-axes.md](references/review-axes.md). -3. Dispatch fresh validator subagents with [references/validator-prompt.md](references/validator-prompt.md). Discard anything unconfirmed. -4. Produce the final report exactly as defined in [references/report-format.md](references/report-format.md). Use only `approve`, `approve-with-comments`, `request-changes`, or `needs-clarification`. - -## Rules - -These rules are MANDATORY. - -- MUST accept only `#<pr-number>`, PR URLs, or `base...head`. -- MUST require installed and authenticated `gh` only for PR review scopes. -- ALWAYS validate both refs before reviewing `base...head`; do not guess missing refs. -- ALWAYS use merge-base diff semantics for `base...head`. -- ALWAYS use a severity-first model: `critical`, `high`, `medium`, `low`, `nitpick`, `question`. -- ALWAYS report only validated findings or validated missing-context questions with concrete evidence and exact `file:line` refs when code is involved. -- DO keep findings issue-focused. DO NOT add a positive-notes section. -- DO NOT keep style nits, speculative risks, weak evidence, pre-existing issues, or linter-catch comments. -- DO treat blocking findings as validated `critical` and `high` findings that would materially harm production, security, UX, or maintenance if shipped. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Scope was resolved as a PR number, PR URL, or `base...head`. -- [ ] PR scopes used GitHub PR metadata, or range scopes validated both refs and reviewed the merge-base diff. -- [ ] Reviewer and validator passes completed before the final report. -- [ ] Final response matches [references/report-format.md](references/report-format.md). - -## References - -Use these references when you need detail. - -- [references/mode-selection.md](references/mode-selection.md) - Scope parsing, validation, and allowed context. -- [references/review-axes.md](references/review-axes.md) - Parallel reviewer-pass contracts. -- [references/reviewer-prompt.md](references/reviewer-prompt.md) - Prompt template for one reviewer pass. -- [references/issue-schema.md](references/issue-schema.md) - Candidate finding and question schema. -- [references/validator-prompt.md](references/validator-prompt.md) - Prompt template for one validator pass. -- [references/validation-rubric.md](references/validation-rubric.md) - Disprove-first validation rules. -- [references/report-format.md](references/report-format.md) - Exact final report shape and decision rules. diff --git a/skills/review/references/issue-schema.md b/skills/review/references/issue-schema.md deleted file mode 100644 index 4b8ea45..0000000 --- a/skills/review/references/issue-schema.md +++ /dev/null @@ -1,54 +0,0 @@ -# Issue Schema - -Use when normalising candidate findings and questions before validation. - -```json -{ - "kind": "finding", - "file": "src/path/file.ts", - "line": 42, - "severity": "high", - "category": "duplication", - "summary": "Short issue title", - "evidence": "Quoted diff, exact rule text, quoted precedent snippet, concrete principle-backed code evidence, or explicit intent evidence", - "evidence_type": "intent-context", - "impact": "Why this matters in this codebase", - "confidence": 88, - "blocking": true, - "rule_source": "AGENTS.md:18", - "precedent_refs": ["src/example.ts:10", "src/example.ts:44"], - "intent_refs": ["PR description", "docs/propulsion/example-plan.md:12-18"], - "principle_basis": "DRY|single-source-of-truth|separation-of-concerns|ownership-boundary|test-protection|cohesion|encapsulation|complexity-management|abstraction-leakage|SOLID|YAGNI", - "open_question": "What missing context prevents a reliable decision?", - "validator_verdict": "pending|confirmed|rejected" -} -``` - -## Required rules - -- `kind`, `severity`, `category`, `summary`, `evidence`, `evidence_type`, `impact`, `confidence`, and `validator_verdict` are mandatory. -- `kind` MUST be `finding` or `question`. -- `file` and `line` are required for code-based findings; omit them only for pure intent or rule questions. -- `severity` MUST be one of `critical`, `high`, `medium`, `low`, `nitpick`, `question`. -- `category` MUST be one of `rule-violation`, `skill-contract-violation`, `bug`, `compile-break`, `logic-error`, `security`, `performance`, `architecture`, `maintainability`, `duplication`, `test-gap`, `requirement-drift`, or `consistency-drift`. -- `evidence` MUST be concrete and tied to changed code, scoped rule text, or cited precedent. -- `evidence_type` MUST be `diff`, `rule-text`, `precedent`, `principle`, or `intent-context`. -- `confidence` MUST be integer `0-100`. -- `blocking` is required for findings; set `true` only for material production, security, UX, or maintenance risk. -- `rule_source` is required for `rule-violation` and `skill-contract-violation`. -- `precedent_refs` is required for `consistency-drift` and any precedent-backed finding. -- `intent_refs` is required for `requirement-drift` and any intent-backed finding. -- `principle_basis` is required for any principle-backed finding. -- `open_question` is required for `kind: question` and should explain the exact missing context. -- DO use `principle` evidence only when the finding names the violated code-health principle and the impact is specific to the changed code. - -## Deduplication key - -Use `(kind, file, line, severity, category, normalised summary)`. - -Only one final finding per dedupe key. - -## Rules - -- ALWAYS normalise every candidate before validation. -- DO omit fields only when these rules explicitly allow omission. diff --git a/skills/review/references/mode-selection.md b/skills/review/references/mode-selection.md deleted file mode 100644 index b7c5db9..0000000 --- a/skills/review/references/mode-selection.md +++ /dev/null @@ -1,40 +0,0 @@ -# Mode Selection - -Use when resolving review scope. - -## Accepted Forms - -- `#<pr-number>` -- PR URL -- `base...head` - -No other scope forms are supported. - -## PR Scope - -- Confirm explicit PR numbers match `#<number>`. -- Accept GitHub PR URLs as explicit PR scope. -- Require `gh` installed, authenticated, and able to access the repository only for PR scopes. -- Resolve PR scope with `gh pr view <number-or-url> --json number,title,body,baseRefName,headRefName,headRefOid,baseRefOid,files,url`. -- Use PR metadata for base/head refs, changed files, title, body, and linked artefact discovery. -- If lookup fails, ask one corrective follow-up for a valid PR number or URL; do not guess another PR. - -## Range Scope - -- Confirm range input contains exactly one `...` separator with non-empty `base` and `head` refs. -- Validate both refs with `git rev-parse --verify <ref>^{commit}` before reviewing. -- If either ref is missing/invalid, ask one corrective follow-up for a valid `base...head` range; do not substitute another ref. -- Review the merge-base diff for the exact range, equivalent to `git diff <base>...<head>`. -- Use changed files from the exact merge-base diff. -- Use explicit user-stated review goals when intent context is needed. - -## Validation Checks - -- If scope is missing or unclear, ask the user for a PR number, PR URL, or `base...head` before review begins. -- If the resolved scope has no reviewable file changes, still return the standard review report and state that the scope was empty. - -## Rules - -- DO accept only the documented scope forms. -- DO NOT infer scope from the current checkout. -- DO NOT require GitHub CLI for `base...head` range review. diff --git a/skills/review/references/report-format.md b/skills/review/references/report-format.md deleted file mode 100644 index 62ad012..0000000 --- a/skills/review/references/report-format.md +++ /dev/null @@ -1,97 +0,0 @@ -# Report Format - -Use this exact final report shape for PR and `base...head` reviews, including empty scopes. - -```markdown -# Review Report - -**Scope**: <PR #123 | PR URL | base...head> - -**Intent Summary**: <1-3 sentences describing the change goal from PR context or explicit user intent> - -**Final Decision**: <approve | approve-with-comments | request-changes | needs-clarification> - -**Critical Findings** - -- None - -<or> - -- <short title> - - Location: <path:line | scope area> - - Why it matters: <concrete impact on correctness, security, UX, performance, or maintenance> - - Evidence: <quoted diff, rule text, precedent, or intent evidence> - - Recommended action: <smallest safe improvement> - -**High Findings** - -- None - -<or same finding item shape as Critical> - -**Medium Findings** - -- None - -<or same finding item shape as Critical> - -**Low Findings** - -- None - -<or same finding item shape as Critical> - -**Nitpicks** - -- None - -<or> - -- <short title> - - Location: <path:line | scope area> - - Why it matters: <why this polish is still worth mentioning> - - Evidence: <quoted diff or precedent> - - Recommended action: <smallest safe improvement> - -**Questions** - -- None - -<or> - -- <short title> - - Missing context: <exact artefact, assumption, or behaviour still needed> - - Why it matters: <how this blocks a reliable decision or severity> - - Evidence checked: <what was already inspected> - -**Residual Risk** - -- None - -<or> - -- <short risk> - - Why it remains: <what could not be fully verified after allowed review steps> -``` - -## Decision rules - -- `approve`: no validated findings and no unanswered blocking questions. -- `approve-with-comments`: only non-blocking validated findings remain. -- `request-changes`: at least one validated blocking finding remains. -- `needs-clarification`: missing context prevents a reliable recommendation. - -## Section rules - -- Use the exact section names shown above. -- Keep findings grouped by severity in descending order. -- Each finding must include short title, `Location`, `Why it matters`, `Evidence`, and `Recommended action`. -- If the resolved review scope is empty, set `**Final Decision**` to `approve`, explain the empty scope in `**Intent Summary**`, and keep all finding sections as `- None`. -- Put unresolved missing-context items only in `**Questions**`, not in severity groups. -- `**Residual Risk**` covers what could not be fully verified after the allowed review steps, even if no question remains. -- Do not add a positive-notes or praise section. - -## Rules - -- ALWAYS use this exact section order. -- DO NOT add extra top-level sections. diff --git a/skills/review/references/review-axes.md b/skills/review/references/review-axes.md deleted file mode 100644 index af3136f..0000000 --- a/skills/review/references/review-axes.md +++ /dev/null @@ -1,47 +0,0 @@ -# Review Axes - -Use when dispatching focused reviewer passes. - -## Focused reviewer passes - -- Correctness: changed behaviour vs stated intent, edge cases, failure paths, state transitions, data flow, and dependency changes. -- Security / trust boundaries: auth, authorization, validation, injection surfaces, secrets, config, logging, file handling, and integration boundaries. -- Maintainability / architecture: wrong-layer ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, coupling, unnecessary complexity, and unnecessary indirection. Apply named principles only when impact is concrete in changed code. -- Tests / verification: changed behaviour protected by tests or other verification, including realistic failure modes and regressions. -- Intent / rule alignment: diff vs PR intent, linked planning artefacts, scoped `AGENTS.md` / `CLAUDE.md`, touched command/skill contracts, and dominant local precedent when consistency matters. - -## Alignment rules - -- Review like a senior PR reviewer, not a lint pass. -- Improve code health; do not seek perfection. -- Prefer concrete, merge-relevant issues the author would fix. -- Read code in context, not only diff hunks. -- Treat tests and trust-boundary changes as first-class review scope. -- Use exact evidence, quoted rules, and nearby precedent before broad principles. - -## Named principles allowed for principle-backed findings - -- `DRY` -- `single-source-of-truth` -- `separation-of-concerns` -- `ownership-boundary` -- `test-protection` -- `cohesion` -- `encapsulation` -- `complexity-management` -- `abstraction-leakage` -- `SOLID` -- `YAGNI` - -## Reject candidates when - -- The complaint is aesthetic or stylistic. -- The claim depends on hidden requirements. -- The issue is too small for a final report finding. -- Multiple local patterns exist and no dominant precedent is clear. -- The suggestion is speculative future-proofing instead of a concrete fix for this diff. - -## Rules - -- EACH pass returns only candidates, NEVER final report text. -- DO stay inside the allowed review scope and gathered context. diff --git a/skills/review/references/reviewer-prompt.md b/skills/review/references/reviewer-prompt.md deleted file mode 100644 index 23b4f76..0000000 --- a/skills/review/references/reviewer-prompt.md +++ /dev/null @@ -1,59 +0,0 @@ -# Reviewer Prompt Template - -Use this reference when dispatching a fresh reviewer subagent for one review axis. - -````markdown -You review exactly one axis in a PR-style code review. - -## Inputs - -- **Review axis**: `<correctness | security/trust boundaries | maintainability/architecture | tests/verification | intent/rule alignment>` -- **Scope summary**: `<resolved review scope>` -- **Intent context**: `<PR title/description and linked artefacts, or explicit user-stated review goal>` -- **Changed files**: `<list of changed files in scope>` -- **Allowed context**: `<scoped rules/contracts, allowed adjacent files, precedent refs, and linked artefacts>` - -## Review Focus - -| Axis | Look for | Do not report | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -| Correctness | Broken logic, wrong branches, unsafe state transitions, dependency regressions, deterministic runtime failures | Style nits, unevidenced hypothetical failures | -| Security / trust boundaries | Auth/authz mistakes, missing validation, injection surfaces, secrets/config leaks, unsafe integrations | Generic security advice not triggered by the diff | -| Maintainability / architecture | Wrong ownership, second sources of truth, duplicated business logic, concrete refactoring opportunities, abstraction leakage, harmful complexity, unnecessary indirection | Broad refactor wishes, future-proofing speculation | -| Tests / verification | Missing protection for changed behaviour, realistic regressions, weak failure-path coverage | Complaints not tied to changed behaviour | -| Intent / rule alignment | Drift from PR intent, linked artefacts, scoped rules, or dominant precedent | Hidden requirements or unstated preferences | - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Review only the assigned axis. -2. Inspect changed files and only allowed context. -3. Compare the diff against the assigned axis; keep only merge-relevant candidates. -4. Normalise every candidate using `references/issue-schema.md`. -5. Return candidates only. Do not write final review prose. - -## Output - -Use this exact format for your output. - -```json -[ - <Replace with the exact JSON object shape from `references/issue-schema.md`>, - <Repeat for each candidate found in this review pass> -] -``` - -Return `[]` when no candidates survive the reviewer pass. - -## Rules - -These rules are MANDATORY. - -- ALWAYS stay inside the assigned axis. -- ALWAYS stay inside the allowed review scope and allowed context. -- DO return only normalised candidates. -- MUST replace the output placeholders with the exact JSON object shape from `references/issue-schema.md` before dispatching the reviewer. -- DO NOT write final report sections, verdicts, or fix patches. -- DO NOT keep stylistic, speculative, or low-value complaints. -```` diff --git a/skills/review/references/validation-rubric.md b/skills/review/references/validation-rubric.md deleted file mode 100644 index 51c321c..0000000 --- a/skills/review/references/validation-rubric.md +++ /dev/null @@ -1,62 +0,0 @@ -# Validation Rubric - -Use when validating candidate findings and questions before final report generation. - -## Disprove-first flow - -1. Assume the finding is wrong. -2. Search diff, changed files, scoped rules/contracts, and gathered adjacent context for counter-evidence. -3. Reject if evidence is incomplete, ambiguous, pre-existing, or out of scope. -4. Confirm only if objective evidence supports the claim and the issue is one the PR author would fix. - -## Candidate types - -- Validate `finding` candidates and `question` candidates separately. -- A `question` is valid only when missing context materially blocks final decision or severity and cites the exact missing artefact, assumption, or unresolved behaviour. - -## Severity confirmation requirements - -- `critical` - - Deterministic breakage, material security exposure, or an explicit rule/contract violation that should block merge. - - Confidence `>= 90`. -- `high` - - Strongly evidenced bug, trust-boundary failure, requirement drift, test gap, or architecture regression with material merge risk. - - Confidence `>= 85`. -- `medium` - - Meaningful maintainability, performance, or verification issue that should likely be fixed before or immediately after merge. - - Confidence `>= 80`. -- `low` - - Real but lower-risk maintainability or consistency drag with a clear alignment path. - - Confidence `>= 75`. -- `nitpick` - - Minor non-blocking cleanup worth mentioning only when strongly evidenced and clearly useful. - - Confidence `>= 70`. -- `question` - - Missing context that prevents a reliable decision. Do not use when the reviewer can resolve the uncertainty from allowed context. - - Confidence `>= 80` that the context gap is real. - -## Evidence requirements - -- Evidence must come from changed code, scoped rules/contracts, allowed adjacent context, nearby precedent, or linked intent artefacts. -- Rule/contract violations quote exact text and source path; consistency claims cite dominant local precedent. -- Principle-backed claims name the principle and concrete maintenance, ownership, testing, or correctness cost. -- Test-gap claims tie directly to changed behaviour and realistic failure modes. - -## Automatic reject conditions - -- Style-only or subjective guidance without strong precedent or principle evidence. -- Potential issues requiring context beyond the sanctioned review window: changed files, scoped rules/contracts, allowed adjacent files, and explicitly linked PR artefacts. -- Pre-existing issues not introduced by reviewed diff. -- Linter-catch issues. -- Consistency findings when multiple equally accepted patterns exist. -- Missing `rule_source` for rule/contract violations. -- Missing `precedent_refs` for consistency findings. -- Principle-backed maintainability or architecture claims with no concrete impact. -- Test-gap claims that do not tie to changed behaviour or realistic failure modes. -- Questions that ask for context the review was already allowed to inspect. -- Questions that do not change the likely decision, severity, or recommended action. - -## Rules - -- ALWAYS try to disprove every candidate before confirming it. -- DO report only candidates that survive every applicable validation rule. diff --git a/skills/review/references/validator-prompt.md b/skills/review/references/validator-prompt.md deleted file mode 100644 index 50b751d..0000000 --- a/skills/review/references/validator-prompt.md +++ /dev/null @@ -1,48 +0,0 @@ -# Validator Prompt Template - -Use when dispatching a fresh validator subagent for one normalised candidate. - -````markdown -You validate one candidate finding or question from a senior PR review workflow. - -## Inputs - -- **Candidate**: `<full normalised candidate JSON>` -- **Scope summary**: `<resolved review scope>` -- **Intent context**: `<PR title/description and linked artefacts, or explicit user-stated review goal>` -- **Allowed context**: `<changed files, scoped rules/contracts, allowed adjacent files, precedent refs, and linked artefacts>` - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Apply `references/validation-rubric.md` exactly. -2. Start by assuming the candidate is wrong. -3. Search for counter-evidence in the allowed context. -4. Confirm the candidate only if the evidence and impact survive the full rubric. -5. Return a verdict for this candidate only. - -## Output - -Use this exact format for your output. - -```json -{ - "summary": "Short issue title", - "validator_verdict": "confirmed", - "confidence": 88, - "blocking": true, - "reason": "Brief evidence-backed explanation" -} -``` - -Use `validator_verdict: "rejected"` when the candidate does not survive validation. - -## Rules - -- ALWAYS try to disprove the candidate first. -- DO confirm only one candidate per validation run. -- DO keep the verdict evidence-based and concise. -- DO NOT widen scope beyond the allowed context. -- DO NOT rewrite the candidate into final report prose. -```` diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md deleted file mode 100644 index d3d665a..0000000 --- a/skills/tdd/SKILL.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -name: tdd -description: Execute TDD red-green-refactor for behaviour changes. Use when changing observable behaviour, public contracts, or durable business logic. ---- - -# TDD - -Drive behaviour changes with one failing behavioural test, minimal green code, then safe refactor. - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- The task changes observable behaviour, a public contract, or durable business logic. -- A local test runner and relevant test command are available. If not, STOP and ask whether adding or fixing the test path is in scope. -- Maintenance-only work is invalid for TDD. STOP for docs/comments/prompts/spec text, styling-only UI changes, copy-only edits unless copy is the contract, config/build/dev-tool text edits, dependency bumps, generated files, data/schema migrations without logic changes, or pure refactors. -- If work mixes behaviour change with maintenance, apply TDD ONLY to the behaviour-changing slice. - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Choose the smallest thin vertical slice that delivers one observable behaviour end-to-end; state the interface, expected outcome, and narrowest test command. -2. Apply [references/testing-patterns.md](references/testing-patterns.md). If no valuable behavioural test exists, record the no-test rationale and strongest fallback verification before changing code. -3. Write ONE failing test through a public interface or stable seam for the next behaviour only. -4. Run the narrowest test command and confirm the test fails for the expected reason. -5. Write minimum passing production code; keep fixtures small and mock only real external, slow, unstable, or nondeterministic boundaries. -6. Re-run the narrowest test command and confirm green. -7. Review refactor candidates only after green using [references/refactor-candidates.md](references/refactor-candidates.md); refactor in small behaviour-preserving steps and rerun checks. -8. Repeat slice by slice until the requested behaviour is complete. - -## Rules - -These rules are MANDATORY. - -- NEVER write production code before a failing test when a valuable behavioural test exists. -- ALWAYS test observable behaviour through a public interface or stable seam. -- NEVER add source-text checks, private-structure checks, internal call choreography, broad snapshots, speculative tests, or implementation-detail tests as behavioural proof. -- DO NOT over-mock; ONLY mock real boundaries that are external, slow, unstable, nondeterministic, or too expensive for the selected test scope. -- STOP and ask if the behaviour, acceptance rule, stable seam, or relevant test command is unclear. -- NEVER refactor while red. -- ALWAYS prefer a regression test first for bug fixes. - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] Work was implemented in thin vertical slices. -- [ ] Each testable slice has red proof that failed for the expected reason, then green proof after the smallest implementation. -- [ ] Tests prove behaviour through a public interface or stable seam, with no brittle, speculative, implementation-detail, or over-mocked tests kept. -- [ ] No-test fallback rationale was documented only where no valuable behavioural test exists. -- [ ] Refactor opportunities were reviewed after green, and refactors happened only while checks were green. - -## References - -Use these references when you need detail. - -- [references/testing-patterns.md](references/testing-patterns.md) - Test scope, behavioural seams, mocks, anti-patterns, fallback verification, and concise templates. -- [references/refactor-candidates.md](references/refactor-candidates.md) - Safe refactor candidates and post-green refactor gates. diff --git a/skills/tdd/references/refactor-candidates.md b/skills/tdd/references/refactor-candidates.md deleted file mode 100644 index 7012a35..0000000 --- a/skills/tdd/references/refactor-candidates.md +++ /dev/null @@ -1,84 +0,0 @@ -# Refactor Candidates - -Use only after red-green is green. Refactor to remove present design pressure while preserving behaviour. - -## When To Refactor - -Refactor when checks are green and you can name a real improvement. Good reasons: - -- the next change is harder than it should be; -- a rule is duplicated and starting to drift; -- names hide the behaviour proven by tests; -- setup or tests are noisy because responsibilities are misplaced; -- branches or data shapes obscure the domain rule; -- a small move would reduce current risk or confusion. - -Do one structural idea at a time; stop when current pain is removed. - -## When Not To Refactor - -Do not refactor when: - -- tests or fallback checks are red; -- the improvement is hypothetical; -- the abstraction has one caller and no present pressure; -- you cannot describe the behaviour-preserving move; -- the code is awkward but isolated and not blocking current work; -- the refactor would expand scope beyond the requested slice. - -Use YAGNI: reject abstractions for futures the code does not need today. - -## Signals To Spot - -### Duplicated Knowledge - -Look for the same decision, validation, calculation, workflow, or domain phrase in multiple places. Copies drift and fixes land in one place. Improve by extracting the shared rule, moving it to the owner, or introducing a small abstraction only after real call sites need it. - -### Mixed Responsibilities - -Look for one function/module that validates, calculates, persists, formats, and coordinates. Unrelated changes collide and tests need excessive setup. Improve by separating orchestration from decisions, moving behaviour to the strongest owner, and keeping coordinators thin. - -### Poor Names - -Look for placeholders, abbreviations, stale names, or tests named for mechanics instead of behaviour. Unclear names hide intent and slow changes. Rename variables, functions, types, files, and tests to match domain meaning. - -### Long Or Tangled Flow - -Look for deep nesting, repeated conditions, order-sensitive branches, or methods that require scrolling. Bugs hide in unreadable paths. Improve with guard clauses, predicates, named steps, or split cases; use polymorphism only after duplication makes cases real. - -### Feature Envy - -Look for logic repeatedly pulling fields from another object to decide for it. Move behaviour closer to the data or replace field chains with messages to the owner. - -### Primitive Obsession - -Look for strings, booleans, numbers, or loose parameter groups repeatedly encoding a domain concept. Use a small value object, enum, named type, or parameter object when the concept has behaviour or repeated validation. - -### Test Friction - -Look for tests needing heavy setup, many mocks, private seams, or fragile assertions for simple behaviour. Test pain often exposes design pain; improve production design when valuable, not test-only seams. - -## Safe Moves - -Prefer small behaviour-preserving moves: - -- rename; -- extract function or predicate; -- inline unnecessary indirection; -- move behaviour to its owner; -- split orchestration from domain rules; -- replace magic values with named concepts; -- collapse duplicated rules; -- simplify conditionals; -- replace partial mocks with realistic fakes when it improves design pressure. - -Run the narrowest relevant check after each meaningful move. If it fails, fix or revert the last refactor step before continuing. - -## Filters - -Use these filters before changing structure: - -- DRY: remove repeated knowledge, not every repeated line. -- SOLID: improve ownership only where current design already shows pressure. -- YAGNI: do not build for imagined futures. -- Refactor-safe tests: existing tests should still prove the same behaviour after the move. diff --git a/skills/tdd/references/testing-patterns.md b/skills/tdd/references/testing-patterns.md deleted file mode 100644 index dfbe5eb..0000000 --- a/skills/tdd/references/testing-patterns.md +++ /dev/null @@ -1,112 +0,0 @@ -# Testing Patterns - -Use before writing or keeping a TDD test. Keep tests behavioural, refactor-safe, and cheap enough for red-green. - -## When TDD Applies - -Use TDD for observable behaviour, public contracts, or durable business logic. Do not force it for prose-only docs, comments, prompts, formatting, config text, dependency bumps, generated files, or pure refactors; record no-test rationale and run fallback verification. If work mixes behaviour and maintenance, TDD only the behaviour-changing slice. - -## Test Type Choice - -Choose the highest-level quick, deterministic test that proves behaviour. - -1. Prefer feature or integration tests first. Test the public path a caller, user, endpoint, CLI, message handler, or upstream module uses. -2. Use unit tests second for isolated important logic, especially rules with many cases, edge conditions, or awkward setup through the full path. -3. Use browser or end-to-end tests sparingly for UI interaction patterns, smoke coverage, or behaviour that lower-level tests cannot prove. - -Drop lower only when the higher-level path is slow, flaky, too broad, or expensive to control; use a stable domain seam, not a private helper. - -## Red-Green Test Quality - -Write one failing test for one missing behaviour. - -Good red tests name caller-visible behaviour, fail for the expected reason before production changes, imply the next smallest code change, assert observable outcomes, and avoid future requirements. - -Weak red tests assert helper calls, call order, source text, hook names, class names, or private state; require large mock choreography; fail when internals move but behaviour stays; or cover hypothetical edge cases. - -## Refactor-Safe Tests - -Refactor-safe tests keep passing when internals change but behaviour does not. Assert through public interfaces or stable seams: - -- returned values; -- persisted state through supported reads; -- visible UI or announced accessibility output; -- emitted domain events; -- externally visible side effects. - -Avoid private helpers, hidden fields, internal modules, source-string checks, AST shape, broad snapshots, and internal call choreography. - -```typescript -// Good: public behaviour -test('rejects checkout when the cart is empty', async () => { - const result = await checkout(emptyCart()); - - assertEqual(result.ok, false); - assertEqual(result.error, 'Cart is empty'); -}); - -// Bad: implementation detail -test('calls validateCart before createOrder', async () => { - const calls = recordCallOrder( - cartModule, - 'validateCart', - orderModule, - 'createOrder', - ); - - await checkout(emptyCart()); - - assertSequence(calls, ['validateCart', 'createOrder']); -}); -``` - -## Good Tests - -Good tests prove a depended-on behaviour through exported functions, endpoints, commands, UI interactions, handlers, or stable domain seams. Keep setup small and realistic; use multiple assertions only for one outcome from one cause; prefer cheap builders, fixtures, in-memory adapters, and real collaborators; make failures describe broken behaviour. - -Examples: `login(email, password)` rejects invalid credentials; `publishPost()` makes the post visible in `listPublishedPosts()`; clicking `Save` shows a success message. - -## Bad Tests - -Reject structure tests: `checkout()` calls `paymentService.charge()` once; `login()` calls `validatePasswordHash()`; source text contains `aria-label`; a broad snapshot proves a menu opens; a test exists only because an edge case might matter later. - -Replace bad tests with behavioural assertions. If none exists, do not keep a weak test; document the no-test rationale and run fallback verification. - -## Mocks And Doubles - -Mock only real boundaries that are external, slow, unstable, nondeterministic, or too expensive for the selected scope. Good targets: - -- payment gateways; -- clocks and time; -- UUID/randomness; -- network calls; -- file systems; -- third-party APIs. - -Keep core logic real. Prefer behaviour-preserving fakes, such as an in-memory repository or mailer. If mock setup dominates, the test likely proves mocks agree. If mock data is required, mirror enough real schema to avoid accidental reliance on missing fields. - -## Anti-Patterns - -Do not keep these as behavioural proof: - -- source-string checks; -- private-structure checks; -- internal call counts or order; -- broad snapshots for dynamic markup; -- test-only production flags or methods; -- partial hand-waved mocks; -- tests for speculative requirements; -- mocking away the behaviour under test. - -## Gate Questions - -Ask before writing or keeping a test: - -1. What behaviour does this prove for a caller or user? -2. Would it pass after an internal rewrite with the same behaviour? -3. Is the assertion through a public interface or stable domain seam? -4. Is every mock isolating a real boundary? -5. Is this the next required behaviour, not a future guess? -6. Will failure point to broken behaviour rather than changed structure? - -If any answer is no, rewrite the test. If no valuable behavioural test remains, document why and run the strongest fallback verification: existing related tests, typecheck, lint, build, CLI smoke check, browser check, or manual reproduction. diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index a264ee4..570d8db 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,53 +1,39 @@ --- name: write-skill -description: Create or improve reusable skills with compact progressive-disclosure artefacts. Use when authoring, updating, or migrating any skill. +description: User-invoked workflow for predictable agent-skill authoring. Use when creating or updating a skill. +metadata: + invocation: user +disable-model-invocation: true --- -# Write Skill +A skill makes an agent's process predictable without fixing the outcome. -Create concise skills for repeatable workflows without bloating context. +## Steps -## Instructions +Start with the applicable discovery branch, then complete the shared stages. -Follow these steps IN ORDER. Do NOT skip steps. +### Create — use-case modeling -1. Load `interrogate` to gather the skill's job, use cases, expected inputs, expected outputs, and trigger phrases before drafting. -2. Choose the default output path `.agents/skills/{skill-name}/`; keep `name` equal to the directory name. -3. Draft or update `SKILL.md` using [assets/skill-template.md](assets/skill-template.md). -4. Put only essential workflow in `SKILL.md`; move supporting artefacts into appropriate directories. -5. Put templates/static resources in `assets/`, executable helpers in `scripts/`, and detailed docs in `references/`. -6. Validate the result with [scripts/validate-skill.js](scripts/validate-skill.js), then fix every blocking issue. +Ground the skill in concrete prompts and expected agent behaviour. Identify its job, inputs, outputs, invocation conditions, branches, and constraints until every intended use case has an explicit route. -## Rules +### Update — characterization + +Read the complete skill bundle, direct references, callers, and reported failures. Distinguish behaviour that remains intentional or relied upon from obsolete material until every current branch and requested change is accounted for. -These rules are MANDATORY. +### Design -- Required authored-skill sections are title, one-line purpose, `## Instructions`, and `## References`. -- Optional sections become REQUIRED when prerequisites, durable rules, completion gates, or next steps exist. -- MUST use only canonical H2 sections in order; `## References` must be the final H2. -- MUST keep `SKILL.md` compact: target about 50 body lines and never exceed 80 body lines. -- MUST make `description` one line, triggerable, and clear about when the skill should be used. -- MUST place artefacts directly under `assets/`, `references/`, or `scripts/` and link each from final references as `- [path](path) - text`. -- MUST use progressive disclosure: metadata first, essential instructions second, artefacts as needed. -- MUST write short, direct, instructional prose: remove filler, pleasantries, hedging, and verbose phrases while preserving exact technical meaning. -- MUST review [references/checklist.md](references/checklist.md) and run [scripts/validate-skill.js](scripts/validate-skill.js) before handoff. +Read [the skill format](references/FORMAT.md), then choose the name, invocation policy, description, structure, and bundled resources. Select one dominant established concept that identifies the skill's technique; add another only when it governs a distinct concern. Give fragile work narrow degrees of freedom and judgement-heavy work explicit boundaries. Finish when every use case has a route and every ordered step has a clear postcondition. -## Completion Gate +### Write -Do NOT leave this skill until ALL items are complete. +Write an explicit workflow using the natural structure of the work. Keep common instructions inline, link each branch-specific reference once beside its condition, and delete obsolete files. Frame instructions around the desired behaviour; pair every necessary prohibition with its positive correction. Continue until the complete bundle expresses the designed process. -- [ ] Skill path and frontmatter name match. -- [ ] Used `interrogate` skill to resolve the skill job, use cases, expected inputs, expected outputs, and trigger phrases before drafting. -- [ ] `SKILL.md` contains only essential workflow and required sections. -- [ ] Skill wording is concise, no-fluff, and technically precise. -- [ ] Supporting artefacts are placed under `assets/`, `references/`, or `scripts/` by purpose. -- [ ] Checklist review is complete with blocking issues fixed. -- [ ] Validator has been run against the skill and all errors are fixed. +### Validate -## References +Dry-run every use case through the finished bundle. Confirm that the invocation conditions, branches, rules, references, and postconditions produce the requested process and that each meaning appears once. Exercise executable helpers, run applicable repository checks, and forward-test complex or uncertain behaviour. Apply final lossless compression, then repeat the dry runs until the shortest wording preserves every behaviour and constraint. -Use these references when you need detail. +## Rules -- [assets/skill-template.md](assets/skill-template.md) - Section-by-section authoring template. -- [references/checklist.md](references/checklist.md) - Skill quality and validation checklist. -- [scripts/validate-skill.js](scripts/validate-skill.js) - Bun validator for skill metadata, body limits, and artefacts. +- Keep the authored skill self-contained: place required guidance in its shipped bundle rather than relying on repository-only context. +- Invoke established techniques by their recognised names. Explain only the skill-specific adaptation or constraints. +- Apply DRY to instructions and definitions, YAGNI to speculative branches and files, and lossless compression to the entire bundle. diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml new file mode 100644 index 0000000..879633c --- /dev/null +++ b/skills/write-skill/agents/openai.yaml @@ -0,0 +1,2 @@ +policy: + allow_implicit_invocation: false diff --git a/skills/write-skill/assets/skill-template.md b/skills/write-skill/assets/skill-template.md deleted file mode 100644 index 5d765c4..0000000 --- a/skills/write-skill/assets/skill-template.md +++ /dev/null @@ -1,97 +0,0 @@ -# Skill Authoring Template - -Use for skills written to `.agents/skills/{skill-name}/SKILL.md` unless the user asks for another supported location. - -```markdown ---- -name: {skill-name} -description: {One-line action-oriented summary with the main use case and trigger words early}. Use when {specific trigger context}. ---- - -# {Skill Title} - -{One-line purpose: what repeatable job this skill performs.} - -## Prerequisites - -ALL prerequisites MUST be satisfied BEFORE following this skill. - -- {Only include when the skill must stop, route, or require a condition before work starts.} - -## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. {First required action, including expected inputs when relevant.} -2. {Next required action, including expected outputs and artefacts when relevant.} -3. {Final action that completes the workflow.} - -## Rules - -These rules are MANDATORY. - -- {Durable rule that must always apply, using control words like MUST, DO NOT, NEVER, ONLY, STOP, or ALWAYS.} - -## Completion Gate - -Do NOT leave this skill until ALL items are complete. - -- [ ] {Observable completion check.} - -## Next Steps - -Once the completion gate is fully checked: - -- {Only include when the workflow must route or hand off after completion.} - -## References - -Use these references when you need detail. - -- [references/{file}.md](references/{file}.md) - {Specific purpose.} -``` - -## Section Instructions - -- `name`: use lowercase alphanumeric words joined by single hyphens; match the parent directory exactly. -- `name`: keep to 64 characters or fewer. -- `description`: keep one YAML line, action-oriented, third person, triggerable with `Use when`, `Use for`, or `Use to`. -- `description`: front-load the main use case and trigger words because crowded skill lists can shorten descriptions. -- `description`: validator warns over 200 characters and errors over 300 characters. -- Title: use a short human-readable H1 that matches the workflow, not necessarily the exact `name`. -- One-line purpose: state the repeatable job and outcome in plain language. -- H2 sections must use this canonical order and no other names: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`. -- `## Instructions` and `## References` are required. -- Each included H2 must start with its template intro sentence; extra text may follow on the same line. -- `## Instructions`: name expected inputs, outputs, and artefacts when relevant. -- `## Prerequisites`: optional; include only when conditions can block, redirect, or define valid use. -- `## Rules`: optional; include when durable constraints must override improvisation; use strong UPPERCASE control words like `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`. -- `## Completion Gate`: optional; include when the agent must verify explicit end-state checks before leaving. -- `## Next Steps`: optional; include only when a workflow handoff, routing choice, or post-completion action exists. -- `## References` must be the final H2. -- Reference bullets for artefacts must be exactly `- [path](path) - text`; link text must match href and include the short description. -- Only links in the final `## References` section count for artefact coverage. - -## Prose Style - -- Write commands, not essays: use direct verbs like Load, Check, Run, Fix, Stop, or Return. -- Delete filler, pleasantries, hedging, and setup phrases such as just, really, basically, actually, simply, please, likely, may want to, and happy to. -- Prefer short concrete words over verbose phrasing: use fix instead of implement a solution for, use check instead of perform validation of. -- Preserve exact technical meaning: required keywords, paths, commands, API names, error text, safety warnings, and ordering constraints. -- Use fragments when clear, but expand any sentence where compression could hide a condition, risk, or handoff. - -## Artefact Placement - -- `assets/`: templates, starter files, static examples, images, prompts, resources copied/adapted into outputs. -- `references/`: checklists, rubrics, explanations, examples, and long context outside `SKILL.md`. -- `scripts/`: executable validation, generation, migration, or inspection helpers. -- Prefer instructions over scripts unless deterministic behavior or external tooling is needed; scripts must be self-contained, dependency-light, and actionable. -- Place artefacts directly under `assets/`, `references/`, or `scripts/`; nested artefact paths are not allowed. - -Keep `SKILL.md` around 50 body lines and under 80 body lines. Move detail here or into `references/` instead of expanding the main skill. - -## Validator CLI - -- Run as `bun scripts/validate-skill.js <skill-path>` from the skill directory, or `bun path/to/validate-skill.js <skill-path>` from elsewhere. -- The validator requires exactly one skill directory path, not a file path. -- The validator always writes JSON to stdout and exits non-zero when `valid` is `false`. diff --git a/skills/write-skill/references/FORMAT.md b/skills/write-skill/references/FORMAT.md new file mode 100644 index 0000000..cedadcb --- /dev/null +++ b/skills/write-skill/references/FORMAT.md @@ -0,0 +1,50 @@ +# Propulsion Skill Format + +## Naming + +Use lowercase letters, digits, and hyphens, keep the name within 64 characters, and match the directory name. + +Prefer the shortest command that fits naturally in a user instruction: + +1. One imperative verb: `implement`, `brainstorm`, `review`. +2. A short imperative phrase when its object adds clarity: `write-skill`, `fix-ci`. +3. An established noun when it already names the operation clearly: `pr`. + +## Invocation + +Declare one mode in `metadata.invocation` and keep both client controls in sync: + +| `metadata.invocation` | `disable-model-invocation` | `agents/openai.yaml` | +| --------------------- | -------------------------- | ---------------------------------- | +| `user` | `true` | `allow_implicit_invocation: false` | +| `model` | `false` | `allow_implicit_invocation: true` | + +Default to user invocation. Choose model invocation only for skills expected to run often enough that automatic or cross-skill discovery earns the permanent context cost. + +Write a one-line description that states what the skill does and adds a concise `Use when`, `Use for`, or `Use to` clause: + +- For user invocation, start with `User-invoked` and describe when a human should select it. +- For model invocation, represent every genuine trigger branch once using words users naturally put in prompts. Use the dominant established concept when it is also a real trigger. + +Keep `agents/openai.yaml` limited to the invocation policy unless custom interface presentation has a concrete use case. + +## Body + +Use only the sections the skill needs, in the order the work makes natural. The patterns below are guidance, not a complete schema: + +- `## Prerequisites` verifies conditions whose failure stops the workflow or routes it elsewhere. Put conditions the agent can establish itself in the first step instead, and place genuine prerequisites before the work. +- `## Steps` contains executable work. Use numbering for dependencies, `###` headings for stages or branches, and bullets for independent actions or checks. Make the postcondition of every ordered step observable without requiring a separate label. +- `## Rules` contains invariants that constrain multiple steps or the finished output. Keep a constraint used by one step beside that step. +- `## Handoff` transfers completed work to another skill, person, or later workflow. Keep anything required to finish the current job in the steps. +- Use descriptive sections such as `## Examples` or `## Output` when they organise necessary instructions more clearly. + +Place each reference link once beside the branch or condition that requires it. Keep references one level from `SKILL.md`, and omit a separate reference catalogue. + +## Bundled resources + +- `references/` holds substantial context needed by a real branch. +- `scripts/` holds deterministic operations or code the agent would otherwise recreate repeatedly. Exercise every changed script. +- `assets/` holds files the skill's output consumes or preserves. +- `agents/openai.yaml` holds the Codex invocation policy and any justified interface metadata. + +Apply the Rule of Three before extracting repeated work, except when a fragile operation needs deterministic execution on its first use. Apply YAGNI to empty directories, speculative examples, and unreferenced files. diff --git a/skills/write-skill/references/checklist.md b/skills/write-skill/references/checklist.md deleted file mode 100644 index f920e5d..0000000 --- a/skills/write-skill/references/checklist.md +++ /dev/null @@ -1,76 +0,0 @@ -# Skill Checklist - -Use this checklist before handing off a new or updated skill. - -## Frontmatter - -- [ ] `name` is lowercase with single hyphen separators. -- [ ] `name` is 1-64 characters. -- [ ] `name` matches the parent directory name. -- [ ] `name` matches `^[a-z0-9]+(-[a-z0-9]+)*$`. -- [ ] `description` is one line only. -- [ ] `description` is 200 characters or fewer to avoid validator warnings. -- [ ] `description` is 300 characters or fewer to avoid validator errors. -- [ ] `description` includes what the skill does. -- [ ] `description` includes `Use when`, `Use for`, or `Use to`. -- [ ] `description` front-loads the main use case and trigger words because crowded skill lists can shorten descriptions. -- [ ] `description` includes natural trigger keywords a user would say. -- [ ] `description` is third person and action-oriented. -- [ ] `description` starts with a strong action verb such as Create, Validate, Review, Manage, or Execute. - -## Artefact Layout - -- [ ] Repository skill path defaults to `.agents/skills/{skill-name}/SKILL.md`. -- [ ] `SKILL.md` has required `name` and `description` frontmatter. -- [ ] `assets/` contains only reusable templates or static resources. -- [ ] `references/` contains detailed documentation, examples, rubrics, or checklists. -- [ ] `scripts/` contains only executable helpers and documents how to run them. -- [ ] Scripts are used only when deterministic behavior or external tooling is needed. -- [ ] Scripts are self-contained, dependency-light, and report actionable errors. -- [ ] Artefacts are directly under `assets/`, `references/`, or `scripts/`; no nested artefact paths exist. -- [ ] No unnecessary README, changelog, or duplicate auxiliary files were added. - -## SKILL.md Body - -- [ ] Includes a title and one-line purpose. -- [ ] Includes required `## Instructions` and `## References` sections. -- [ ] Uses only allowed H2 sections: `## Prerequisites`, `## Instructions`, `## Rules`, `## Completion Gate`, `## Next Steps`, `## References`. -- [ ] H2 sections follow the canonical order exactly when present. -- [ ] `## References` is the final H2 section. -- [ ] Each included H2 starts with its required intro sentence from the template; extra text may follow on the same line. -- [ ] Includes `## Prerequisites` when the skill can be invalid, blocked, or must route elsewhere. -- [ ] Includes `## Rules` when durable instructions must always apply. -- [ ] Includes `## Completion Gate` when explicit finish checks are needed. -- [ ] Includes `## Next Steps` when a handoff or post-completion route exists. -- [ ] Uses ordered steps for workflows that must run in sequence. -- [ ] Instructions name expected inputs, outputs, and artefacts when relevant. -- [ ] `## Rules` uses strong control words such as `MUST`, `DO NOT`, `NEVER`, `ONLY`, `STOP`, or `ALWAYS`. -- [ ] Body stays at or below 50 non-empty lines to avoid validator warnings. -- [ ] Body stays at or below 80 non-empty lines to avoid validator errors. - -## Language Quality - -- [ ] Removes filler: just, really, basically, actually, simply. -- [ ] Removes pleasantries/chatty setup: sure, certainly, happy to, please. -- [ ] Removes hedging from required instructions: likely, maybe, should probably, may want to. -- [ ] Replaces verbose phrasing with short direct wording without changing meaning. -- [ ] Preserves exact commands, paths, APIs, error text, safety warnings, conditions, and ordering constraints. - -## Progressive Disclosure - -- [ ] Level 1 metadata is enough to decide whether to load the skill. -- [ ] Level 2 `SKILL.md` contains only essential workflow and durable rules. -- [ ] Level 3 artefacts hold examples, templates, explanations, and long checklists. -- [ ] All linked references resolve from `SKILL.md` using relative paths. -- [ ] Every `assets/`, `references/`, and `scripts/` artefact is linked from the final `## References` section. -- [ ] Reference bullets use exactly `- [path](path) - text`. -- [ ] Reference bullet link text matches the href exactly. -- [ ] Reference bullets include a short description after the separator in `- [path](path) - text`. -- [ ] No orphaned reference, asset, or script files exist. - -## Validation - -- [ ] Manually verify frontmatter, line count, links, and artefact placement. -- [ ] Run the dedicated validator with exactly one skill directory path. -- [ ] Do not pass validator options or a file path. -- [ ] Read validator output as JSON on both success and failure. diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js deleted file mode 100644 index 8de4681..0000000 --- a/skills/write-skill/scripts/validate-skill.js +++ /dev/null @@ -1,426 +0,0 @@ -#!/usr/bin/env bun -import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'; -import { basename, join, relative, resolve } from 'node:path'; - -const args = process.argv.slice(2); -const errors = []; -const warnings = []; -const allowedSections = [ - 'Prerequisites', - 'Instructions', - 'Rules', - 'Completion Gate', - 'Next Steps', - 'References', -]; -const sectionIntroLines = { - Prerequisites: - 'ALL prerequisites MUST be satisfied BEFORE following this skill.', - Instructions: 'Follow these steps IN ORDER. Do NOT skip steps.', - Rules: 'These rules are MANDATORY.', - 'Completion Gate': 'Do NOT leave this skill until ALL items are complete.', - 'Next Steps': 'Once the completion gate is fully checked:', - References: 'Use these references when you need detail.', -}; - -function addError(message) { - errors.push(message); -} - -function addWarning(message) { - warnings.push(message); -} - -function report(path, stats = null) { - return { - path, - valid: errors.length === 0, - errors, - warnings, - stats, - }; -} - -function parseFrontmatter(content) { - const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/); - if (!match) { - addError( - 'Add YAML frontmatter with name and description at the top of SKILL.md.', - ); - return { name: null, description: null, body: content, raw: '' }; - } - - const raw = match[1]; - const name = raw.match(/^name:\s*(.+)$/m)?.[1]?.trim() || null; - const description = readDescription(raw); - - return { name, description, body: content.slice(match[0].length), raw }; -} - -function readDescription(raw) { - const lines = raw.split(/\r?\n/); - const index = lines.findIndex((line) => line.startsWith('description:')); - if (index === -1) return null; - - const firstValue = lines[index].replace(/^description:\s*/, '').trim(); - if (firstValue === '|' || firstValue === '>') { - return lines - .slice(index + 1) - .filter((line) => /^\s+\S/.test(line)) - .map((line) => line.trim()) - .join(' '); - } - - return firstValue || null; -} - -function hasMultilineDescription(raw) { - const lines = raw.split(/\r?\n/); - const index = lines.findIndex((line) => line.startsWith('description:')); - if (index === -1) return false; - const firstValue = lines[index].replace(/^description:\s*/, '').trim(); - if (firstValue === '|' || firstValue === '>') return true; - - return lines.slice(index + 1).some((line) => /^\s+\S/.test(line)); -} - -function validateName(name, dirName) { - if (!name) { - addError( - 'Add frontmatter name and set it to the skill directory name.', - ); - return; - } - if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name)) { - addError( - `Fix frontmatter name "${name}" to match ^[a-z0-9]+(-[a-z0-9]+)*$.`, - ); - } - if (name.length > 64) { - addError( - `Shorten frontmatter name "${name}" to 64 characters or fewer.`, - ); - } - if (name !== dirName) { - addError( - `Set frontmatter name to "${dirName}" so it matches the skill directory.`, - ); - } -} - -function validateDescription(description, raw) { - if (!description) { - addError( - 'Add a one-line frontmatter description with Use when, Use for, or Use to.', - ); - return; - } - if (hasMultilineDescription(raw)) { - addError('Rewrite frontmatter description as a single YAML line.'); - } - if (description.length > 300) { - addError( - `Shorten description to 300 characters or fewer. Current length: ${description.length}.`, - ); - } else if (description.length > 200) { - addWarning( - `Shorten description to 200 characters or fewer for easier skill selection. Current length: ${description.length}.`, - ); - } - if (!/\bUse (when|for|to)\b/.test(description)) { - addError( - 'Add Use when, Use for, or Use to to the one-line description so agents know when to load the skill.', - ); - } - if (/\b(I|me|my|mine|we|us|our|ours)\b/i.test(description)) { - addWarning( - 'Rewrite description in third person; avoid first-person wording like I, me, my, we, or our.', - ); - } - if ( - !/^(Create|Build|Design|Analyze|Test|Validate|Generate|Process|Manage|Execute|Handle|Provide|Review|Write|Author|Migrate|Improve|Add|Update|Check)\b/.test( - description, - ) - ) { - addWarning( - 'Start description with a strong action verb such as Create, Validate, Review, Manage, or Execute.', - ); - } -} - -function validateBody(body) { - const lines = body.split(/\r?\n/); - const nonEmpty = lines - .map((line, index) => ({ line: line.trim(), index })) - .filter(({ line }) => line); - const bodyLines = nonEmpty.length; - - if (bodyLines > 80) { - addError( - `Move detail out of SKILL.md; body has ${bodyLines} non-empty lines and must stay at or below 80.`, - ); - } else if (bodyLines > 50) { - addWarning( - `Move detail out of SKILL.md; body has ${bodyLines} non-empty lines and should stay at or below 50.`, - ); - } - - const first = nonEmpty[0]; - if (!first || !/^#\s+\S/.test(first.line)) { - addError( - 'Make the first non-empty body line an H1 title, for example: # Skill Name.', - ); - } - - const firstH2Index = lines.findIndex((line) => - /^##\s+\S/.test(line.trim()), - ); - const titleIndex = first?.index ?? -1; - const purpose = lines - .slice( - titleIndex + 1, - firstH2Index === -1 ? lines.length : firstH2Index, - ) - .map((line) => line.trim()) - .find((line) => line); - if (!purpose || purpose.startsWith('#')) { - addError( - 'Add one non-empty, non-heading purpose line immediately after the H1 title and before the first H2.', - ); - } - - const h2Sections = nonEmpty - .filter(({ line }) => /^##\s+\S/.test(line)) - .map(({ line, index }) => ({ - title: line.replace(/^##\s+/, '').trim(), - index, - })); - validateSections(h2Sections, lines); - - return { bodyLines, h2Sections: h2Sections.length }; -} - -function validateSections(h2Sections, lines) { - const titles = h2Sections.map(({ title }) => title); - for (const required of ['Instructions', 'References']) { - if (!titles.includes(required)) - addError(`Add required section ## ${required}.`); - } - - let lastAllowedIndex = -1; - for (const title of titles) { - const allowedIndex = allowedSections.indexOf(title); - if (allowedIndex === -1) { - addError( - `Remove unsupported H2 section ## ${title}. Allowed H2 sections are ${allowedSections.map((section) => `## ${section}`).join(', ')}.`, - ); - continue; - } - if (allowedIndex < lastAllowedIndex) { - addError( - `Move ## ${title} before ## ${allowedSections[lastAllowedIndex]} to match the canonical section order.`, - ); - } else { - lastAllowedIndex = allowedIndex; - } - } - - const final = titles[titles.length - 1]; - if (titles.includes('References') && final !== 'References') { - addError('Move ## References to the final H2 section.'); - } - - for (let index = 0; index < h2Sections.length; index++) { - const { title, index: lineIndex } = h2Sections[index]; - const requiredIntro = sectionIntroLines[title]; - if (!requiredIntro) continue; - - const nextSectionIndex = h2Sections[index + 1]?.index ?? lines.length; - const firstContentLine = lines - .slice(lineIndex + 1, nextSectionIndex) - .map((line) => line.trim()) - .find((line) => line); - - if (!firstContentLine?.startsWith(requiredIntro)) { - addError(`Start ## ${title} with: ${requiredIntro}`); - } - } -} - -function collectArtifacts(skillPath) { - const artifacts = []; - for (const dir of ['assets', 'references', 'scripts']) { - const dirPath = join(skillPath, dir); - if (!existsSync(dirPath)) continue; - - for (const entry of readdirSync(dirPath, { withFileTypes: true })) { - const artifactPath = `${dir}/${entry.name}`; - if (entry.isFile()) { - artifacts.push(artifactPath); - continue; - } - if (entry.isDirectory()) { - for (const nested of collectNestedFiles( - join(dirPath, entry.name), - artifactPath, - )) { - addError( - `Move nested artifact ${nested} directly under ${dir}/; nested artifact files are not allowed.`, - ); - } - } - } - } - return artifacts; -} - -function collectNestedFiles(dirPath, prefix) { - const files = []; - for (const entry of readdirSync(dirPath, { withFileTypes: true })) { - const nestedPath = `${prefix}/${entry.name}`; - if (entry.isFile()) files.push(nestedPath); - if (entry.isDirectory()) - files.push( - ...collectNestedFiles(join(dirPath, entry.name), nestedPath), - ); - } - return files; -} - -function finalReferencesSection(body) { - const lines = body.split(/\r?\n/); - const start = lines.findIndex((line) => line.trim() === '## References'); - if (start === -1) return ''; - - const rest = lines.slice(start + 1); - const nextH2 = rest.findIndex((line) => /^##\s+\S/.test(line.trim())); - return (nextH2 === -1 ? rest : rest.slice(0, nextH2)).join('\n'); -} - -function validateArtifacts(skillPath, body) { - const artifacts = collectArtifacts(skillPath); - const linked = new Set(); - const references = finalReferencesSection(body); - const artifactLink = - /\[(assets|references|scripts)\/[^\]]+\]\((assets|references|scripts)\/[^)]+\)/; - - for (const rawLine of references.split(/\r?\n/)) { - const line = rawLine.trimStart(); - if (!artifactLink.test(line)) continue; - - const match = line.match( - /^- \[((?:assets|references|scripts)\/[^\]]+)\]\(((?:assets|references|scripts)\/[^)]+)\) - (.*)$/, - ); - const emptyDescriptionMatch = line.match( - /^- \[((?:assets|references|scripts)\/[^\]]+)\]\(((?:assets|references|scripts)\/[^)]+)\) -\s*$/, - ); - const text = match?.[1]; - const href = match?.[2]; - const description = match?.[3]?.trim(); - const path = href ?? text; - - if ( - !match && - emptyDescriptionMatch?.[1] === emptyDescriptionMatch?.[2] - ) { - linked.add(emptyDescriptionMatch[2]); - addError( - `Add a short description after " - " for artifact reference ${emptyDescriptionMatch[2]}.`, - ); - if (!existsSync(join(skillPath, emptyDescriptionMatch[2]))) { - addError( - `Create linked artifact ${emptyDescriptionMatch[2]} or remove its References bullet.`, - ); - } - continue; - } - - if (!match || text !== href) { - const expected = text ?? path ?? 'artifact/path'; - addError( - `Reference artifact ${expected} with matching text and href: - [${expected}](${expected}) - short description.`, - ); - continue; - } - - linked.add(href); - if (!description) { - addError( - `Add a short description after " - " for artifact reference ${href}.`, - ); - } - if (!existsSync(join(skillPath, href))) { - addError( - `Create linked artifact ${href} or remove its References bullet.`, - ); - } - } - - for (const artifact of artifacts) { - if (!linked.has(artifact)) { - addError( - `Link artifact ${artifact} from the final ## References section.`, - ); - } - } - - return artifacts.length; -} - -function validateSkill(skillPath) { - if (!existsSync(skillPath)) { - addError( - `Create the skill directory or fix the path; not found: ${skillPath}`, - ); - return null; - } - if (!statSync(skillPath).isDirectory()) { - addError(`Provide a skill directory, not a file: ${skillPath}`); - return null; - } - - const skillMdPath = join(skillPath, 'SKILL.md'); - if (!existsSync(skillMdPath)) { - addError('Add SKILL.md to the skill directory.'); - return null; - } - - const content = readFileSync(skillMdPath, 'utf8'); - const { name, description, body, raw } = parseFrontmatter(content); - validateName(name, basename(skillPath)); - validateDescription(description, raw); - const bodyStats = validateBody(body); - const artifacts = validateArtifacts(skillPath, body); - - return { ...bodyStats, artifacts }; -} - -let targetArg = null; -for (const arg of args) { - if (arg.startsWith('--')) { - addError( - `Unsupported option ${arg}. Provide only a skill directory path.`, - ); - } else if (targetArg) { - addError('Provide only one skill directory path.'); - } else { - targetArg = arg; - } -} - -if (!targetArg && errors.length === 0) { - addError( - 'Provide a skill directory path: bun validate-skill.js <skill-path>', - ); -} - -const targetPath = targetArg ? resolve(targetArg) : null; -const stats = - targetPath && errors.length === 0 ? validateSkill(targetPath) : null; -const displayPath = targetPath - ? relative(process.cwd(), targetPath) || targetPath - : null; -const output = report(displayPath, stats); - -console.log(JSON.stringify(output, null, 2)); -process.exit(output.valid ? 0 : 1); diff --git a/tests/codex-hook.test.js b/tests/codex-hook.test.js deleted file mode 100644 index a2cbad0..0000000 --- a/tests/codex-hook.test.js +++ /dev/null @@ -1,111 +0,0 @@ -import { describe, expect, test } from 'bun:test'; -import { readFile } from 'node:fs/promises'; - -import { - PROPULSION_BOOTSTRAP_GUIDANCE, - getPropulsionBootstrapGuidance, -} from '../lib/bootstrap-guidance.js'; - -async function readJson(path) { - return JSON.parse(await readFile(path, 'utf8')); -} - -async function runConfiguredHook(env) { - const config = await readJson('hooks/hooks.json'); - const command = config.hooks.SessionStart[0].hooks[0].command; - - const result = Bun.spawnSync({ - cmd: ['sh', '-c', command], - cwd: '/private/tmp', - env: { - ...process.env, - ...env, - }, - stdout: 'pipe', - stderr: 'pipe', - }); - - expect(result.exitCode).toBe(0); - - const output = new TextDecoder().decode(result.stdout).trim(); - return JSON.parse(output); -} - -describe('Codex Propulsion bootstrap guidance', () => { - test('uses the shared Propulsion bootstrap contract', () => { - expect(getPropulsionBootstrapGuidance()).toBe( - PROPULSION_BOOTSTRAP_GUIDANCE, - ); - }); - - test('registers a plugin-root session-start hook matcher', async () => { - const config = await readJson('hooks/hooks.json'); - - expect(config.hooks.SessionStart).toEqual([ - { - matcher: 'startup|clear|compact|resume', - hooks: [ - { - type: 'command', - command: - '"${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}/hooks/run-hook.cmd" session-start', - timeout: 10, - statusMessage: 'Loading Propulsion workflow', - }, - ], - }, - ]); - }); - - test('runs configured hook command with CODEX_PLUGIN_ROOT', async () => { - const payload = await runConfiguredHook({ - CODEX_PLUGIN_ROOT: process.cwd(), - }); - - expect(payload.hookSpecificOutput).toEqual({ - hookEventName: 'SessionStart', - additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE, - }); - }); - - test('runs configured hook command with CLAUDE_PLUGIN_ROOT fallback', async () => { - const payload = await runConfiguredHook({ - CODEX_PLUGIN_ROOT: '', - CLAUDE_PLUGIN_ROOT: process.cwd(), - }); - - expect(payload.hookSpecificOutput).toEqual({ - hookEventName: 'SessionStart', - additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE, - }); - }); - - test('prints Codex SessionStart additional context as parseable JSON', async () => { - const result = Bun.spawnSync({ - cmd: ['./hooks/run-hook.cmd', 'session-start'], - stdout: 'pipe', - stderr: 'pipe', - }); - - expect(result.exitCode).toBe(0); - - const output = new TextDecoder().decode(result.stdout).trim(); - const payload = JSON.parse(output); - - expect(payload).toEqual({ - hookSpecificOutput: { - hookEventName: 'SessionStart', - additionalContext: PROPULSION_BOOTSTRAP_GUIDANCE, - }, - }); - expect(payload.hookSpecificOutput.additionalContext).toContain( - '<EXTREMELY_IMPORTANT>', - ); - expect(payload.hookSpecificOutput.additionalContext).toContain( - 'Propulsion workflow entry point: load and follow the propulsion skill when the request is software work.', - ); - expect(payload.hookSpecificOutput.additionalContext).toContain( - 'Route software work through Propulsion before downstream stages.', - ); - }); -}); diff --git a/tests/opencode-plugin.test.js b/tests/opencode-plugin.test.js deleted file mode 100644 index ed195d4..0000000 --- a/tests/opencode-plugin.test.js +++ /dev/null @@ -1,117 +0,0 @@ -import { describe, expect, test } from 'bun:test'; -import { readFile } from 'node:fs/promises'; -import { dirname, join } from 'node:path'; -import { fileURLToPath } from 'node:url'; - -import { getPropulsionBootstrapGuidance } from '../lib/bootstrap-guidance.js'; - -describe('OpenCode Propulsion bootstrap guidance', () => { - test('exposes the root package entry for OpenCode package loading', async () => { - const manifest = JSON.parse(await readFile('package.json', 'utf8')); - const rootExports = await import('../index.mjs'); - - expect(manifest.main).toBe('./index.mjs'); - expect(manifest.exports).toBe('./index.mjs'); - expect( - Object.values(rootExports).every( - (value) => - typeof value === 'function' || - (typeof value === 'object' && - value !== null && - typeof value.server === 'function'), - ), - ).toBe(true); - }); - - test('registers bundled skills with OpenCode config', async () => { - const pluginPackage = (await import('../index.mjs')).default; - const PropulsionPlugin = pluginPackage.server; - const hooks = await PropulsionPlugin({}); - const config = {}; - const skillsDir = join( - dirname(fileURLToPath(import.meta.url)), - '..', - 'skills', - ); - - expect(hooks).toEqual( - expect.objectContaining({ - config: expect.any(Function), - }), - ); - - await hooks.config(config); - await hooks.config(config); - - expect(config.skills.paths).toEqual([skillsDir]); - await expect( - readFile(join(skillsDir, 'debug', 'SKILL.md'), 'utf8'), - ).resolves.toContain('# Debug'); - }); - - test('provides high-priority Propulsion routing guidance', () => { - const guidance = getPropulsionBootstrapGuidance(); - - expect(guidance).toContain('<EXTREMELY_IMPORTANT>'); - expect(guidance).toContain('</EXTREMELY_IMPORTANT>'); - expect(guidance).toContain('propulsion'); - expect(guidance).toContain( - 'Route software work through Propulsion before downstream stages.', - ); - expect(guidance).toContain( - 'Route software-work requests into the right Propulsion entry stage before any other action.', - ); - }); - - test('registers an OpenCode messages transform that injects Propulsion guidance into the first user message', async () => { - const pluginPackage = (await import('../index.mjs')).default; - const PropulsionPlugin = pluginPackage.server; - const hooks = await PropulsionPlugin({}); - const userPart = { - id: 'part-user', - type: 'text', - text: 'Build the thing', - }; - const output = { - system: ['existing system prompt'], - messages: [ - { - info: { role: 'assistant' }, - parts: [ - { - id: 'part-assistant', - type: 'text', - text: 'Ready', - }, - ], - }, - { - info: { role: 'user' }, - parts: [userPart], - }, - ], - }; - - expect(hooks).toEqual( - expect.objectContaining({ - 'experimental.chat.messages.transform': expect.any(Function), - }), - ); - expect(hooks).not.toHaveProperty('experimental.chat.system.transform'); - - await hooks['experimental.chat.messages.transform']({}, output); - await hooks['experimental.chat.messages.transform']({}, output); - - expect(output.system).toEqual(['existing system prompt']); - expect(output.messages).toHaveLength(2); - expect(output.messages[0].info.role).toBe('assistant'); - expect(output.messages[1].parts).toEqual([ - { - ...userPart, - type: 'text', - text: getPropulsionBootstrapGuidance(), - }, - userPart, - ]); - }); -}); diff --git a/tests/write-skill-validator.test.js b/tests/write-skill-validator.test.js deleted file mode 100644 index 257bd32..0000000 --- a/tests/write-skill-validator.test.js +++ /dev/null @@ -1,513 +0,0 @@ -import { describe, expect, test } from 'bun:test'; -import { spawnSync } from 'node:child_process'; -import { - existsSync, - mkdirSync, - mkdtempSync, - readdirSync, - writeFileSync, -} from 'node:fs'; -import { tmpdir } from 'node:os'; -import { join } from 'node:path'; - -const repoRoot = join(import.meta.dir, '..'); -const validatorPath = join( - repoRoot, - 'skills/write-skill/scripts/validate-skill.js', -); -const shippedSkillsPath = join(repoRoot, 'skills'); - -function runValidator(args = []) { - const result = spawnSync('bun', [validatorPath, ...args], { - cwd: repoRoot, - encoding: 'utf8', - }); - - return { - ...result, - report: JSON.parse(result.stdout), - }; -} - -function shippedSkillPaths() { - return readdirSync(shippedSkillsPath, { withFileTypes: true }) - .filter((entry) => entry.isDirectory()) - .map((entry) => `skills/${entry.name}`) - .toSorted(); -} - -function validatorOutput(result) { - const details = []; - - if (result.stdout.trim()) { - details.push(`stdout:\n${result.stdout.trim()}`); - } - - if (result.stderr.trim()) { - details.push(`stderr:\n${result.stderr.trim()}`); - } - - return details.join('\n\n') || 'Validator produced no stdout or stderr.'; -} - -function validSkillMd(overrides = {}) { - const name = overrides.name ?? 'good-skill'; - const description = - overrides.description ?? - 'Validate reusable workflow skills. Use when checking authored skill structure.'; - const sections = - overrides.sections ?? - `## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Validate the skill. - -## References - -Use these references when you need detail. -`; - - return `--- -name: ${name} -description: ${description} ---- - -# ${overrides.title ?? 'Good Skill'} - -${overrides.purpose ?? 'Validate reusable skill structure before handoff.'} - -${sections}`; -} - -function createSkill(name, skillMd = validSkillMd({ name }), files = {}) { - const root = mkdtempSync(join(tmpdir(), 'writing-skill-validator-')); - const skillPath = join(root, name); - mkdirSync(skillPath); - writeFileSync(join(skillPath, 'SKILL.md'), skillMd); - - for (const [filePath, content] of Object.entries(files)) { - const parts = filePath.split('/'); - parts.pop(); - if (parts.length > 0) { - mkdirSync(join(skillPath, ...parts), { recursive: true }); - } - writeFileSync(join(skillPath, filePath), content); - } - - return skillPath; -} - -describe('write-skill validator', () => { - test('ships a standalone JavaScript validator', () => { - expect(existsSync(validatorPath)).toBe(true); - }); - - test('requires a skill path and always outputs JSON', () => { - const result = runValidator(); - - expect(result.status).toBe(1); - expect(result.report).toMatchObject({ - path: null, - valid: false, - warnings: [], - stats: null, - }); - expect(result.report.errors).toContain( - 'Provide a skill directory path: bun validate-skill.js <skill-path>', - ); - }); - - test('accepts the write-skill skill as JSON', () => { - const result = runValidator(['skills/write-skill']); - - expect(result.status).toBe(0); - expect(result.report.valid).toBe(true); - expect(result.report).toEqual({ - path: 'skills/write-skill', - valid: true, - errors: [], - warnings: [], - stats: expect.objectContaining({ - bodyLines: expect.any(Number), - artifacts: expect.any(Number), - }), - }); - }); - - test('validates every shipped skill', () => { - const skillPaths = shippedSkillPaths(); - - expect(skillPaths.length).toBeGreaterThan(0); - - for (const skillPath of skillPaths) { - const result = runValidator([skillPath]); - - if (result.status !== 0) { - throw new Error( - `Validator failed for ${skillPath}.\n\n${validatorOutput(result)}`, - ); - } - } - }); - - test('rejects unknown flags instead of supporting legacy options', () => { - const result = runValidator(['--unknown']); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Unsupported option --unknown. Provide only a skill directory path.', - ); - }); - - test('validates name requirements', () => { - const longName = `Bad-${'x'.repeat(65)}`; - const skillPath = createSkill( - 'expected-name', - validSkillMd({ name: longName }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - `Fix frontmatter name "${longName}" to match ^[a-z0-9]+(-[a-z0-9]+)*$.`, - ); - expect(result.report.errors).toContain( - `Shorten frontmatter name "${longName}" to 64 characters or fewer.`, - ); - expect(result.report.errors).toContain( - 'Set frontmatter name to "expected-name" so it matches the skill directory.', - ); - }); - - test('validates description requirements and warnings', () => { - const longFirstPersonDescription = - 'I help agents with reusable skill review language that is intentionally long enough to cross the warning threshold while still remaining under the hard maximum for metadata checks. '.padEnd( - 220, - 'x', - ); - const skillPath = createSkill( - 'description-skill', - validSkillMd({ - name: 'description-skill', - description: longFirstPersonDescription, - }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Add Use when, Use for, or Use to to the one-line description so agents know when to load the skill.', - ); - expect(result.report.warnings).toContain( - 'Shorten description to 200 characters or fewer for easier skill selection. Current length: 220.', - ); - expect(result.report.warnings).toContain( - 'Rewrite description in third person; avoid first-person wording like I, me, my, we, or our.', - ); - expect(result.report.warnings).toContain( - 'Start description with a strong action verb such as Create, Validate, Review, Manage, or Execute.', - ); - }); - - test('errors when description is missing', () => { - const skillPath = createSkill( - 'missing-description', - `--- -name: missing-description ---- - -# Missing Description - -Validate missing description metadata before handoff. - -## Instructions - -1. Validate descriptions. - -## References -`, - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Add a one-line frontmatter description with Use when, Use for, or Use to.', - ); - }); - - test('errors when description is multiline or over 300 chars', () => { - const skillPath = createSkill( - 'description-errors', - `--- -name: description-errors -description: | - ${'Validate metadata. Use when checking descriptions.'.padEnd(301, 'x')} ---- - -# Description Errors - -Validate description metadata before handoff. - -## Instructions - -1. Validate descriptions. - -## References -`, - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Rewrite frontmatter description as a single YAML line.', - ); - expect(result.report.errors).toContain( - 'Shorten description to 300 characters or fewer. Current length: 301.', - ); - }); - - test('validates title, purpose, required sections, heading order, and final references', () => { - const skillPath = createSkill( - 'bad-body', - `--- -name: bad-body -description: Validate skill body structure. Use when checking headings and purpose. ---- - -Intro before title. - -## References - -## Rules - -## Extra -`, - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Make the first non-empty body line an H1 title, for example: # Skill Name.', - ); - expect(result.report.errors).toContain( - 'Add one non-empty, non-heading purpose line immediately after the H1 title and before the first H2.', - ); - expect(result.report.errors).toContain( - 'Add required section ## Instructions.', - ); - expect(result.report.errors).toContain( - 'Remove unsupported H2 section ## Extra. Allowed H2 sections are ## Prerequisites, ## Instructions, ## Rules, ## Completion Gate, ## Next Steps, ## References.', - ); - expect(result.report.errors).toContain( - 'Move ## Rules before ## References to match the canonical section order.', - ); - expect(result.report.errors).toContain( - 'Move ## References to the final H2 section.', - ); - }); - - test('errors when included canonical sections do not start with required intro lines', () => { - const skillPath = createSkill( - 'bad-intros', - validSkillMd({ - name: 'bad-intros', - sections: `## Prerequisites - -## Instructions - -Start with another instruction explanation. - -1. Validate intros. - -## Rules - -Start with another rules explanation. - -- MUST validate intros. - -## Completion Gate - -Start with another completion explanation. - -- [ ] Intros were validated. - -## Next Steps - -Start with another next step explanation. - -- Continue after validation. - -## References - -Start with another reference explanation. -`, - }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Start ## Prerequisites with: ALL prerequisites MUST be satisfied BEFORE following this skill.', - ); - expect(result.report.errors).toContain( - 'Start ## Instructions with: Follow these steps IN ORDER. Do NOT skip steps.', - ); - expect(result.report.errors).toContain( - 'Start ## Rules with: These rules are MANDATORY.', - ); - expect(result.report.errors).toContain( - 'Start ## Completion Gate with: Do NOT leave this skill until ALL items are complete.', - ); - expect(result.report.errors).toContain( - 'Start ## Next Steps with: Once the completion gate is fully checked:', - ); - expect(result.report.errors).toContain( - 'Start ## References with: Use these references when you need detail.', - ); - }); - - test('allows extra text after required intro lines and checks only present sections', () => { - const skillPath = createSkill( - 'extra-intro-text', - validSkillMd({ - name: 'extra-intro-text', - sections: `## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. Extra same-line guidance is allowed. - -1. Validate intros. - -## References - -Use these references when you need detail. Extra same-line guidance is allowed. -`, - }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(0); - expect(result.report.valid).toBe(true); - expect(result.report.errors).toEqual([]); - }); - - test('warns over 50 body lines and exits 0 when only warnings exist', () => { - const bodyLines = Array.from( - { length: 44 }, - (_, index) => `Extra body line ${index + 1}`, - ).join('\n'); - const skillPath = createSkill( - 'warning-skill', - validSkillMd({ - name: 'warning-skill', - sections: `## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Validate warnings. - -${bodyLines} - -## References - -Use these references when you need detail. -`, - }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(0); - expect(result.report.valid).toBe(true); - expect(result.report.warnings).toContain( - 'Move detail out of SKILL.md; body has 51 non-empty lines and should stay at or below 50.', - ); - }); - - test('errors over 80 body lines', () => { - const bodyLines = Array.from( - { length: 74 }, - (_, index) => `Extra body line ${index + 1}`, - ).join('\n'); - const skillPath = createSkill( - 'long-skill', - validSkillMd({ - name: 'long-skill', - sections: `## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Validate length. - -${bodyLines} - -## References - -Use these references when you need detail. -`, - }), - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Move detail out of SKILL.md; body has 81 non-empty lines and must stay at or below 80.', - ); - }); - - test('validates artifact placement and final references bullets', () => { - const skillPath = createSkill( - 'artifact-checks', - validSkillMd({ - name: 'artifact-checks', - sections: `## Instructions - -Follow these steps IN ORDER. Do NOT skip steps. - -1. Use [ignored outside references](assets/linked-outside.md). - -## References - -Use these references when you need detail. - -- [assets/template.md](assets/wrong.md) - Template file. -- [references/missing.md](references/missing.md) - Missing file. -- [scripts/helper.js](scripts/helper.js) - -`, - }), - { - 'assets/linked-outside.md': 'outside link only', - 'assets/template.md': 'template', - 'references/nested/example.md': 'nested', - 'scripts/helper.js': 'helper', - }, - ); - - const result = runValidator([skillPath]); - - expect(result.status).toBe(1); - expect(result.report.errors).toContain( - 'Move nested artifact references/nested/example.md directly under references/; nested artifact files are not allowed.', - ); - expect(result.report.errors).toContain( - 'Reference artifact assets/template.md with matching text and href: - [assets/template.md](assets/template.md) - short description.', - ); - expect(result.report.errors).toContain( - 'Create linked artifact references/missing.md or remove its References bullet.', - ); - expect(result.report.errors).toContain( - 'Add a short description after " - " for artifact reference scripts/helper.js.', - ); - expect(result.report.errors).toContain( - 'Link artifact assets/linked-outside.md from the final ## References section.', - ); - }); -}); From e45d933bbeb3d38f72652629e7e5af7ffc7b25c5 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 14:50:44 +0100 Subject: [PATCH 02/52] Reset --- package.json | 2 +- skills/write-skill/SKILL.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/package.json b/package.json index 7485c6e..6186184 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "checks": "bun run lint && bun run format", "format": "oxfmt .", "format:check": "oxfmt --check .", - "lint": "oxlint", + "lint": "oxlint" }, "devDependencies": { "oxfmt": "^0.44.0", diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 570d8db..07db5d5 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -22,7 +22,7 @@ Read the complete skill bundle, direct references, callers, and reported failure ### Design -Read [the skill format](references/FORMAT.md), then choose the name, invocation policy, description, structure, and bundled resources. Select one dominant established concept that identifies the skill's technique; add another only when it governs a distinct concern. Give fragile work narrow degrees of freedom and judgement-heavy work explicit boundaries. Finish when every use case has a route and every ordered step has a clear postcondition. +Read [the skill format](references/FORMAT.md), then choose the name, invocation policy, description, structure, and bundled resources. Choose one dominant **leading word** grounded in a proven methodology or technique from sources including, but not limited to, The Pragmatic Programmer, Martin Fowler, Robert C. Martin's Clean Code, The Mythical Man-Month, Code Complete, or The Art of Computer Programming. It must be recognised terminology that invokes the agent's existing knowledge; add another only when it governs a distinct concern. Give fragile work narrow degrees of freedom and judgement-heavy work explicit boundaries. Finish when every use case has a route and every ordered step has a clear postcondition. ### Write @@ -35,5 +35,4 @@ Dry-run every use case through the finished bundle. Confirm that the invocation ## Rules - Keep the authored skill self-contained: place required guidance in its shipped bundle rather than relying on repository-only context. -- Invoke established techniques by their recognised names. Explain only the skill-specific adaptation or constraints. - Apply DRY to instructions and definitions, YAGNI to speculative branches and files, and lossless compression to the entire bundle. From 6ae5a4ffcb3033bd0be8eedf23202506e29186f1 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 17:28:25 +0100 Subject: [PATCH 03/52] Reset --- .agents/skills/domain-modeling/ADR-FORMAT.md | 47 -- .../skills/domain-modeling/CONTEXT-FORMAT.md | 60 --- .agents/skills/domain-modeling/SKILL.md | 74 ---- .agents/skills/grill-with-docs/SKILL.md | 7 - .agents/skills/grilling/SKILL.md | 12 - AGENTS.md | 2 + CONTEXT.md | 64 ++- SKILLS_PLAN.md | 419 ++++++++++++++++++ .../0001-use-a-fixed-local-ticket-tracker.md | 3 + ...ose-skills-without-a-mandatory-pipeline.md | 3 + package.json | 2 +- skills/write-skill/SKILL.md | 38 -- skills/write-skill/agents/openai.yaml | 2 - skills/write-skill/references/FORMAT.md | 50 --- 14 files changed, 491 insertions(+), 292 deletions(-) delete mode 100644 .agents/skills/domain-modeling/ADR-FORMAT.md delete mode 100644 .agents/skills/domain-modeling/CONTEXT-FORMAT.md delete mode 100644 .agents/skills/domain-modeling/SKILL.md delete mode 100644 .agents/skills/grill-with-docs/SKILL.md delete mode 100644 .agents/skills/grilling/SKILL.md create mode 100644 SKILLS_PLAN.md create mode 100644 docs/adr/0001-use-a-fixed-local-ticket-tracker.md create mode 100644 docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md delete mode 100644 skills/write-skill/SKILL.md delete mode 100644 skills/write-skill/agents/openai.yaml delete mode 100644 skills/write-skill/references/FORMAT.md diff --git a/.agents/skills/domain-modeling/ADR-FORMAT.md b/.agents/skills/domain-modeling/ADR-FORMAT.md deleted file mode 100644 index da7e78e..0000000 --- a/.agents/skills/domain-modeling/ADR-FORMAT.md +++ /dev/null @@ -1,47 +0,0 @@ -# ADR Format - -ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc. - -Create the `docs/adr/` directory lazily — only when the first ADR is needed. - -## Template - -```md -# {Short title of the decision} - -{1-3 sentences: what's the context, what did we decide, and why.} -``` - -That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections. - -## Optional sections - -Only include these when they add genuine value. Most ADRs won't need them. - -- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited -- **Considered Options** — only when the rejected alternatives are worth remembering -- **Consequences** — only when non-obvious downstream effects need to be called out - -## Numbering - -Scan `docs/adr/` for the highest existing number and increment by one. - -## When to offer an ADR - -All three of these must be true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing." - -### What qualifies - -- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres." -- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP." -- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out. -- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s. -- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate. -- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract." -- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months. diff --git a/.agents/skills/domain-modeling/CONTEXT-FORMAT.md b/.agents/skills/domain-modeling/CONTEXT-FORMAT.md deleted file mode 100644 index eaf2a18..0000000 --- a/.agents/skills/domain-modeling/CONTEXT-FORMAT.md +++ /dev/null @@ -1,60 +0,0 @@ -# CONTEXT.md Format - -## Structure - -```md -# {Context Name} - -{One or two sentence description of what this context is and why it exists.} - -## Language - -**Order**: -{A one or two sentence description of the term} -_Avoid_: Purchase, transaction - -**Invoice**: -A request for payment sent to a customer after delivery. -_Avoid_: Bill, payment request - -**Customer**: -A person or organization that places orders. -_Avoid_: Client, buyer, account -``` - -## Rules - -- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`. -- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. -- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. -- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine. - -## Single vs multi-context repos - -**Single context (most repos):** One `CONTEXT.md` at the repo root. - -**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other: - -```md -# Context Map - -## Contexts - -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping - -## Relationships - -- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking -- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices -- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money` -``` - -The skill infers which structure applies: - -- If `CONTEXT-MAP.md` exists, read it to find contexts -- If only a root `CONTEXT.md` exists, single context -- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved - -When multiple contexts exist, infer which one the current topic relates to. If unclear, ask. diff --git a/.agents/skills/domain-modeling/SKILL.md b/.agents/skills/domain-modeling/SKILL.md deleted file mode 100644 index d0f7e1a..0000000 --- a/.agents/skills/domain-modeling/SKILL.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: domain-modeling -description: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model. ---- - -# Domain Modeling - -Actively build and sharpen the project's domain model as you design. This is the *active* discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.) - -## File structure - -Most repos have a single context: - -``` -/ -├── CONTEXT.md -├── docs/ -│ └── adr/ -│ ├── 0001-event-sourced-orders.md -│ └── 0002-postgres-for-write-model.md -└── src/ -``` - -If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives: - -``` -/ -├── CONTEXT-MAP.md -├── docs/ -│ └── adr/ ← system-wide decisions -├── src/ -│ ├── ordering/ -│ │ ├── CONTEXT.md -│ │ └── docs/adr/ ← context-specific decisions -│ └── billing/ -│ ├── CONTEXT.md -│ └── docs/adr/ -``` - -Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed. - -## During the session - -### Challenge against the glossary - -When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?" - -### Sharpen fuzzy language - -When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things." - -### Discuss concrete scenarios - -When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts. - -### Cross-reference with code - -When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?" - -### Update CONTEXT.md inline - -When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). - -`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else. - -### Offer ADRs sparingly - -Only offer to create an ADR when all three are true: - -1. **Hard to reverse** — the cost of changing your mind later is meaningful -2. **Surprising without context** — a future reader will wonder "why did they do it this way?" -3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons - -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). diff --git a/.agents/skills/grill-with-docs/SKILL.md b/.agents/skills/grill-with-docs/SKILL.md deleted file mode 100644 index bed05d2..0000000 --- a/.agents/skills/grill-with-docs/SKILL.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -name: grill-with-docs -description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go. -disable-model-invocation: true ---- - -Run a `/grilling` session, using the `/domain-modeling` skill. diff --git a/.agents/skills/grilling/SKILL.md b/.agents/skills/grilling/SKILL.md deleted file mode 100644 index 219930f..0000000 --- a/.agents/skills/grilling/SKILL.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: grilling -description: Grill the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases. ---- - -Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer. - -Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering. - -If a *fact* can be found by exploring the codebase, look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer. - -Do not enact the plan until I confirm we have reached a shared understanding. diff --git a/AGENTS.md b/AGENTS.md index 1e63dad..8df8bbb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ - When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. - After implementing changes run `bun run checks` before handoff. - When raising a PR, update `package.json` to the appropriate semantic version for the PR contents and keep mirrored manifest versions in sync. +- Design every skill as an independently invocable, composable capability. Keep orchestration optional and avoid making any skill depend on completing the full workflow. +- Prefer a small set of cohesive skills. Split a responsibility only when it is independently useful, reused by multiple workflows, or requires a distinct invocation policy; avoid one-skill-per-step fragmentation. diff --git a/CONTEXT.md b/CONTEXT.md index afca342..6ab9d8d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -26,6 +26,10 @@ _Avoid_: Invocation flag, frontmatter setting 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 + **Description**: A concise statement of what a skill does and the conditions under which it should be invoked. _Avoid_: Summary, tagline @@ -39,7 +43,7 @@ A distinct route through a skill for a particular use case or condition. Branche _Avoid_: Separate workflow, mode **Leading word**: -An established concept specific enough for the agent to identify the intended technique without additional explanation. A skill explains only its Propulsion-specific adaptation or constraints. +A recognised term from a proven methodology or technique in established literature, specific enough to invoke the agent's existing knowledge without further explanation. A skill explains only its Propulsion-specific adaptation or constraints. _Avoid_: Coined term, theme, slogan **Lossless compression**: @@ -81,3 +85,61 @@ _Avoid_: Background, resource **Dry run**: A semantic validation that traces concrete use cases through a finished skill before handoff. _Avoid_: Checklist, structural validation + +### Work tracking + +**Project**: +A documented initiative that gives a related group of tickets a shared outcome, scope, and constraints. Every ticket belongs to exactly one project through its project key. +_Avoid_: Epic, ticket group + +**Ticket**: +A durable Markdown record of a coherent unit of work, containing the context and completion conditions an agent needs to deliver it. +_Avoid_: Issue, task + +**Ticket tracker**: +The repository-native system that stores tickets in status directories and treats moving a ticket between them as a workflow transition. +_Avoid_: Issue tracker, external tracker + +**Ticket status**: +The current lifecycle state of a ticket, determined solely by the status directory containing its file. The canonical states are `backlog`, `ready`, `in-progress`, `blocked`, `done`, and `cancelled`. +_Avoid_: Frontmatter status, ticket state field + +**Backlog ticket**: +A fully specified, actionable ticket that has been deliberately postponed rather than selected for execution. +_Avoid_: Draft ticket, incomplete ticket + +**Backlog refinement**: +The recurring review that keeps backlog tickets current, ordered, and aligned with project goals, and selects appropriate work for promotion to `ready`. +_Avoid_: Ticket completion, requirements discovery + +**Ready ticket**: +A fully specified, actionable ticket that has been selected for execution and whose blocking dependencies have been completed. +_Avoid_: Todo ticket, open ticket + +**Blocked ticket**: +A selected or in-progress ticket that encounters an unexpected impediment and cannot continue until an explicitly recorded dependency, decision, or external condition is resolved. +_Avoid_: Stalled ticket, paused ticket + +**Done ticket**: +A ticket whose implementation, executable verification, and material review findings are complete. Commit and pull-request state do not affect ticket status. +_Avoid_: Committed ticket, merged ticket + +**Project key**: +A short uppercase identifier that prefixes related ticket IDs so their files remain grouped and recognisable across the ticket tracker. +_Avoid_: Project prefix, namespace + +**Ticket ID**: +The stable identifier formed from a project key and project-local sequence number, such as `CACHE-001`. References use the ticket ID even if the descriptive filename slug changes. +_Avoid_: Filename, ticket number + +**Ticket filename**: +The path-safe representation of a ticket in the form `{PROJECT-KEY}-{SEQUENCE}-{SLUG}.md`, such as `CACHE-001-add-redis-driver.md`. +_Avoid_: Ticket ID, title + +**Ticket estimate**: +An evidence-based relative size on the Fibonacci scale `1, 2, 3, 5, 8`, calibrated without contingency padding. Work above 5 points should be considered for decomposition when it can be split into independently verifiable outcomes. +_Avoid_: Time estimate, deadline, buffer + +**Material review finding**: +An evidence-backed issue whose effect on intent, correctness, security, reliability, or maintainability justifies resolving it before the current implementation is considered complete. +_Avoid_: Nit, optional suggestion diff --git a/SKILLS_PLAN.md b/SKILLS_PLAN.md new file mode 100644 index 0000000..7ac9263 --- /dev/null +++ b/SKILLS_PLAN.md @@ -0,0 +1,419 @@ +# Propulsion Skills Plan + +## Purpose + +This document defines the intended Propulsion engineering workflow and the high-level contract for each skill. It is the shared brief for the agents that will design and implement the individual skill bundles. + +It deliberately stops short of specifying complete prompts, schemas, templates, scripts, or edge-case behaviour. Each skill must still go through the `write-skill` use-case modelling, design, writing, and validation workflow before implementation. + +## Outcome + +Propulsion will be a small suite of predictable, independently useful engineering skills for an individual developer directing a coding agent. The suite should support a natural path from an uncertain idea to verified code and optional Git delivery without making that path mandatory. + +The primary flow is: + +```mermaid +flowchart LR + A["brainstorm"] --> B{"Capture the work?"} + B -->|"Yes"| C["plan-work"] + B -->|"No, build now"| D["implement"] + B -->|"No"| E["Stop with decisions"] + C --> F{"Work now?"} + F -->|"Yes"| D + F -->|"Later"| G["backlog"] + D --> H{"Commit?"} + H -->|"Yes"| I["commit"] + H -->|"No"| J["Working tree"] + I --> K{"Open PR?"} + K -->|"Yes"| L["pr"] +``` + +Every node remains directly invocable. A developer may start with `implement`, `debug`, `review`, `commit`, or any other suitable skill without first traversing the primary flow. + +## Governing principles + +### Predictable process, adaptable outcome + +A skill makes the agent's process predictable without predetermining the result. Fragile operations receive narrow degrees of freedom; judgement-heavy work receives explicit decision boundaries. + +### Composition without coupling + +- Every skill must be useful when invoked alone. +- Orchestrating skills may invoke supporting skills, but the full workflow is never a prerequisite. +- Handoffs are optional routes offered after the current skill has satisfied its own postconditions. +- User intent determines whether the workflow continues to tickets, implementation, commits, or a pull request. + +### Cohesive boundaries + +Prefer the smallest cohesive suite, not the largest number of reusable fragments. Extract a responsibility only when it is independently useful, reused by multiple workflows, requires a distinct invocation policy, or is fragile enough to need its own guardrails. + +Repository exploration, project creation, ticket creation, and refactoring do not currently justify separate skills. They remain steps or branches inside the skills that own their outcomes. + +### Methodology, not cargo cult + +Each skill must choose one dominant established method that governs its process. Add another only when it governs a distinct concern. Use recognised terminology as a leading word and explain only the Propulsion-specific adaptation or constraint. + +Repository evidence and explicit user intent outrank generic advice. Sources such as _Clean Code_ are inputs rather than unquestionable law; future skill authors must resolve tensions using the concrete problem, project conventions, and the best-fitting engineering principle. + +### Durable context + +Facts discoverable in the repository are looked up rather than asked of the user. Decisions belong to the user. Durable conclusions live in the narrowest appropriate source: code, tests, `CONTEXT.md`, ADRs, project records, tickets, commits, or review documents. + +### Evidence before completion + +Implementation is complete when observable behaviour is implemented, executable verification passes, and no material review findings remain. Commit and pull-request state are separate, optional delivery concerns. + +## Repository contracts + +### Domain documentation + +- A root `CONTEXT.md` is the canonical project glossary. +- ADRs live under `docs/adr/`. +- `CONTEXT.md` contains domain language only, never implementation decisions or specifications. +- ADRs are created sparingly for decisions that are hard to reverse, surprising without context, and the result of a real trade-off. + +### Local ticket tracker + +Propulsion uses a fixed, repository-native Markdown tracker. External tracker adapters and setup workflows are outside the current scope. + +```text +docs/tickets/ +├── projects/ +├── backlog/ +├── ready/ +├── in-progress/ +├── blocked/ +├── done/ +└── cancelled/ +``` + +Directories are created lazily. A ticket's directory is the sole source of truth for its status; status must not be duplicated in frontmatter. + +```mermaid +stateDiagram-v2 + [*] --> backlog: postpone + [*] --> ready: select now + backlog --> ready: select for execution + ready --> in-progress: begin implementation + in-progress --> done: implementation verified + in-progress --> blocked: unexpected impediment + blocked --> ready: impediment resolved + backlog --> cancelled + ready --> cancelled + blocked --> cancelled +``` + +#### Status semantics + +- `backlog` contains fully specified, actionable work that has been deliberately postponed. +- `ready` contains fully specified, actionable work selected for execution with completed planned dependencies. +- `in-progress` contains work currently being implemented. +- `blocked` is reserved for an unexpected impediment encountered after selection or commencement. Planned dependency ordering does not make a ticket blocked. +- `done` means implementation, executable verification, and material review findings are complete. It does not mean committed, pushed, merged, or released. +- `cancelled` preserves deliberately abandoned work and its history. + +Outstanding decisions must be resolved by `brainstorm`, `research`, or `prototype` before a ticket is created. The tracker does not contain draft or incomplete tickets. + +#### Projects and ticket identity + +Every ticket belongs to exactly one documented project. Project records use `{PROJECT-KEY}.md`, such as `docs/tickets/projects/CACHE.md`, and hold the shared outcome, scope, constraints, success measures, and durable references that should not be repeated in each ticket. + +Ticket filenames use: + +```text +{PROJECT-KEY}-{SEQUENCE}-{SLUG}.md +``` + +For example, `CACHE-001-add-redis-driver.md` has the stable ticket ID `CACHE-001`. The project-local sequence is allocated by scanning every status directory. References use the stable ID; the descriptive slug may change when the title improves. + +Ticket frontmatter should carry descriptive and planning metadata such as the stable ID, project key, title, priority, estimate, confidence, labels, dependencies, and relevant dates. The exact schema belongs to the `plan-work` design. Ticket bodies must give an implementation agent sufficient context, intended outcome, constraints, acceptance criteria, and validation expectations without prescribing stale file-level implementation details. + +#### Estimation + +Ticket estimates use the Fibonacci scale `1, 2, 3, 5, 8`. Estimates are evidence-based relative sizes, not hours, deadlines, or padded commitments. Complexity, uncertainty, dependencies, integration risk, testing scope, and confidence remain visible rather than being hidden inside a larger number. + +Work above 5 points should be considered for decomposition into independently verifiable vertical slices. An 8 is allowed when the work is genuinely broad or uncertain, but should trigger scrutiny rather than becoming a convenient bucket. + +## Skill catalogue + +| Skill | Invocation | Responsibility | Primary compositions | +| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| `brainstorm` | User | Resolve an idea or decision tree through a relentless one-question-at-a-time interview | `model-domain`, `research`, `prototype`; hands off to `plan-work` or `implement` | +| `model-domain` | Model | Maintain ubiquitous language and qualifying architectural decisions | Used by `brainstorm` and any skill that changes the domain model | +| `research` | Model | Answer an external technical question from high-trust primary sources and record cited findings | Feeds `brainstorm`, `debug`, or `implement` | +| `prototype` | Model | Build the smallest disposable experiment that answers one design question | Feeds conclusions back to `brainstorm` or `implement` | +| `plan-work` | User | Create or update a project and produce one or more fully resolved tickets | Uses `estimate`; hands off to `implement` or the backlog | +| `refine-backlog` | User | Keep actionable postponed work current, ordered, and deliberately promoted | Uses `estimate`; may hand stale decisions to `brainstorm` | +| `estimate` | Model | Size work using evidence-calibrated Fibonacci estimates | Used by `plan-work` and `refine-backlog` | +| `implement` | User | Implement one coherent unit of work from a ticket, conversation, or direct request | Uses `tdd`, `review`, and `verify`; offers `commit` | +| `tdd` | Model | Develop observable behaviour through test-driven vertical slices | Used by `implement` and fix-authorised `debug` | +| `review` | Model | Read a diff against intent and engineering quality, producing prioritised findings | Used by `implement`; may feed findings back to `implement` | +| `verify` | Model | Discover and run relevant executable repository checks and report evidence | Used by `implement`, `debug`, `commit`, `pr`, and `resolve-conflicts` | +| `commit` | User | Turn the intended working-tree scope into coherent atomic commits | May use `verify`; may be invoked by `pr` for PR preparation | +| `pr` | User | Prepare, push, and open a pull request with release metadata and evidence | Uses `commit` and `verify` | +| `debug` | Model | Diagnose hard bugs scientifically and optionally carry an authorised fix through regression coverage | May use `research`, `tdd`, `implement`, and `verify` | +| `audit-architecture` | User | Find structural improvement opportunities and communicate them visually and durably | May hand a selected opportunity to `brainstorm` or `implement` | +| `resolve-conflicts` | Model | Resolve an active merge or rebase by recovering and preserving both intents | Uses tickets, history, and `verify` | +| `write-skill` | User | Create or update a skill through use-case modelling and lossless compression | Governs implementation of every skill in this plan | + +## Skill briefs + +### `brainstorm` + +- **Job:** Sharpen a request, plan, or design by walking its decision tree one question at a time. Every question includes a recommended answer. +- **Inputs:** A user idea plus repository facts discovered by reading the codebase and existing durable documentation. +- **Outputs:** Shared understanding, updated domain language or qualifying ADRs, and an optional handoff to `plan-work`, direct `implement`, or no further action. +- **Boundaries:** It does not create tickets or implement work. It does not ask the user for facts the repository can supply. It must resolve outstanding decisions before offering ticket creation. +- **Methodology:** Socratic questioning, decision trees, concrete scenarios, Evans's ubiquitous language, and Nygard-style ADRs. +- **Design work remaining:** Define completion signals, research/prototype detours, how the interview resumes, and the exact handoff wording. + +### `model-domain` + +- **Job:** Actively sharpen project terminology and record qualifying decisions as the model changes. +- **Inputs:** Existing `CONTEXT.md`, ADRs, code evidence, and a live design discussion. +- **Outputs:** Precise glossary updates and sparse ADRs. +- **Boundaries:** Reading established vocabulary is a normal habit, not a reason to invoke this skill. `CONTEXT.md` remains a glossary rather than a specification or implementation log. +- **Methodology:** Domain-Driven Design, ubiquitous language, bounded contexts when genuinely needed, concrete scenario testing, and lightweight ADRs. +- **Design work remaining:** Adapt the existing format resources to the final skill name and validate single- versus multi-context routing without adding speculative structure. + +### `research` + +- **Job:** Investigate one bounded external question against high-trust primary sources. +- **Inputs:** A precise research question and its relevance to the current engineering decision. +- **Outputs:** A concise, cited Markdown finding that separates evidence, inference, uncertainty, and recommendation. +- **Boundaries:** Research informs a decision; it does not make product decisions or silently implement conclusions. +- **Methodology:** Evidence hierarchy, primary-source research, falsification, and reproducible citations. +- **Design work remaining:** Decide artifact location, source-quality rules, freshness handling, and when ephemeral findings do not warrant a file. + +### `prototype` + +- **Job:** Create the smallest disposable program or interface variation needed to answer one explicit design question. +- **Inputs:** A question that cannot be settled confidently through conversation, code reading, or documentary research. +- **Outputs:** Runnable evidence and a recorded conclusion that can return to `brainstorm` or implementation planning. +- **Boundaries:** Prototype code is throwaway and is not production implementation. The answer survives; accidental architecture does not. +- **Methodology:** Brooks's “plan to throw one away”, technical spikes, evolutionary learning, and rapid feedback. +- **Design work remaining:** Define logic/UI branches, lifecycle and disposal rules, and how validated conclusions are retained without normalising prototype code. + +### `plan-work` + +- **Job:** Turn a resolved conversation or coherent request into a documented project and one or more implementation-ready tickets. +- **Inputs:** Completed decisions, relevant domain documents, repository evidence, and the user's desired timing. +- **Outputs:** A project record plus tickets placed in `backlog` when postponed or `ready` when selected for immediate execution. +- **Boundaries:** It creates no incomplete tickets and does not reopen product discovery. Ambiguity routes back to `brainstorm`. Project and ticket creation are branches of this skill, not separate skills. +- **Methodology:** Pragmatic Programmer tracer bullets, vertical slicing, INVEST-style work-item quality, dependency graphs, and YAGNI. +- **Design work remaining:** Define project and ticket schemas, ticket-ID allocation, duplicate/concurrency handling, dependency representation, and one-ticket versus multi-ticket approval flows. + +### `refine-backlog` + +- **Job:** Keep fully specified postponed work useful and decide which work should become active. +- **Inputs:** Project summaries and backlog ticket metadata, loading full ticket bodies only when required. +- **Outputs:** Updated priority, estimate, dependency, or cancellation decisions and deliberate moves into `ready`. +- **Boundaries:** It does not finish incomplete requirements. Stale or newly ambiguous work routes to `brainstorm` before remaining actionable. +- **Methodology:** Backlog refinement, cost of delay, dependency ordering, WIP discipline, and evidence-based prioritisation. +- **Design work remaining:** Define prioritisation vocabulary, stale-ticket detection, project filtering, and the level of user confirmation required for transitions. + +### `estimate` + +- **Job:** Break down and size engineering work using the developer's existing Fibonacci practice. +- **Inputs:** A single proposed ticket or a larger outcome that may need multiple tickets. +- **Outputs:** `1`, `2`, `3`, `5`, or `8` with confidence, assumptions, dependencies, risks, and concise evidence. +- **Boundaries:** It does not pad for safety or turn points into time commitments. It proposes a split when independent outcomes make that more honest. +- **Methodology:** Fibonacci relative sizing, Planning Poker calibration, disprove-first critique, vertical slicing, and the uncertainty lessons of _The Mythical Man-Month_. +- **Design work remaining:** Adapt the current OpenCode estimator's critique loop, matrices, and single/multi-ticket output branches into a self-contained skill. + +### `implement` + +- **Job:** Implement one coherent unit of work from a ticket, the resolved current conversation, or a direct request. +- **Inputs:** An actionable ticket or sufficiently clear user instruction. Ticket creation is optional. +- **Outputs:** Working code or documentation, appropriate tests, passing verification, no unresolved material review findings, and a completed ticket transition when applicable. +- **Boundaries:** It does not commit or open a PR. It does not force TDD onto non-behavioural documentation, metadata-only work, or disposable prototypes. +- **Methodology:** TDD by default for observable behaviour, tracer-bullet vertical slices, YAGNI, DRY, Code Complete construction discipline, and iterative review. +- **Composition:** For behaviour changes, use `tdd`; then run `review`, implement material findings, and repeat until the material-finding gate is clear; run `verify`; offer `commit` at handoff. +- **Ticket behaviour:** Move `ready` to `in-progress` on commencement and to `done` when implementation, verification, and material review findings are complete. With no ticket, do not create one implicitly. +- **Design work remaining:** Define material-finding severity, loop termination, safe handling of direct requests, ticket failure transitions, and TDD exceptions. + +### `tdd` + +- **Job:** Develop behaviour in small red–green–refactor cycles, one vertical slice at a time. +- **Inputs:** An observable behaviour and a meaningful public seam. +- **Outputs:** Behavioural tests that fail for the intended reason, minimal passing implementation, and local design improvement while green. +- **Boundaries:** Tests describe behaviour rather than implementation. Avoid speculative horizontal test batches, tautological assertions, and mock-heavy tests of internals. +- **Methodology:** Beck's test-driven development, Feathers's seams and characterization tests, tracer bullets, and outside-in behavioural testing. +- **Design work remaining:** Define seam selection, mocking guidance, legacy-code branches, integration-test policy, and the relationship between local refactoring and the wider `review` loop. + +### `review` + +- **Job:** Assess a diff from a pinned fixed point and report evidence-backed findings without modifying code. +- **Inputs:** A diff, its originating intent or ticket, and repository standards. +- **Outputs:** Prioritised findings across two independent axes: intent fidelity and engineering quality. +- **Boundaries:** It remains read-only. Refactoring opportunities are findings implemented later through `implement`; there is no separate `refactor` skill. +- **Methodology:** Fagan inspection, Fowler code smells and refactoring vocabulary, Clean Code and Code Complete practices where applicable, security/performance risk analysis, and spec conformance. +- **Design work remaining:** Define severity and materiality, fixed-point discovery, evidence requirements, false-positive handling, and whether independent axes benefit from separate agents. + +### `verify` + +- **Job:** Produce executable evidence that the relevant repository expectations pass. +- **Inputs:** The changed scope and repository-provided instructions, scripts, CI configuration, and test layout. +- **Outputs:** Commands run, pass/fail evidence, relevant omissions, and a clear verification conclusion. +- **Boundaries:** It does not reason about intent or maintainability like `review`, and it does not fix failures unless the calling request also authorises implementation. +- **Methodology:** Fast feedback loops, continuous integration, test pyramids or test portfolios appropriate to the repository, and fail-fast ordering. +- **Design work remaining:** Define command discovery, targeted versus full checks, smoke-test selection, stale evidence, and failure routing. + +### `commit` + +- **Job:** Convert the intended working-tree scope into one or more coherent atomic commits. +- **Inputs:** The complete diff, repository instructions, relevant ticket/project context, and current verification evidence. +- **Outputs:** Intentional commits with Conventional Commit subjects and useful explanatory bodies when needed. +- **Boundaries:** It preserves unrelated user changes, does not open a PR, and does not treat “commit everything” as permission to combine unrelated concerns. +- **Methodology:** Atomic commits, cohesive change sets, Conventional Commits, and narrative source history. +- **Design work remaining:** Define staging and grouping, user confirmation, verification freshness, amend behaviour, ticket references, and handling of mixed or dirty worktrees. + +### `pr` + +- **Job:** Prepare, push, and open a pull request for committed work. +- **Inputs:** The branch history, target branch, project/ticket context, review findings, and verification evidence. +- **Outputs:** A pushed branch and PR whose Conventional Commit title and body communicate intent, important decisions, validation, and related tickets. +- **Boundaries:** It is explicitly user-invoked. It does not conceal failing checks or unresolved material findings. +- **Repository rule:** Determine the appropriate semantic-version change, synchronize mirrored manifest versions, and use `commit` when PR preparation changes files. +- **Methodology:** Semantic Versioning, Conventional Commits, small reviewable changes, and evidence-rich change descriptions. +- **Design work remaining:** Define version inference, base-branch selection, PR templates, draft policy, push safety, and provider-specific tooling. + +### `debug` + +- **Job:** Diagnose a hard bug or performance regression scientifically and continue to a fix only when authorised. +- **Inputs:** A failure report, observed evidence, and the affected environment. +- **Outputs:** A tight feedback loop, minimized reproduction, ranked and falsified hypotheses, root cause, and either a diagnosis or a regression-covered fix. +- **Boundaries:** Diagnosis-only requests stop before code modification. A fix request may compose `tdd`, `implement`, and `verify`. +- **Methodology:** Scientific method, Zeller-style delta debugging, binary search, instrumentation, hypothesis logs, and regression testing. +- **Design work remaining:** Define deterministic and intermittent branches, feedback-loop thresholds, hypothesis-log persistence, performance diagnosis, and no-reproduction outcomes. + +### `audit-architecture` + +- **Job:** Find structural improvements that make a codebase easier for humans and agents to understand, change, and verify. +- **Inputs:** Repository structure, domain boundaries, dependency relationships, tests, change patterns, and project instructions. +- **Outputs:** A throwaway interactive HTML report for exploration and a durable Markdown architecture review for history. +- **Boundaries:** It remains read-only. A selected opportunity hands off to `brainstorm` when decisions remain or directly to `implement` when the change is already clear. +- **Methodology:** Parnas information hiding, Ousterhout deep modules, Fowler refactoring, Evans bounded contexts, Brooks conceptual integrity, coupling/cohesion, and change amplification. +- **Design work remaining:** Define analysis dimensions, candidate ranking, HTML lifecycle and interaction model, durable report location, and agent-navigability criteria. + +### `resolve-conflicts` + +- **Job:** Complete an active merge or rebase conflict while preserving the intent behind both sides. +- **Inputs:** Conflict state, commits, tickets, PR context, surrounding history, and repository checks. +- **Outputs:** Resolved hunks, completed merge/rebase state, and passing relevant verification. +- **Boundaries:** It does not invent unrelated behaviour or use destructive history operations as shortcuts. +- **Methodology:** Three-way merge reasoning, primary-source intent recovery, semantic conflict resolution, and post-merge verification. +- **Design work remaining:** Define merge versus rebase branches, conflict-source discovery, incompatible-intent escalation, staging/continuation mechanics, and repeated-conflict handling. + +### `write-skill` + +`write-skill` already exists and is the required authoring workflow for every skill above. Its naming, invocation, structure, resource, dry-run, DRY, YAGNI, and lossless-compression rules govern the implementation work. + +## Dependency map + +```mermaid +flowchart TD + BS["brainstorm"] --> MD["model-domain"] + BS --> RS["research"] + BS --> PT["prototype"] + BS --> PW["plan-work"] + BS --> IM["implement"] + + PW --> ES["estimate"] + RB["refine-backlog"] --> ES + RB --> BS + + IM --> TD["tdd"] + IM --> RV["review"] + IM --> VF["verify"] + IM -. "optional handoff" .-> CM["commit"] + + DB["debug"] --> RS + DB --> TD + DB --> IM + DB --> VF + + AA["audit-architecture"] --> BS + AA --> IM + + CM --> VF + PR["pr"] --> CM + PR --> VF + RC["resolve-conflicts"] --> VF +``` + +Arrows show available composition, not mandatory global sequencing. + +## Methodology map + +| Capability | Dominant methods and source traditions | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| Discovery | Socratic questioning, decision trees, concrete scenarios, evidence gathering | +| Domain language | Eric Evans's Domain-Driven Design and ubiquitous language; Michael Nygard's ADR practice | +| Work slicing | _The Pragmatic Programmer_ tracer bullets, vertical slices, INVEST, dependency graphs, YAGNI | +| Estimation | Fibonacci relative sizing, Planning Poker, critique-driven calibration, Brooks on uncertainty and scheduling | +| Implementation | Kent Beck's TDD, tracer bullets, DRY/YAGNI, Steve McConnell's construction discipline | +| Legacy code | Michael Feathers's seams and characterization tests | +| Review | Fagan inspections, Martin Fowler's code smells/refactoring, _Clean Code_, _Code Complete_, repository standards | +| Algorithms | Knuth's emphasis on precise specification, correctness, data structures, and complexity analysis when algorithmic work warrants it | +| Architecture | Parnas information hiding, Ousterhout deep modules, Evans bounded contexts, Brooks conceptual integrity, coupling/cohesion | +| Debugging | Scientific method, delta debugging, binary search, instrumentation, regression tests | +| Delivery | Atomic commits, Conventional Commits, Semantic Versioning, small reviewable changes, continuous integration | +| Prototyping | Brooks's “plan to throw one away” and time-boxed technical spikes | + +These are vocabulary and reasoning tools, not a requirement to cite every source in every skill or reproduce generic book summaries inside skill bundles. + +## Suggested implementation order + +The order below reduces rework by implementing shared supporting capabilities before their orchestrators. It is a recommendation, not a workflow restriction. + +1. **Foundations:** `model-domain`, `estimate`, `tdd`, `review`, `verify`. +2. **Primary flow:** `brainstorm`, `plan-work`, `implement`. +3. **Planning and delivery:** `refine-backlog`, `commit`, `pr`. +4. **Discovery and recovery:** `research`, `prototype`, `debug`, `audit-architecture`, `resolve-conflicts`. + +An agent may work on one skill at a time, but it must read the high-level contracts of direct callers and callees before fixing the boundary. + +## Instructions for skill implementation agents + +For each skill: + +1. Read this plan, the complete `write-skill` bundle, relevant repository instructions, existing domain language, and the briefs for direct callers and callees. +2. Study the corresponding Matt Pocock engineering skill where one exists, plus other acknowledged prior art. Preserve useful techniques, not wording or accidental structure. +3. Run the `write-skill` create branch. Model concrete user prompts, expected behaviour, inputs, outputs, invocation conditions, failure branches, composition points, and constraints before writing files. +4. Select one dominant established method. Verify source terminology where precision matters and state only the Propulsion-specific adaptation. +5. Use the agreed name unless use-case modelling proves it misleading. Any rename must be checked against the full catalogue and `write-skill` naming rules. +6. Apply the invocation policy in this plan and keep frontmatter plus `agents/openai.yaml` synchronized. +7. Keep the bundle self-contained. Add a reference, script, or asset only for a concrete branch; apply the Rule of Three unless a fragile first-use operation needs deterministic automation. +8. Keep common requirements inline and branch-specific detail one link away. Avoid duplicated definitions across skills; the owner named in this plan is the source of truth. +9. Preserve independent invocation. Callers may compose the skill, but the skill must not assume the caller or demand completion of later workflow stages. +10. Dry-run every use case and handoff. Exercise scripts, validate resource links and invocation metadata, then apply lossless compression without removing behaviour. +11. Run `bun run checks` after implementation. When raising a PR, update the semantic version in `package.json` and keep mirrored manifest versions synchronized. +12. Update this plan only when implementation changes a high-level boundary, name, dependency, or governing contract. Low-level implementation detail belongs in the skill bundle. + +## Suite-level acceptance criteria + +The suite is complete when: + +- Every planned skill has explicit use cases, observable postconditions, and validated invocation metadata. +- Every skill works independently and every documented composition route has been dry-run. +- The primary flow supports ticketed and ticketless implementation without forcing commit or PR creation. +- The fixed ticket tracker can create, identify, transition, refine, and complete tickets without conflicting status sources. +- `implement` uses TDD where meaningful, clears material review findings, and produces verification evidence without committing implicitly. +- `commit` and `pr` preserve unrelated work and produce intentional, convention-compliant history. +- `debug`, `audit-architecture`, and `resolve-conflicts` retain their distinct diagnostic or recovery boundaries. +- Methodology terms are applied accurately and only where they improve the skill's process. +- The complete repository passes `bun run checks`. + +## Explicitly deferred + +The following are outside the current individual-developer scope and must not be introduced speculatively: + +- Autonomous Ralph-loop or multi-agent ticket queue runners +- External issue-tracker adapters +- A repository setup/configuration skill +- A conversation handoff skill +- Standalone `explore`, `interrogate`, `create-project`, `create-ticket`, or `refactor` skills +- Mandatory commits, PRs, or tickets in otherwise independent workflows + +Reconsider a deferred capability only after concrete repeated use cases satisfy the same cohesion and reuse tests applied to this catalogue. diff --git a/docs/adr/0001-use-a-fixed-local-ticket-tracker.md b/docs/adr/0001-use-a-fixed-local-ticket-tracker.md new file mode 100644 index 0000000..1a565a4 --- /dev/null +++ b/docs/adr/0001-use-a-fixed-local-ticket-tracker.md @@ -0,0 +1,3 @@ +# Use a fixed local ticket tracker + +Propulsion will standardize on repository-native Markdown projects and tickets under `docs/tickets/`, with ticket status determined by directory location, rather than abstracting over external issue trackers. This sacrifices tracker portability in exchange for predictable agent access, offline operation, reviewable history, and a smaller skill suite with no setup or tracker-adapter workflow. diff --git a/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md b/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md new file mode 100644 index 0000000..caa9885 --- /dev/null +++ b/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md @@ -0,0 +1,3 @@ +# Compose skills without a mandatory pipeline + +Propulsion will provide independently invocable, cohesive skills with optional orchestration rather than enforcing one end-to-end workflow. This may duplicate a small amount of routing language, but it lets an individual developer enter at the appropriate capability, skip unnecessary project-management or Git steps, and combine skills without inheriting unrelated side effects. diff --git a/package.json b/package.json index 6186184..f891d56 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "checks": "bun run lint && bun run format", "format": "oxfmt .", "format:check": "oxfmt --check .", - "lint": "oxlint" + "lint": "oxlint --no-error-on-unmatched-pattern" }, "devDependencies": { "oxfmt": "^0.44.0", diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md deleted file mode 100644 index 07db5d5..0000000 --- a/skills/write-skill/SKILL.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: write-skill -description: User-invoked workflow for predictable agent-skill authoring. Use when creating or updating a skill. -metadata: - invocation: user -disable-model-invocation: true ---- - -A skill makes an agent's process predictable without fixing the outcome. - -## Steps - -Start with the applicable discovery branch, then complete the shared stages. - -### Create — use-case modeling - -Ground the skill in concrete prompts and expected agent behaviour. Identify its job, inputs, outputs, invocation conditions, branches, and constraints until every intended use case has an explicit route. - -### Update — characterization - -Read the complete skill bundle, direct references, callers, and reported failures. Distinguish behaviour that remains intentional or relied upon from obsolete material until every current branch and requested change is accounted for. - -### Design - -Read [the skill format](references/FORMAT.md), then choose the name, invocation policy, description, structure, and bundled resources. Choose one dominant **leading word** grounded in a proven methodology or technique from sources including, but not limited to, The Pragmatic Programmer, Martin Fowler, Robert C. Martin's Clean Code, The Mythical Man-Month, Code Complete, or The Art of Computer Programming. It must be recognised terminology that invokes the agent's existing knowledge; add another only when it governs a distinct concern. Give fragile work narrow degrees of freedom and judgement-heavy work explicit boundaries. Finish when every use case has a route and every ordered step has a clear postcondition. - -### Write - -Write an explicit workflow using the natural structure of the work. Keep common instructions inline, link each branch-specific reference once beside its condition, and delete obsolete files. Frame instructions around the desired behaviour; pair every necessary prohibition with its positive correction. Continue until the complete bundle expresses the designed process. - -### Validate - -Dry-run every use case through the finished bundle. Confirm that the invocation conditions, branches, rules, references, and postconditions produce the requested process and that each meaning appears once. Exercise executable helpers, run applicable repository checks, and forward-test complex or uncertain behaviour. Apply final lossless compression, then repeat the dry runs until the shortest wording preserves every behaviour and constraint. - -## Rules - -- Keep the authored skill self-contained: place required guidance in its shipped bundle rather than relying on repository-only context. -- Apply DRY to instructions and definitions, YAGNI to speculative branches and files, and lossless compression to the entire bundle. diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml deleted file mode 100644 index 879633c..0000000 --- a/skills/write-skill/agents/openai.yaml +++ /dev/null @@ -1,2 +0,0 @@ -policy: - allow_implicit_invocation: false diff --git a/skills/write-skill/references/FORMAT.md b/skills/write-skill/references/FORMAT.md deleted file mode 100644 index cedadcb..0000000 --- a/skills/write-skill/references/FORMAT.md +++ /dev/null @@ -1,50 +0,0 @@ -# Propulsion Skill Format - -## Naming - -Use lowercase letters, digits, and hyphens, keep the name within 64 characters, and match the directory name. - -Prefer the shortest command that fits naturally in a user instruction: - -1. One imperative verb: `implement`, `brainstorm`, `review`. -2. A short imperative phrase when its object adds clarity: `write-skill`, `fix-ci`. -3. An established noun when it already names the operation clearly: `pr`. - -## Invocation - -Declare one mode in `metadata.invocation` and keep both client controls in sync: - -| `metadata.invocation` | `disable-model-invocation` | `agents/openai.yaml` | -| --------------------- | -------------------------- | ---------------------------------- | -| `user` | `true` | `allow_implicit_invocation: false` | -| `model` | `false` | `allow_implicit_invocation: true` | - -Default to user invocation. Choose model invocation only for skills expected to run often enough that automatic or cross-skill discovery earns the permanent context cost. - -Write a one-line description that states what the skill does and adds a concise `Use when`, `Use for`, or `Use to` clause: - -- For user invocation, start with `User-invoked` and describe when a human should select it. -- For model invocation, represent every genuine trigger branch once using words users naturally put in prompts. Use the dominant established concept when it is also a real trigger. - -Keep `agents/openai.yaml` limited to the invocation policy unless custom interface presentation has a concrete use case. - -## Body - -Use only the sections the skill needs, in the order the work makes natural. The patterns below are guidance, not a complete schema: - -- `## Prerequisites` verifies conditions whose failure stops the workflow or routes it elsewhere. Put conditions the agent can establish itself in the first step instead, and place genuine prerequisites before the work. -- `## Steps` contains executable work. Use numbering for dependencies, `###` headings for stages or branches, and bullets for independent actions or checks. Make the postcondition of every ordered step observable without requiring a separate label. -- `## Rules` contains invariants that constrain multiple steps or the finished output. Keep a constraint used by one step beside that step. -- `## Handoff` transfers completed work to another skill, person, or later workflow. Keep anything required to finish the current job in the steps. -- Use descriptive sections such as `## Examples` or `## Output` when they organise necessary instructions more clearly. - -Place each reference link once beside the branch or condition that requires it. Keep references one level from `SKILL.md`, and omit a separate reference catalogue. - -## Bundled resources - -- `references/` holds substantial context needed by a real branch. -- `scripts/` holds deterministic operations or code the agent would otherwise recreate repeatedly. Exercise every changed script. -- `assets/` holds files the skill's output consumes or preserves. -- `agents/openai.yaml` holds the Codex invocation policy and any justified interface metadata. - -Apply the Rule of Three before extracting repeated work, except when a fragile operation needs deterministic execution on its first use. Apply YAGNI to empty directories, speculative examples, and unreferenced files. From 0f8104294f34ab11a9c6c29b77b28456684576a6 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 17:39:23 +0100 Subject: [PATCH 04/52] Reset --- AGENTS.md | 2 -- docs/adr/0001-use-a-fixed-local-ticket-tracker.md | 3 --- docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md | 3 --- 3 files changed, 8 deletions(-) delete mode 100644 docs/adr/0001-use-a-fixed-local-ticket-tracker.md delete mode 100644 docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md diff --git a/AGENTS.md b/AGENTS.md index 8df8bbb..1e63dad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,3 @@ - When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. - After implementing changes run `bun run checks` before handoff. - When raising a PR, update `package.json` to the appropriate semantic version for the PR contents and keep mirrored manifest versions in sync. -- Design every skill as an independently invocable, composable capability. Keep orchestration optional and avoid making any skill depend on completing the full workflow. -- Prefer a small set of cohesive skills. Split a responsibility only when it is independently useful, reused by multiple workflows, or requires a distinct invocation policy; avoid one-skill-per-step fragmentation. diff --git a/docs/adr/0001-use-a-fixed-local-ticket-tracker.md b/docs/adr/0001-use-a-fixed-local-ticket-tracker.md deleted file mode 100644 index 1a565a4..0000000 --- a/docs/adr/0001-use-a-fixed-local-ticket-tracker.md +++ /dev/null @@ -1,3 +0,0 @@ -# Use a fixed local ticket tracker - -Propulsion will standardize on repository-native Markdown projects and tickets under `docs/tickets/`, with ticket status determined by directory location, rather than abstracting over external issue trackers. This sacrifices tracker portability in exchange for predictable agent access, offline operation, reviewable history, and a smaller skill suite with no setup or tracker-adapter workflow. diff --git a/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md b/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md deleted file mode 100644 index caa9885..0000000 --- a/docs/adr/0002-compose-skills-without-a-mandatory-pipeline.md +++ /dev/null @@ -1,3 +0,0 @@ -# Compose skills without a mandatory pipeline - -Propulsion will provide independently invocable, cohesive skills with optional orchestration rather than enforcing one end-to-end workflow. This may duplicate a small amount of routing language, but it lets an individual developer enter at the appropriate capability, skip unnecessary project-management or Git steps, and combine skills without inheriting unrelated side effects. From 41b38dba0de61ebe0448abd5ae95f99faf63ed55 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 19:00:12 +0100 Subject: [PATCH 05/52] Reset --- CONTEXT.md | 58 ------------------------------------------------------ 1 file changed, 58 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 6ab9d8d..c2b7bcb 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -85,61 +85,3 @@ _Avoid_: Background, resource **Dry run**: A semantic validation that traces concrete use cases through a finished skill before handoff. _Avoid_: Checklist, structural validation - -### Work tracking - -**Project**: -A documented initiative that gives a related group of tickets a shared outcome, scope, and constraints. Every ticket belongs to exactly one project through its project key. -_Avoid_: Epic, ticket group - -**Ticket**: -A durable Markdown record of a coherent unit of work, containing the context and completion conditions an agent needs to deliver it. -_Avoid_: Issue, task - -**Ticket tracker**: -The repository-native system that stores tickets in status directories and treats moving a ticket between them as a workflow transition. -_Avoid_: Issue tracker, external tracker - -**Ticket status**: -The current lifecycle state of a ticket, determined solely by the status directory containing its file. The canonical states are `backlog`, `ready`, `in-progress`, `blocked`, `done`, and `cancelled`. -_Avoid_: Frontmatter status, ticket state field - -**Backlog ticket**: -A fully specified, actionable ticket that has been deliberately postponed rather than selected for execution. -_Avoid_: Draft ticket, incomplete ticket - -**Backlog refinement**: -The recurring review that keeps backlog tickets current, ordered, and aligned with project goals, and selects appropriate work for promotion to `ready`. -_Avoid_: Ticket completion, requirements discovery - -**Ready ticket**: -A fully specified, actionable ticket that has been selected for execution and whose blocking dependencies have been completed. -_Avoid_: Todo ticket, open ticket - -**Blocked ticket**: -A selected or in-progress ticket that encounters an unexpected impediment and cannot continue until an explicitly recorded dependency, decision, or external condition is resolved. -_Avoid_: Stalled ticket, paused ticket - -**Done ticket**: -A ticket whose implementation, executable verification, and material review findings are complete. Commit and pull-request state do not affect ticket status. -_Avoid_: Committed ticket, merged ticket - -**Project key**: -A short uppercase identifier that prefixes related ticket IDs so their files remain grouped and recognisable across the ticket tracker. -_Avoid_: Project prefix, namespace - -**Ticket ID**: -The stable identifier formed from a project key and project-local sequence number, such as `CACHE-001`. References use the ticket ID even if the descriptive filename slug changes. -_Avoid_: Filename, ticket number - -**Ticket filename**: -The path-safe representation of a ticket in the form `{PROJECT-KEY}-{SEQUENCE}-{SLUG}.md`, such as `CACHE-001-add-redis-driver.md`. -_Avoid_: Ticket ID, title - -**Ticket estimate**: -An evidence-based relative size on the Fibonacci scale `1, 2, 3, 5, 8`, calibrated without contingency padding. Work above 5 points should be considered for decomposition when it can be split into independently verifiable outcomes. -_Avoid_: Time estimate, deadline, buffer - -**Material review finding**: -An evidence-backed issue whose effect on intent, correctness, security, reliability, or maintainability justifies resolving it before the current implementation is considered complete. -_Avoid_: Nit, optional suggestion From 14d74e4ab749f06915054b2a656b7c38b30f3f67 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 21:43:45 +0100 Subject: [PATCH 06/52] Add skills --- CONTEXT.md | 24 +- SKILLS_PLAN.md | 419 ------------------- package.json | 5 +- scripts/validate-skills.js | 30 ++ skills/elicit/SKILL.md | 40 ++ skills/elicit/agents/openai.yaml | 5 + skills/write-skill/SKILL.md | 137 ++++++ skills/write-skill/agents/openai.yaml | 5 + skills/write-skill/scripts/validate-skill.js | 335 +++++++++++++++ 9 files changed, 573 insertions(+), 427 deletions(-) delete mode 100644 SKILLS_PLAN.md create mode 100644 scripts/validate-skills.js create mode 100644 skills/elicit/SKILL.md create mode 100644 skills/elicit/agents/openai.yaml create mode 100644 skills/write-skill/SKILL.md create mode 100644 skills/write-skill/agents/openai.yaml create mode 100644 skills/write-skill/scripts/validate-skill.js diff --git a/CONTEXT.md b/CONTEXT.md index c2b7bcb..b94f136 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -20,10 +20,18 @@ _Avoid_: Automatic skill 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 +**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 reveals no new material branches, allowing the complete shared understanding to be presented for confirmation. +_Avoid_: Question limit, exhaustive questioning + ### 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. +A skill that guides an agent through creating, reviewing, or improving another skill with an explicit process. It makes execution predictable without prescribing the authored skill's outcome. _Avoid_: Design guide, skill reference **Composable skill**: @@ -43,7 +51,7 @@ A distinct route through a skill for a particular use case or condition. Branche _Avoid_: Separate workflow, mode **Leading word**: -A recognised term from a proven methodology or technique in established literature, specific enough to invoke the agent's existing knowledge without further explanation. A skill explains only its Propulsion-specific adaptation or constraints. +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 **Lossless compression**: @@ -54,8 +62,8 @@ _Avoid_: Trimming, shortening, minimalism 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 -**Positive framing**: -Steering that states the desired behaviour directly. Use a negative instruction only for a necessary hard guardrail and pair it with the corrective behaviour. +**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**: @@ -82,6 +90,10 @@ _Avoid_: Next step, final step Focused supporting documentation linked once beside the condition that requires it and loaded only when that branch is reached. _Avoid_: Background, resource -**Dry run**: -A semantic validation that traces concrete use cases through a finished skill before handoff. +**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/SKILLS_PLAN.md b/SKILLS_PLAN.md deleted file mode 100644 index 7ac9263..0000000 --- a/SKILLS_PLAN.md +++ /dev/null @@ -1,419 +0,0 @@ -# Propulsion Skills Plan - -## Purpose - -This document defines the intended Propulsion engineering workflow and the high-level contract for each skill. It is the shared brief for the agents that will design and implement the individual skill bundles. - -It deliberately stops short of specifying complete prompts, schemas, templates, scripts, or edge-case behaviour. Each skill must still go through the `write-skill` use-case modelling, design, writing, and validation workflow before implementation. - -## Outcome - -Propulsion will be a small suite of predictable, independently useful engineering skills for an individual developer directing a coding agent. The suite should support a natural path from an uncertain idea to verified code and optional Git delivery without making that path mandatory. - -The primary flow is: - -```mermaid -flowchart LR - A["brainstorm"] --> B{"Capture the work?"} - B -->|"Yes"| C["plan-work"] - B -->|"No, build now"| D["implement"] - B -->|"No"| E["Stop with decisions"] - C --> F{"Work now?"} - F -->|"Yes"| D - F -->|"Later"| G["backlog"] - D --> H{"Commit?"} - H -->|"Yes"| I["commit"] - H -->|"No"| J["Working tree"] - I --> K{"Open PR?"} - K -->|"Yes"| L["pr"] -``` - -Every node remains directly invocable. A developer may start with `implement`, `debug`, `review`, `commit`, or any other suitable skill without first traversing the primary flow. - -## Governing principles - -### Predictable process, adaptable outcome - -A skill makes the agent's process predictable without predetermining the result. Fragile operations receive narrow degrees of freedom; judgement-heavy work receives explicit decision boundaries. - -### Composition without coupling - -- Every skill must be useful when invoked alone. -- Orchestrating skills may invoke supporting skills, but the full workflow is never a prerequisite. -- Handoffs are optional routes offered after the current skill has satisfied its own postconditions. -- User intent determines whether the workflow continues to tickets, implementation, commits, or a pull request. - -### Cohesive boundaries - -Prefer the smallest cohesive suite, not the largest number of reusable fragments. Extract a responsibility only when it is independently useful, reused by multiple workflows, requires a distinct invocation policy, or is fragile enough to need its own guardrails. - -Repository exploration, project creation, ticket creation, and refactoring do not currently justify separate skills. They remain steps or branches inside the skills that own their outcomes. - -### Methodology, not cargo cult - -Each skill must choose one dominant established method that governs its process. Add another only when it governs a distinct concern. Use recognised terminology as a leading word and explain only the Propulsion-specific adaptation or constraint. - -Repository evidence and explicit user intent outrank generic advice. Sources such as _Clean Code_ are inputs rather than unquestionable law; future skill authors must resolve tensions using the concrete problem, project conventions, and the best-fitting engineering principle. - -### Durable context - -Facts discoverable in the repository are looked up rather than asked of the user. Decisions belong to the user. Durable conclusions live in the narrowest appropriate source: code, tests, `CONTEXT.md`, ADRs, project records, tickets, commits, or review documents. - -### Evidence before completion - -Implementation is complete when observable behaviour is implemented, executable verification passes, and no material review findings remain. Commit and pull-request state are separate, optional delivery concerns. - -## Repository contracts - -### Domain documentation - -- A root `CONTEXT.md` is the canonical project glossary. -- ADRs live under `docs/adr/`. -- `CONTEXT.md` contains domain language only, never implementation decisions or specifications. -- ADRs are created sparingly for decisions that are hard to reverse, surprising without context, and the result of a real trade-off. - -### Local ticket tracker - -Propulsion uses a fixed, repository-native Markdown tracker. External tracker adapters and setup workflows are outside the current scope. - -```text -docs/tickets/ -├── projects/ -├── backlog/ -├── ready/ -├── in-progress/ -├── blocked/ -├── done/ -└── cancelled/ -``` - -Directories are created lazily. A ticket's directory is the sole source of truth for its status; status must not be duplicated in frontmatter. - -```mermaid -stateDiagram-v2 - [*] --> backlog: postpone - [*] --> ready: select now - backlog --> ready: select for execution - ready --> in-progress: begin implementation - in-progress --> done: implementation verified - in-progress --> blocked: unexpected impediment - blocked --> ready: impediment resolved - backlog --> cancelled - ready --> cancelled - blocked --> cancelled -``` - -#### Status semantics - -- `backlog` contains fully specified, actionable work that has been deliberately postponed. -- `ready` contains fully specified, actionable work selected for execution with completed planned dependencies. -- `in-progress` contains work currently being implemented. -- `blocked` is reserved for an unexpected impediment encountered after selection or commencement. Planned dependency ordering does not make a ticket blocked. -- `done` means implementation, executable verification, and material review findings are complete. It does not mean committed, pushed, merged, or released. -- `cancelled` preserves deliberately abandoned work and its history. - -Outstanding decisions must be resolved by `brainstorm`, `research`, or `prototype` before a ticket is created. The tracker does not contain draft or incomplete tickets. - -#### Projects and ticket identity - -Every ticket belongs to exactly one documented project. Project records use `{PROJECT-KEY}.md`, such as `docs/tickets/projects/CACHE.md`, and hold the shared outcome, scope, constraints, success measures, and durable references that should not be repeated in each ticket. - -Ticket filenames use: - -```text -{PROJECT-KEY}-{SEQUENCE}-{SLUG}.md -``` - -For example, `CACHE-001-add-redis-driver.md` has the stable ticket ID `CACHE-001`. The project-local sequence is allocated by scanning every status directory. References use the stable ID; the descriptive slug may change when the title improves. - -Ticket frontmatter should carry descriptive and planning metadata such as the stable ID, project key, title, priority, estimate, confidence, labels, dependencies, and relevant dates. The exact schema belongs to the `plan-work` design. Ticket bodies must give an implementation agent sufficient context, intended outcome, constraints, acceptance criteria, and validation expectations without prescribing stale file-level implementation details. - -#### Estimation - -Ticket estimates use the Fibonacci scale `1, 2, 3, 5, 8`. Estimates are evidence-based relative sizes, not hours, deadlines, or padded commitments. Complexity, uncertainty, dependencies, integration risk, testing scope, and confidence remain visible rather than being hidden inside a larger number. - -Work above 5 points should be considered for decomposition into independently verifiable vertical slices. An 8 is allowed when the work is genuinely broad or uncertain, but should trigger scrutiny rather than becoming a convenient bucket. - -## Skill catalogue - -| Skill | Invocation | Responsibility | Primary compositions | -| -------------------- | ---------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| `brainstorm` | User | Resolve an idea or decision tree through a relentless one-question-at-a-time interview | `model-domain`, `research`, `prototype`; hands off to `plan-work` or `implement` | -| `model-domain` | Model | Maintain ubiquitous language and qualifying architectural decisions | Used by `brainstorm` and any skill that changes the domain model | -| `research` | Model | Answer an external technical question from high-trust primary sources and record cited findings | Feeds `brainstorm`, `debug`, or `implement` | -| `prototype` | Model | Build the smallest disposable experiment that answers one design question | Feeds conclusions back to `brainstorm` or `implement` | -| `plan-work` | User | Create or update a project and produce one or more fully resolved tickets | Uses `estimate`; hands off to `implement` or the backlog | -| `refine-backlog` | User | Keep actionable postponed work current, ordered, and deliberately promoted | Uses `estimate`; may hand stale decisions to `brainstorm` | -| `estimate` | Model | Size work using evidence-calibrated Fibonacci estimates | Used by `plan-work` and `refine-backlog` | -| `implement` | User | Implement one coherent unit of work from a ticket, conversation, or direct request | Uses `tdd`, `review`, and `verify`; offers `commit` | -| `tdd` | Model | Develop observable behaviour through test-driven vertical slices | Used by `implement` and fix-authorised `debug` | -| `review` | Model | Read a diff against intent and engineering quality, producing prioritised findings | Used by `implement`; may feed findings back to `implement` | -| `verify` | Model | Discover and run relevant executable repository checks and report evidence | Used by `implement`, `debug`, `commit`, `pr`, and `resolve-conflicts` | -| `commit` | User | Turn the intended working-tree scope into coherent atomic commits | May use `verify`; may be invoked by `pr` for PR preparation | -| `pr` | User | Prepare, push, and open a pull request with release metadata and evidence | Uses `commit` and `verify` | -| `debug` | Model | Diagnose hard bugs scientifically and optionally carry an authorised fix through regression coverage | May use `research`, `tdd`, `implement`, and `verify` | -| `audit-architecture` | User | Find structural improvement opportunities and communicate them visually and durably | May hand a selected opportunity to `brainstorm` or `implement` | -| `resolve-conflicts` | Model | Resolve an active merge or rebase by recovering and preserving both intents | Uses tickets, history, and `verify` | -| `write-skill` | User | Create or update a skill through use-case modelling and lossless compression | Governs implementation of every skill in this plan | - -## Skill briefs - -### `brainstorm` - -- **Job:** Sharpen a request, plan, or design by walking its decision tree one question at a time. Every question includes a recommended answer. -- **Inputs:** A user idea plus repository facts discovered by reading the codebase and existing durable documentation. -- **Outputs:** Shared understanding, updated domain language or qualifying ADRs, and an optional handoff to `plan-work`, direct `implement`, or no further action. -- **Boundaries:** It does not create tickets or implement work. It does not ask the user for facts the repository can supply. It must resolve outstanding decisions before offering ticket creation. -- **Methodology:** Socratic questioning, decision trees, concrete scenarios, Evans's ubiquitous language, and Nygard-style ADRs. -- **Design work remaining:** Define completion signals, research/prototype detours, how the interview resumes, and the exact handoff wording. - -### `model-domain` - -- **Job:** Actively sharpen project terminology and record qualifying decisions as the model changes. -- **Inputs:** Existing `CONTEXT.md`, ADRs, code evidence, and a live design discussion. -- **Outputs:** Precise glossary updates and sparse ADRs. -- **Boundaries:** Reading established vocabulary is a normal habit, not a reason to invoke this skill. `CONTEXT.md` remains a glossary rather than a specification or implementation log. -- **Methodology:** Domain-Driven Design, ubiquitous language, bounded contexts when genuinely needed, concrete scenario testing, and lightweight ADRs. -- **Design work remaining:** Adapt the existing format resources to the final skill name and validate single- versus multi-context routing without adding speculative structure. - -### `research` - -- **Job:** Investigate one bounded external question against high-trust primary sources. -- **Inputs:** A precise research question and its relevance to the current engineering decision. -- **Outputs:** A concise, cited Markdown finding that separates evidence, inference, uncertainty, and recommendation. -- **Boundaries:** Research informs a decision; it does not make product decisions or silently implement conclusions. -- **Methodology:** Evidence hierarchy, primary-source research, falsification, and reproducible citations. -- **Design work remaining:** Decide artifact location, source-quality rules, freshness handling, and when ephemeral findings do not warrant a file. - -### `prototype` - -- **Job:** Create the smallest disposable program or interface variation needed to answer one explicit design question. -- **Inputs:** A question that cannot be settled confidently through conversation, code reading, or documentary research. -- **Outputs:** Runnable evidence and a recorded conclusion that can return to `brainstorm` or implementation planning. -- **Boundaries:** Prototype code is throwaway and is not production implementation. The answer survives; accidental architecture does not. -- **Methodology:** Brooks's “plan to throw one away”, technical spikes, evolutionary learning, and rapid feedback. -- **Design work remaining:** Define logic/UI branches, lifecycle and disposal rules, and how validated conclusions are retained without normalising prototype code. - -### `plan-work` - -- **Job:** Turn a resolved conversation or coherent request into a documented project and one or more implementation-ready tickets. -- **Inputs:** Completed decisions, relevant domain documents, repository evidence, and the user's desired timing. -- **Outputs:** A project record plus tickets placed in `backlog` when postponed or `ready` when selected for immediate execution. -- **Boundaries:** It creates no incomplete tickets and does not reopen product discovery. Ambiguity routes back to `brainstorm`. Project and ticket creation are branches of this skill, not separate skills. -- **Methodology:** Pragmatic Programmer tracer bullets, vertical slicing, INVEST-style work-item quality, dependency graphs, and YAGNI. -- **Design work remaining:** Define project and ticket schemas, ticket-ID allocation, duplicate/concurrency handling, dependency representation, and one-ticket versus multi-ticket approval flows. - -### `refine-backlog` - -- **Job:** Keep fully specified postponed work useful and decide which work should become active. -- **Inputs:** Project summaries and backlog ticket metadata, loading full ticket bodies only when required. -- **Outputs:** Updated priority, estimate, dependency, or cancellation decisions and deliberate moves into `ready`. -- **Boundaries:** It does not finish incomplete requirements. Stale or newly ambiguous work routes to `brainstorm` before remaining actionable. -- **Methodology:** Backlog refinement, cost of delay, dependency ordering, WIP discipline, and evidence-based prioritisation. -- **Design work remaining:** Define prioritisation vocabulary, stale-ticket detection, project filtering, and the level of user confirmation required for transitions. - -### `estimate` - -- **Job:** Break down and size engineering work using the developer's existing Fibonacci practice. -- **Inputs:** A single proposed ticket or a larger outcome that may need multiple tickets. -- **Outputs:** `1`, `2`, `3`, `5`, or `8` with confidence, assumptions, dependencies, risks, and concise evidence. -- **Boundaries:** It does not pad for safety or turn points into time commitments. It proposes a split when independent outcomes make that more honest. -- **Methodology:** Fibonacci relative sizing, Planning Poker calibration, disprove-first critique, vertical slicing, and the uncertainty lessons of _The Mythical Man-Month_. -- **Design work remaining:** Adapt the current OpenCode estimator's critique loop, matrices, and single/multi-ticket output branches into a self-contained skill. - -### `implement` - -- **Job:** Implement one coherent unit of work from a ticket, the resolved current conversation, or a direct request. -- **Inputs:** An actionable ticket or sufficiently clear user instruction. Ticket creation is optional. -- **Outputs:** Working code or documentation, appropriate tests, passing verification, no unresolved material review findings, and a completed ticket transition when applicable. -- **Boundaries:** It does not commit or open a PR. It does not force TDD onto non-behavioural documentation, metadata-only work, or disposable prototypes. -- **Methodology:** TDD by default for observable behaviour, tracer-bullet vertical slices, YAGNI, DRY, Code Complete construction discipline, and iterative review. -- **Composition:** For behaviour changes, use `tdd`; then run `review`, implement material findings, and repeat until the material-finding gate is clear; run `verify`; offer `commit` at handoff. -- **Ticket behaviour:** Move `ready` to `in-progress` on commencement and to `done` when implementation, verification, and material review findings are complete. With no ticket, do not create one implicitly. -- **Design work remaining:** Define material-finding severity, loop termination, safe handling of direct requests, ticket failure transitions, and TDD exceptions. - -### `tdd` - -- **Job:** Develop behaviour in small red–green–refactor cycles, one vertical slice at a time. -- **Inputs:** An observable behaviour and a meaningful public seam. -- **Outputs:** Behavioural tests that fail for the intended reason, minimal passing implementation, and local design improvement while green. -- **Boundaries:** Tests describe behaviour rather than implementation. Avoid speculative horizontal test batches, tautological assertions, and mock-heavy tests of internals. -- **Methodology:** Beck's test-driven development, Feathers's seams and characterization tests, tracer bullets, and outside-in behavioural testing. -- **Design work remaining:** Define seam selection, mocking guidance, legacy-code branches, integration-test policy, and the relationship between local refactoring and the wider `review` loop. - -### `review` - -- **Job:** Assess a diff from a pinned fixed point and report evidence-backed findings without modifying code. -- **Inputs:** A diff, its originating intent or ticket, and repository standards. -- **Outputs:** Prioritised findings across two independent axes: intent fidelity and engineering quality. -- **Boundaries:** It remains read-only. Refactoring opportunities are findings implemented later through `implement`; there is no separate `refactor` skill. -- **Methodology:** Fagan inspection, Fowler code smells and refactoring vocabulary, Clean Code and Code Complete practices where applicable, security/performance risk analysis, and spec conformance. -- **Design work remaining:** Define severity and materiality, fixed-point discovery, evidence requirements, false-positive handling, and whether independent axes benefit from separate agents. - -### `verify` - -- **Job:** Produce executable evidence that the relevant repository expectations pass. -- **Inputs:** The changed scope and repository-provided instructions, scripts, CI configuration, and test layout. -- **Outputs:** Commands run, pass/fail evidence, relevant omissions, and a clear verification conclusion. -- **Boundaries:** It does not reason about intent or maintainability like `review`, and it does not fix failures unless the calling request also authorises implementation. -- **Methodology:** Fast feedback loops, continuous integration, test pyramids or test portfolios appropriate to the repository, and fail-fast ordering. -- **Design work remaining:** Define command discovery, targeted versus full checks, smoke-test selection, stale evidence, and failure routing. - -### `commit` - -- **Job:** Convert the intended working-tree scope into one or more coherent atomic commits. -- **Inputs:** The complete diff, repository instructions, relevant ticket/project context, and current verification evidence. -- **Outputs:** Intentional commits with Conventional Commit subjects and useful explanatory bodies when needed. -- **Boundaries:** It preserves unrelated user changes, does not open a PR, and does not treat “commit everything” as permission to combine unrelated concerns. -- **Methodology:** Atomic commits, cohesive change sets, Conventional Commits, and narrative source history. -- **Design work remaining:** Define staging and grouping, user confirmation, verification freshness, amend behaviour, ticket references, and handling of mixed or dirty worktrees. - -### `pr` - -- **Job:** Prepare, push, and open a pull request for committed work. -- **Inputs:** The branch history, target branch, project/ticket context, review findings, and verification evidence. -- **Outputs:** A pushed branch and PR whose Conventional Commit title and body communicate intent, important decisions, validation, and related tickets. -- **Boundaries:** It is explicitly user-invoked. It does not conceal failing checks or unresolved material findings. -- **Repository rule:** Determine the appropriate semantic-version change, synchronize mirrored manifest versions, and use `commit` when PR preparation changes files. -- **Methodology:** Semantic Versioning, Conventional Commits, small reviewable changes, and evidence-rich change descriptions. -- **Design work remaining:** Define version inference, base-branch selection, PR templates, draft policy, push safety, and provider-specific tooling. - -### `debug` - -- **Job:** Diagnose a hard bug or performance regression scientifically and continue to a fix only when authorised. -- **Inputs:** A failure report, observed evidence, and the affected environment. -- **Outputs:** A tight feedback loop, minimized reproduction, ranked and falsified hypotheses, root cause, and either a diagnosis or a regression-covered fix. -- **Boundaries:** Diagnosis-only requests stop before code modification. A fix request may compose `tdd`, `implement`, and `verify`. -- **Methodology:** Scientific method, Zeller-style delta debugging, binary search, instrumentation, hypothesis logs, and regression testing. -- **Design work remaining:** Define deterministic and intermittent branches, feedback-loop thresholds, hypothesis-log persistence, performance diagnosis, and no-reproduction outcomes. - -### `audit-architecture` - -- **Job:** Find structural improvements that make a codebase easier for humans and agents to understand, change, and verify. -- **Inputs:** Repository structure, domain boundaries, dependency relationships, tests, change patterns, and project instructions. -- **Outputs:** A throwaway interactive HTML report for exploration and a durable Markdown architecture review for history. -- **Boundaries:** It remains read-only. A selected opportunity hands off to `brainstorm` when decisions remain or directly to `implement` when the change is already clear. -- **Methodology:** Parnas information hiding, Ousterhout deep modules, Fowler refactoring, Evans bounded contexts, Brooks conceptual integrity, coupling/cohesion, and change amplification. -- **Design work remaining:** Define analysis dimensions, candidate ranking, HTML lifecycle and interaction model, durable report location, and agent-navigability criteria. - -### `resolve-conflicts` - -- **Job:** Complete an active merge or rebase conflict while preserving the intent behind both sides. -- **Inputs:** Conflict state, commits, tickets, PR context, surrounding history, and repository checks. -- **Outputs:** Resolved hunks, completed merge/rebase state, and passing relevant verification. -- **Boundaries:** It does not invent unrelated behaviour or use destructive history operations as shortcuts. -- **Methodology:** Three-way merge reasoning, primary-source intent recovery, semantic conflict resolution, and post-merge verification. -- **Design work remaining:** Define merge versus rebase branches, conflict-source discovery, incompatible-intent escalation, staging/continuation mechanics, and repeated-conflict handling. - -### `write-skill` - -`write-skill` already exists and is the required authoring workflow for every skill above. Its naming, invocation, structure, resource, dry-run, DRY, YAGNI, and lossless-compression rules govern the implementation work. - -## Dependency map - -```mermaid -flowchart TD - BS["brainstorm"] --> MD["model-domain"] - BS --> RS["research"] - BS --> PT["prototype"] - BS --> PW["plan-work"] - BS --> IM["implement"] - - PW --> ES["estimate"] - RB["refine-backlog"] --> ES - RB --> BS - - IM --> TD["tdd"] - IM --> RV["review"] - IM --> VF["verify"] - IM -. "optional handoff" .-> CM["commit"] - - DB["debug"] --> RS - DB --> TD - DB --> IM - DB --> VF - - AA["audit-architecture"] --> BS - AA --> IM - - CM --> VF - PR["pr"] --> CM - PR --> VF - RC["resolve-conflicts"] --> VF -``` - -Arrows show available composition, not mandatory global sequencing. - -## Methodology map - -| Capability | Dominant methods and source traditions | -| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| Discovery | Socratic questioning, decision trees, concrete scenarios, evidence gathering | -| Domain language | Eric Evans's Domain-Driven Design and ubiquitous language; Michael Nygard's ADR practice | -| Work slicing | _The Pragmatic Programmer_ tracer bullets, vertical slices, INVEST, dependency graphs, YAGNI | -| Estimation | Fibonacci relative sizing, Planning Poker, critique-driven calibration, Brooks on uncertainty and scheduling | -| Implementation | Kent Beck's TDD, tracer bullets, DRY/YAGNI, Steve McConnell's construction discipline | -| Legacy code | Michael Feathers's seams and characterization tests | -| Review | Fagan inspections, Martin Fowler's code smells/refactoring, _Clean Code_, _Code Complete_, repository standards | -| Algorithms | Knuth's emphasis on precise specification, correctness, data structures, and complexity analysis when algorithmic work warrants it | -| Architecture | Parnas information hiding, Ousterhout deep modules, Evans bounded contexts, Brooks conceptual integrity, coupling/cohesion | -| Debugging | Scientific method, delta debugging, binary search, instrumentation, regression tests | -| Delivery | Atomic commits, Conventional Commits, Semantic Versioning, small reviewable changes, continuous integration | -| Prototyping | Brooks's “plan to throw one away” and time-boxed technical spikes | - -These are vocabulary and reasoning tools, not a requirement to cite every source in every skill or reproduce generic book summaries inside skill bundles. - -## Suggested implementation order - -The order below reduces rework by implementing shared supporting capabilities before their orchestrators. It is a recommendation, not a workflow restriction. - -1. **Foundations:** `model-domain`, `estimate`, `tdd`, `review`, `verify`. -2. **Primary flow:** `brainstorm`, `plan-work`, `implement`. -3. **Planning and delivery:** `refine-backlog`, `commit`, `pr`. -4. **Discovery and recovery:** `research`, `prototype`, `debug`, `audit-architecture`, `resolve-conflicts`. - -An agent may work on one skill at a time, but it must read the high-level contracts of direct callers and callees before fixing the boundary. - -## Instructions for skill implementation agents - -For each skill: - -1. Read this plan, the complete `write-skill` bundle, relevant repository instructions, existing domain language, and the briefs for direct callers and callees. -2. Study the corresponding Matt Pocock engineering skill where one exists, plus other acknowledged prior art. Preserve useful techniques, not wording or accidental structure. -3. Run the `write-skill` create branch. Model concrete user prompts, expected behaviour, inputs, outputs, invocation conditions, failure branches, composition points, and constraints before writing files. -4. Select one dominant established method. Verify source terminology where precision matters and state only the Propulsion-specific adaptation. -5. Use the agreed name unless use-case modelling proves it misleading. Any rename must be checked against the full catalogue and `write-skill` naming rules. -6. Apply the invocation policy in this plan and keep frontmatter plus `agents/openai.yaml` synchronized. -7. Keep the bundle self-contained. Add a reference, script, or asset only for a concrete branch; apply the Rule of Three unless a fragile first-use operation needs deterministic automation. -8. Keep common requirements inline and branch-specific detail one link away. Avoid duplicated definitions across skills; the owner named in this plan is the source of truth. -9. Preserve independent invocation. Callers may compose the skill, but the skill must not assume the caller or demand completion of later workflow stages. -10. Dry-run every use case and handoff. Exercise scripts, validate resource links and invocation metadata, then apply lossless compression without removing behaviour. -11. Run `bun run checks` after implementation. When raising a PR, update the semantic version in `package.json` and keep mirrored manifest versions synchronized. -12. Update this plan only when implementation changes a high-level boundary, name, dependency, or governing contract. Low-level implementation detail belongs in the skill bundle. - -## Suite-level acceptance criteria - -The suite is complete when: - -- Every planned skill has explicit use cases, observable postconditions, and validated invocation metadata. -- Every skill works independently and every documented composition route has been dry-run. -- The primary flow supports ticketed and ticketless implementation without forcing commit or PR creation. -- The fixed ticket tracker can create, identify, transition, refine, and complete tickets without conflicting status sources. -- `implement` uses TDD where meaningful, clears material review findings, and produces verification evidence without committing implicitly. -- `commit` and `pr` preserve unrelated work and produce intentional, convention-compliant history. -- `debug`, `audit-architecture`, and `resolve-conflicts` retain their distinct diagnostic or recovery boundaries. -- Methodology terms are applied accurately and only where they improve the skill's process. -- The complete repository passes `bun run checks`. - -## Explicitly deferred - -The following are outside the current individual-developer scope and must not be introduced speculatively: - -- Autonomous Ralph-loop or multi-agent ticket queue runners -- External issue-tracker adapters -- A repository setup/configuration skill -- A conversation handoff skill -- Standalone `explore`, `interrogate`, `create-project`, `create-ticket`, or `refactor` skills -- Mandatory commits, PRs, or tickets in otherwise independent workflows - -Reconsider a deferred capability only after concrete repeated use cases satisfy the same cohesion and reuse tests applied to this catalogue. diff --git a/package.json b/package.json index f891d56..51de0ea 100644 --- a/package.json +++ b/package.json @@ -4,10 +4,11 @@ "main": "./index.mjs", "exports": "./index.mjs", "scripts": { - "checks": "bun run lint && bun run format", + "checks": "bun run lint && bun run format && bun run validate:skills", "format": "oxfmt .", "format:check": "oxfmt --check .", - "lint": "oxlint --no-error-on-unmatched-pattern" + "lint": "oxlint --no-error-on-unmatched-pattern", + "validate:skills": "bun scripts/validate-skills.js" }, "devDependencies": { "oxfmt": "^0.44.0", diff --git a/scripts/validate-skills.js b/scripts/validate-skills.js new file mode 100644 index 0000000..de37439 --- /dev/null +++ b/scripts/validate-skills.js @@ -0,0 +1,30 @@ +#!/usr/bin/env bun + +import { spawnSync } from 'node:child_process'; +import { readdirSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; + +const skillRoot = fileURLToPath(new URL('../skills/', import.meta.url)); +const validator = fileURLToPath( + new URL('../skills/write-skill/scripts/validate-skill.js', import.meta.url), +); +const skillDirectories = readdirSync(skillRoot, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => + fileURLToPath( + new URL(`${entry.name}/`, new URL('../skills/', import.meta.url)), + ), + ) + .toSorted(); + +let valid = true; + +for (const skillDirectory of skillDirectories) { + const result = spawnSync(process.execPath, [validator, skillDirectory], { + stdio: 'inherit', + }); + + if (result.status !== 0) valid = false; +} + +process.exitCode = valid ? 0 : 1; diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md new file mode 100644 index 0000000..23855e2 --- /dev/null +++ b/skills/elicit/SKILL.md @@ -0,0 +1,40 @@ +--- +name: elicit +description: Elicit shared understanding through research and one-question-at-a-time interviews. Use when requirements, constraints, design choices, or user intent remain unresolved. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Elicit + +**Requirements elicitation** turns an unresolved request into confirmed shared +understanding through environment research and one decision at a time. + +## Steps + +1. Establish the subject, then inspect relevant files, tools, behaviour, and + durable context until discoverable facts for the current branch are known. + Treat existing evidence as current state and the user's answers as intent. +2. Build an internal decision tree of every material outcome, boundary, + dependency, constraint, and success condition. Order prerequisites before + dependent decisions. +3. Take the highest-impact decision whose dependencies are resolved. Ask + exactly one question, give the recommended answer first with a brief reason, + add genuinely viable alternatives when useful, then wait for the user's + answer. +4. Test the answer with concrete scenarios, counterexamples, and edge cases. + Surface conflicts with evidence or earlier decisions for the user to resolve. + Inspect newly relevant facts as the tree develops. +5. Repeat the question and validation loop to **theoretical saturation**, when + further answers reveal no new material branches. +6. Present a concise synthesis of the agreed outcome, boundaries, decisions, + constraints, and success conditions. Ask whether it accurately captures the + shared understanding and complete only after explicit confirmation. + +## Rules + +- Keep downstream action pending until shared understanding is confirmed. +- Return an unconfirmed state when the user pauses, cancels, or redirects the + interview before confirmation. +- Keep each response focused on the single active decision. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml new file mode 100644 index 0000000..0c4c186 --- /dev/null +++ b/skills/elicit/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Elicit' + short_description: 'Reach shared understanding through elicitation' +policy: + allow_implicit_invocation: true diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md new file mode 100644 index 0000000..197e6cc --- /dev/null +++ b/skills/write-skill/SKILL.md @@ -0,0 +1,137 @@ +--- +name: write-skill +description: Create, review, and improve predictable, composable agent skills. Use when writing a new skill or assessing an existing skill's process, structure, or wording. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Write Skill + +**Use-case modelling** creates, reviews, and improves skills whose process is +predictable while their context-sensitive outcomes remain open. + +## Steps + +1. Inspect the request, complete target bundle, discoverable callers, and host + conventions. Select the `Create`, `Review`, or `Improve` branch from the + user's authorised outcome. +2. Follow the selected branch. + +### Create + +1. Invoke `$elicit` to confirm concrete invocations, user goals, inputs, + outputs, preconditions, main flows, branches, failure paths, composition, + permissions, observable postconditions, and the governing approach. Once the + use cases are clear, recall familiar established approaches, recommend one + dominant method with its canonical author or work, and include the user's + choice in the confirmed shared understanding. Add a named principle, theory, + or technique only for a distinct concern; verify a recalled term when its + precision or attribution is uncertain. +2. Choose a short verb-led name through **ubiquitous language** and an invocation + policy whose context cost matches its expected use. Place the bundle using + the established host convention; use `$elicit` when none is discoverable. +3. Map common-path instructions into `SKILL.md`. Add branch-specific resources + only when an elicited use case requires them, with each resource pointer + beside the condition that loads or uses it. +4. Write the complete bundle to the skill contract below. + +### Review + +1. Recover the intended contract from the full bundle, callers, host + conventions, and representative prompts. Invoke `$elicit` only when a + material intent decision remains unresolved. +2. Run [scripts/validate-skill.js](scripts/validate-skill.js) for mechanical + evidence, then assess every rule below against the observable process. +3. Return concise, prioritised findings. For each, name the principle, cite the + evidence and behavioural consequence, and recommend the smallest effective + improvement. Affirm the skill plainly when it already meets the standard. + +### Improve + +1. Complete the `Review` branch, then use **characterization testing** to pin + the existing invocation and process that should survive the change. +2. Invoke `$elicit` for material changes to intent, behaviour, invocation, + composition, or scope. Apply mechanical corrections already authorised by + the request. +3. Update the target and every affected caller while preserving the + characterised contract outside the confirmed change. + +### Validate Create or Improve + +1. Apply **lossless compression** until each remaining word changes behaviour, + preserves a condition, or improves navigation. +2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and exercise every + script added to the bundle until the mechanical contract passes. +3. Use **acceptance testing** to replay every elicited invocation through its + branches, pointers, and postconditions. Repeat writing, compression, and + validation until the latest version passes every scenario and review. +4. For complex or high-risk skills, give a fresh agent only the finished skill + and a realistic request. Evaluate its observed process independently, then + resolve material findings through the same loop. +5. Report created or changed files, validation evidence, acceptance scenarios, + fresh-agent evidence when used, and any remaining uncertainty. + +## Skill Contract + +- Start `SKILL.md` with frontmatter containing `name`, a one-line + `description`, `metadata.invocation`, and `disable-model-invocation`. +- Make `name` identical to its directory, at most 64 lowercase letters, digits, + and single hyphens. Prefer a short verb-led phrase that reads naturally as + `$skill-name` inside a request. +- Keep `description` at most 200 characters. Start with a strong action verb; + state what the skill does in third-person, action-oriented language; front-load + natural trigger terms; and add `Use when`, `Use for`, or `Use to` with its + invocation conditions. +- Make user invocation the default. Select model invocation when the skill is + expected across most relevant work and earns permanent description context. + +| `metadata.invocation` | `disable-model-invocation` | `policy.allow_implicit_invocation` | +| --------------------- | -------------------------- | ---------------------------------- | +| `user` | `true` | `false` | +| `model` | `false` | `true` | + +- Add `agents/openai.yaml` with `interface.display_name`, + `interface.short_description`, and the matching + `policy.allow_implicit_invocation`. +- Follow frontmatter with a human-readable H1 and one concise introductory + paragraph that makes the governing idea and capability obvious. +- Use the fewest semantically ordered sections that make execution and + maintenance predictable. Put genuine entry gates in `## Prerequisites`, + executable work in `## Steps`, skill-wide invariants in `## Rules`, and a + completed transfer in `## Handoff`. Use descriptive sections when they index + necessary instructions more clearly. +- Number dependent work, use `###` headings for stages or branches, and use + bullets for independent actions or checks. End every ordered step in an + observable postcondition through **design by contract**. +- Put conditional knowledge in `references/`, output templates and static files + in `assets/`, and deterministic repeated or fragile operations in `scripts/`. + Link each resource inline from the step or branch that needs it. + +## Rules + +- **Predictability** governs quality: stabilise the process while preserving + valid variation in outcomes. +- Choose one dominant established method that governs the process. Add a named + principle, theory, or technique only for a distinct concern. Prefer familiar + model knowledge, verifying a recalled term when precision matters. +- **Unix philosophy** governs boundaries: one coherent capability, independently + invokable and composable through explicit preconditions and postconditions. +- **Leading words** recruit existing model knowledge. Bold each established + approach where it first governs behaviour and explain only its + context-specific adaptation. Reinvoke it later only when a branch needs the + reminder. +- **Progressive disclosure** keeps common-path instructions in `SKILL.md` and + moves branch-specific detail behind a contextual pointer. +- Calibrate **degrees of freedom** to fragility: exact execution for brittle + operations, bounded choices for preferred patterns, concise principles for + judgement-heavy work. +- **Ironic process theory** favours positive target behaviour. Pair an essential + safety boundary with the safe action that satisfies it. +- **YAGNI** admits resources required by current use cases. A fragile operation + may justify a deterministic script on first use; other resources earn their + place through demonstrated need. +- **DRY** gives every meaning one authoritative location. Callers and contextual + resource pointers reach that source instead of restating it. +- Keep a constraint used by one step beside that step. Put `## Rules` + constraints across multiple steps or the finished output. diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml new file mode 100644 index 0000000..b9abe40 --- /dev/null +++ b/skills/write-skill/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Write Skill' + short_description: 'Create, review, and improve agent skills' +policy: + allow_implicit_invocation: false diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js new file mode 100644 index 0000000..eef830d --- /dev/null +++ b/skills/write-skill/scripts/validate-skill.js @@ -0,0 +1,335 @@ +#!/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 = []; + +function addError(message) { + errors.push(message); +} + +function unquote(value) { + const trimmed = value.trim(); + const first = trimmed.at(0); + const last = trimmed.at(-1); + + if ((first === '"' && last === '"') || (first === "'" && last === "'")) { + return trimmed.slice(1, -1); + } + + return trimmed; +} + +function readTopLevel(raw, key) { + const line = raw + .split(/\r?\n/) + .find((candidate) => candidate.startsWith(`${key}:`)); + + return line ? unquote(line.slice(key.length + 1)) : null; +} + +function readNested(raw, parent, key) { + const lines = raw.split(/\r?\n/); + const parentIndex = lines.findIndex((line) => line === `${parent}:`); + + if (parentIndex === -1) return null; + + for (const line of lines.slice(parentIndex + 1)) { + if (/^\S/.test(line)) break; + + const match = line.match(new RegExp(`^\\s+${key}:\\s*(.+)$`)); + if (match) return unquote(match[1]); + } + + return null; +} + +function parseFrontmatter(content) { + const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/); + + if (!match) { + addError('Add YAML frontmatter at the start of SKILL.md.'); + return { body: content, raw: '' }; + } + + return { + body: content.slice(match[0].length), + raw: match[1], + }; +} + +function validateName(raw, skillPath) { + const name = readTopLevel(raw, 'name'); + + if (!name) { + addError('Add the skill name to frontmatter.'); + return; + } + + if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) { + addError( + `Use lowercase letters, digits, and single hyphens for name: ${name}`, + ); + } + + if (name.length > 64) { + addError(`Keep name at most 64 characters; found ${name.length}.`); + } + + if (name !== basename(skillPath)) { + addError(`Match name "${name}" to directory "${basename(skillPath)}".`); + } +} + +function validateDescription(raw) { + const description = readTopLevel(raw, 'description'); + const descriptionLine = raw + .split(/\r?\n/) + .find((line) => line.startsWith('description:')); + + if (!description) { + addError('Add a one-line description to frontmatter.'); + return; + } + + if (descriptionLine?.match(/^description:\s*[|>]/)) { + addError('Write description on one YAML line.'); + } + + if (description.length > 200) { + addError( + `Keep description at most 200 characters; found ${description.length}.`, + ); + } + + if (!/\bUse (?:when|for|to)\b/.test(description)) { + addError( + 'State invocation conditions with Use when, Use for, or Use to.', + ); + } + + if (/\b(?:I|me|my|mine|we|us|our|ours)\b/i.test(description)) { + addError( + 'Write description in third-person, action-oriented language.', + ); + } +} + +function validateInvocation(raw, openaiRaw) { + const invocation = readNested(raw, 'metadata', 'invocation'); + const disableModel = readTopLevel(raw, 'disable-model-invocation'); + const allowImplicit = readNested( + openaiRaw, + 'policy', + 'allow_implicit_invocation', + ); + + if (!['user', 'model'].includes(invocation)) { + addError('Set metadata.invocation to user or model.'); + return; + } + + const expectedDisable = invocation === 'user' ? 'true' : 'false'; + const expectedImplicit = invocation === 'user' ? 'false' : 'true'; + + if (disableModel !== expectedDisable) { + addError( + `Set disable-model-invocation to ${expectedDisable} for ${invocation} invocation.`, + ); + } + + if (allowImplicit !== expectedImplicit) { + addError( + `Set policy.allow_implicit_invocation to ${expectedImplicit} for ${invocation} invocation.`, + ); + } +} + +function validateOpenaiYaml(skillPath, raw) { + const openaiPath = join(skillPath, 'agents', 'openai.yaml'); + + if (!existsSync(openaiPath)) { + addError('Add agents/openai.yaml.'); + return ''; + } + + const openaiRaw = readFileSync(openaiPath, 'utf8'); + const displayName = readNested(openaiRaw, 'interface', 'display_name'); + const shortDescription = readNested( + openaiRaw, + 'interface', + 'short_description', + ); + + if (!displayName) + addError('Set interface.display_name in agents/openai.yaml.'); + + if (!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}.`, + ); + } + + validateInvocation(raw, openaiRaw); + return openaiRaw; +} + +function validateBody(body) { + const lines = body.split(/\r?\n/); + 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 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.'); + } + + const h2s = lines + .map((line, index) => ({ + index, + title: line.match(/^##\s+(.+)$/)?.[1], + })) + .filter(({ title }) => title); + const sectionIndex = new Map(h2s.map(({ index, title }) => [title, index])); + + if (sectionIndex.has('References')) { + addError( + 'Move each resource pointer beside the step or branch that uses it.', + ); + } + + if (sectionIndex.has('Completion Gate')) { + addError('Express completion through observable step postconditions.'); + } + + const prerequisites = sectionIndex.get('Prerequisites'); + const steps = sectionIndex.get('Steps'); + const handoff = sectionIndex.get('Handoff'); + + if ( + prerequisites !== undefined && + steps !== undefined && + prerequisites > steps + ) { + addError('Place Prerequisites before Steps.'); + } + + if (handoff !== undefined && steps !== undefined && handoff < steps) { + addError('Place Handoff after the completed Steps.'); + } +} + +function collectFiles(directory, prefix) { + if (!existsSync(directory)) return []; + + return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => { + const absolute = join(directory, entry.name); + const relativePath = `${prefix}/${entry.name}`; + + return entry.isDirectory() + ? collectFiles(absolute, relativePath) + : [relativePath]; + }); +} + +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); + + if (!/^(?:references|assets|scripts)\//.test(target)) continue; + + linked.add(target); + if (!existsSync(join(skillPath, normalized))) { + addError(`Create linked resource ${target} or update its pointer.`); + } + } + + for (const resource of resources) { + if (!linked.has(resource)) { + addError( + `Link ${resource} beside the step or branch that uses it.`, + ); + } + } + + return resources.length; +} + +function validateSkill(skillPath) { + if (!existsSync(skillPath)) { + addError(`Provide an existing skill directory: ${skillPath}`); + return null; + } + + if (!statSync(skillPath).isDirectory()) { + addError(`Provide a skill directory: ${skillPath}`); + return null; + } + + const skillFile = join(skillPath, 'SKILL.md'); + if (!existsSync(skillFile)) { + addError('Add SKILL.md to the skill directory.'); + return null; + } + + const content = readFileSync(skillFile, 'utf8'); + const { body, raw } = parseFrontmatter(content); + + validateName(raw, skillPath); + validateDescription(raw); + validateOpenaiYaml(skillPath, raw); + 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 <skill-directory>.'); +} else { + target = resolve(cliArguments[0]); +} + +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; From c307fdfe6d2a5583c14a40163db07d1d3db28659 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 21:48:42 +0100 Subject: [PATCH 07/52] Symlink --- .agents/skills | 1 + 1 file changed, 1 insertion(+) create mode 120000 .agents/skills diff --git a/.agents/skills b/.agents/skills new file mode 120000 index 0000000..42c5394 --- /dev/null +++ b/.agents/skills @@ -0,0 +1 @@ +../skills \ No newline at end of file From adfec87749d93be14543797e2f38c433a1181509 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Mon, 13 Jul 2026 22:46:19 +0100 Subject: [PATCH 08/52] Skills --- .oxfmtrc.json | 6 +- skills/elicit-with-context/SKILL.md | 20 ++++++ skills/elicit-with-context/agents/openai.yaml | 5 ++ skills/maintain-context/SKILL.md | 69 +++++++++++++++++++ skills/maintain-context/agents/openai.yaml | 5 ++ .../maintain-context/assets/adr-template.md | 17 +++++ .../assets/context-template.md | 10 +++ 7 files changed, 127 insertions(+), 5 deletions(-) create mode 100644 skills/elicit-with-context/SKILL.md create mode 100644 skills/elicit-with-context/agents/openai.yaml create mode 100644 skills/maintain-context/SKILL.md create mode 100644 skills/maintain-context/agents/openai.yaml create mode 100644 skills/maintain-context/assets/adr-template.md create mode 100644 skills/maintain-context/assets/context-template.md diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 3528913..398f676 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -1,10 +1,6 @@ { "$schema": "./node_modules/oxfmt/configuration_schema.json", - "ignorePatterns": [ - "node_modules/**", - ".opencode/node_modules/**", - ".agents/**" - ], + "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], "printWidth": 80, "tabWidth": 4, "singleQuote": true, diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md new file mode 100644 index 0000000..c9c0724 --- /dev/null +++ b/skills/elicit-with-context/SKILL.md @@ -0,0 +1,20 @@ +--- +name: elicit-with-context +description: Elicits shared understanding while maintaining project language and decisions. Use for deliberate interviews that should update CONTEXT.md and ADRs. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Elicit with Context + +**Requirements elicitation** resolves a request one decision at a time while +explicit skill composition keeps the project's ubiquitous language current and +records only confirmed architectural decisions. + +## Steps + +1. Invoke `$elicit`, using `$maintain-context` throughout. Persist validated + glossary terms as they resolve, and treat `$elicit`'s final confirmation as + the acceptance boundary for ADRs. The handoff returns the elicitation state, + context files changed, and unresolved language or qualifying decisions. diff --git a/skills/elicit-with-context/agents/openai.yaml b/skills/elicit-with-context/agents/openai.yaml new file mode 100644 index 0000000..ef66b09 --- /dev/null +++ b/skills/elicit-with-context/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Elicit with Context' + short_description: 'Interview while maintaining language and decisions' +policy: + allow_implicit_invocation: false diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md new file mode 100644 index 0000000..47b14b7 --- /dev/null +++ b/skills/maintain-context/SKILL.md @@ -0,0 +1,69 @@ +--- +name: maintain-context +description: Maintains a project's ubiquitous language and architecture decision records. Use when domain terms or consequential codebase decisions emerge or change. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Maintain Context + +**Ubiquitous Language**, from Eric Evans's domain-driven design, keeps project +language rigorous by using, testing, and refining the domain model in everyday +work; concise architecture decision records preserve the consequential choices +that shape the codebase. + +## Steps + +1. Compare domain language in the conversation with the root `CONTEXT.md` and + relevant code. + Challenge vague, overloaded, or conflicting terms immediately, propose one + precise canonical term, and test it with concrete scenarios and edge cases. + Treat code as evidence of current behaviour and the user's confirmed answer + as intent; surface contradictions for resolution. The term is either + validated with the user or remains explicitly unresolved. +2. As soon as a term is validated and agreed, create or update the single root + `CONTEXT.md` using the [context template](assets/context-template.md). Keep + definitions to one or two sentences, add `_Avoid_` only for aliases or + ambiguous alternatives that actually occur, and define domain meaning rather + than implementation, specifications, or general programming concepts. The + glossary reflects each resolved term before the discussion continues. +3. Test an accepted codebase decision against all three ADR 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 only when all three gates pass. The decision is either rejected + as routine or identified as a qualifying architectural decision. + +4. After a qualifying decision is accepted, 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 the file + `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision + first, then only the context and significant ramifications needed to explain + it. The new ADR is brief, accepted, sequentially numbered, and readable from + its filename. +5. When an accepted decision changes, read only the specific ADR it supersedes, + preserve that record, and create a new one. Set the old record's `status` to + `superseded` with a relative `superseded-by` link, and give the new record a + relative `supersedes` link; leave the old decision, context, and ramifications + unchanged. Both records expose the decision history in both directions. +6. Re-read every changed artifact against the resolved language, accepted + decisions, and relevant code evidence, then report the files changed and any + unresolved contradiction. The handoff identifies a consistent durable + record or names the exact uncertainty that prevented one. + +## Rules + +- Persist agreed language immediately; keep inferred or unresolved terms in the + conversation until agreement. +- Keep all ubiquitous language in the single root `CONTEXT.md`. +- Give each domain meaning one glossary entry and each architectural decision + one ADR; link supporting material from its authoritative record. +- Require only `Decision`, `Context`, and `Ramifications` as ADR content + sections, in that order. Frontmatter is reserved for `status` and conditional + supersession links. +- Preserve accepted ADR content as history; express a later choice through a + superseding record. +- Reuse a compatible convention when encountered; surface a conflicting + convention and obtain agreement before moving or reshaping durable records. diff --git a/skills/maintain-context/agents/openai.yaml b/skills/maintain-context/agents/openai.yaml new file mode 100644 index 0000000..b5d50ea --- /dev/null +++ b/skills/maintain-context/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Maintain Context' + short_description: 'Maintain project language and decision records' +policy: + allow_implicit_invocation: true diff --git a/skills/maintain-context/assets/adr-template.md b/skills/maintain-context/assets/adr-template.md new file mode 100644 index 0000000..19c3d8d --- /dev/null +++ b/skills/maintain-context/assets/adr-template.md @@ -0,0 +1,17 @@ +--- +status: accepted +--- + +# {Decision-shaped title} + +## Decision + +{State what was decided and the essential reason first.} + +## Context + +{Explain the problem, forces, and serious alternatives needed to understand the decision.} + +## Ramifications + +{State the significant consequences, trade-offs, and conditions that could trigger reconsideration.} diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md new file mode 100644 index 0000000..4bb0d39 --- /dev/null +++ b/skills/maintain-context/assets/context-template.md @@ -0,0 +1,10 @@ +# {Project Name} Context + +{Describe the project domain and why this language exists in one or two +sentences.} + +## Language + +**{Canonical term}**: +{Define what the term is in one or two sentences.} +_Avoid_: {List observed aliases or ambiguous alternatives; omit when none exist.} From d2018a37ddac4c1c161d984027ce16e58b9f8bc8 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 11:55:16 +0100 Subject: [PATCH 09/52] Skills --- CONTEXT.md | 9 +++ skills/implement/SKILL.md | 56 +++++++++++++++++++ skills/implement/agents/openai.yaml | 5 ++ skills/review/SKILL.md | 86 +++++++++++++++++++++++++++++ skills/review/agents/openai.yaml | 5 ++ skills/tdd/SKILL.md | 84 ++++++++++++++++++++++++++++ skills/tdd/agents/openai.yaml | 5 ++ 7 files changed, 250 insertions(+) create mode 100644 skills/implement/SKILL.md create mode 100644 skills/implement/agents/openai.yaml create mode 100644 skills/review/SKILL.md create mode 100644 skills/review/agents/openai.yaml create mode 100644 skills/tdd/SKILL.md create mode 100644 skills/tdd/agents/openai.yaml diff --git a/CONTEXT.md b/CONTEXT.md index b94f136..de63676 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -38,6 +38,15 @@ _Avoid_: Design guide, skill reference 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 +**Implement skill**: +The user-invoked workflow that uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates review findings until verified 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 to behaviour changes when the repository has a runnable test suite. It uses Test Desiderata to favour valuable tests that respond to behaviour without coupling to code structure. + +**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. + **Description**: A concise statement of what a skill does and the conditions under which it should be invoked. _Avoid_: Summary, tagline diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..f5d3ccc --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,56 @@ +--- +name: implement +description: Implements clear software requests in verified slices with TDD when applicable and a closed review loop. Use when explicitly asked to change code. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Implement + +**Tracer bullets**, from Andrew Hunt and David Thomas's _The Pragmatic +Programmer_, deliver the smallest end-to-end slice and use its feedback to aim +the next one; TDD and review keep each slice safe. + +## Steps + +1. Read the request, repository instructions, relevant context and decisions, + current Git state, and available verification commands. Invoke `$elicit` + before editing when the requested outcome is materially ambiguous; otherwise + record the intended behaviour, authorised scope, acceptance evidence, and + pre-existing changes. The request and its change boundary are explicit. +2. Choose the smallest end-to-end slice that advances the request. Invoke `$tdd` + when the slice changes observable behaviour or fixes a bug and the repository + already has a runnable test suite. For documentation or configuration-only + work without an observable behaviour change, behaviour-preserving refactors, + or repositories without a test suite, implement the smallest change and use + the best existing verification without adding a test harness merely to enable + TDD. The slice passes its targeted verification. +3. Repeat the slice-and-verify loop, running focused tests, type-checking, or + other fast checks regularly. Every requested behaviour and acceptance + condition is implemented without speculative scope. +4. Invoke `$review` with the confirmed request and the exact changes made for + it. Address every in-scope finding in priority order, using `$tdd` for + behavioural corrections when applicable and keeping tests green through + refactors. Invoke `$elicit` when a correction would change agreed behaviour, + a public contract, architecture, or authorised scope; difficulty alone does + not require user intervention. Re-run relevant checks and `$review` until its + latest report has no unresolved in-scope findings. +5. Run the repository's prescribed checks and the full test suite when one + exists. The final verification state is known: available checks pass, or an + exact blocker or unrelated pre-existing failure is reported without claiming + full verification. + +## Rules + +- Preserve pre-existing user changes and keep review and remediation scoped to + the current request. +- Commit or push only when the user explicitly requests that Git operation. +- Prefer the simplest present solution; each abstraction and change must serve + the confirmed request. + +## Handoff + +Report the implemented behaviour and changed files, why TDD did or did not +apply, targeted and final verification evidence, review rounds and remediated +findings, and any unresolved blocker or uncertainty. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml new file mode 100644 index 0000000..e509f4b --- /dev/null +++ b/skills/implement/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Implement' + short_description: 'Implement clear requests through verified review loops' +policy: + allow_implicit_invocation: false diff --git a/skills/review/SKILL.md b/skills/review/SKILL.md new file mode 100644 index 0000000..0add926 --- /dev/null +++ b/skills/review/SKILL.md @@ -0,0 +1,86 @@ +--- +name: review +description: Reviews scoped code changes for requirements, code health, and refactor opportunities. Use when assessing a diff, branch, pull request, or completed implementation. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Review + +Google's **code health** standard governs whether a change improves the system; +independent requirements and code-health passes prevent one concern from +masking the other. + +## Steps + +1. Resolve the change scope in this order: an explicit fixed point or caller + scope, uncommitted tracked and untracked changes, then the current branch + from its default-branch merge base. Confirm any revision exists and the + change set is non-empty; ask the user only when multiple scopes remain + plausible. Recover the originating + request from caller context, a supplied specification or ticket, then the + change description and commit history. If none exists, state that the + Requirements pass has no source instead of inventing one. The exact diff and + available requirements source are pinned. +2. Read repository instructions, relevant context and decisions, documented + standards, changed files in full, nearby tests, and any code needed to judge + effects. Treat surrounding code as context while keeping findings limited to + the scoped change. Both reviewers receive the same evidence and boundaries. +3. Run two fresh independent passes in parallel when the host supports + delegation; otherwise perform the passes separately without allowing one to + suppress or reprioritise the other: + - **Requirements** compares the diff with the confirmed request and reports + missing, partial, incorrect, or unrequested behaviour and relevant edge + cases. + - **Code health** examines design, correctness, complexity, tests, naming, + documentation, security, performance, reliability, and repository + standards where relevant. Assess changed tests for behavioural sensitivity, + structure insensitivity, specificity, and determinism. Use Martin Fowler's + **code smells** from _Refactoring_ to investigate concrete refactor + opportunities; a smell is a prompt for judgement, not a violation by + itself. + + Each pass returns candidate findings with evidence and does not edit files. + +4. Validate every candidate by trying to disprove it against the scoped diff, + full context, requirements, and repository standards. Run targeted + non-mutating tests, type-checking, linting, or other checks when they can + settle a claim. Discard preferences, unsupported speculation, unrelated + pre-existing debt, and issues already enforced by tooling. Every remaining + finding is reproducible or directly evidenced. +5. Assign `critical` to immediate data-loss, security, or production failure; + `high` to incorrect requirements or major behaviour, reliability, security, + or maintenance risk; `medium` to a concrete defect or significant code, + design, or test weakness; and `low` to a local but worthwhile improvement. + Every level remains actionable, while inconsequential nits are omitted. The + two axes are ready for transfer without merging or reranking them against + each other. + +## Rules + +- Keep review read-only; return corrections for the caller to implement. +- Prefer technical evidence and documented repository standards over personal + preference. +- Review the changed lines and their effects completely, but report only issues + introduced by or directly relevant to the scoped change. +- Give refactor opportunities the same evidence, priority, and correction + standard as behavioural findings. + +## Handoff + +Return `## Requirements` and `## Code health`. Use `No requirements source.` +when the first axis has no recoverable source and `No findings.` for a clean +axis. Format every finding as: + +```markdown +### [priority] Concise finding + +- Evidence: exact `path:line` and the observed fact +- Consequence: concrete behaviour or code-health impact +- Correction: smallest effective change +``` + +End with `## Summary` containing the finding count for each axis and any check +that could not run. The report contains findings only; a clean report says both +axes have no findings. diff --git a/skills/review/agents/openai.yaml b/skills/review/agents/openai.yaml new file mode 100644 index 0000000..ff8212f --- /dev/null +++ b/skills/review/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Review' + short_description: 'Review scoped code changes with validated evidence' +policy: + allow_implicit_invocation: true diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md new file mode 100644 index 0000000..cd7a2d7 --- /dev/null +++ b/skills/tdd/SKILL.md @@ -0,0 +1,84 @@ +--- +name: tdd +description: Builds observable behaviour through red-green-refactor and Test Desiderata. Use when a feature or bug fix has a runnable test suite. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Test-Driven Development + +**Test-driven development**, from Kent Beck's _Test-Driven Development: By +Example_, builds one behaviour at a time through red, green, and refactor; +**Test Desiderata** governs whether each test is worth keeping. + +## Prerequisites + +- The request changes observable behaviour or fixes a bug. +- The repository already has a runnable test suite. A missing suite makes TDD + inapplicable; use the repository's available verification without installing + a harness solely for this workflow. +- Documentation, configuration-only work, and behaviour-preserving refactors + remain outside TDD unless they also introduce an observable behaviour change. + +## Test Quality + +Assess each test against Beck's Test Desiderata. A test need not maximise every +property, but surrender one only for a property of greater value: + +- **Isolated** and **composable**: order and selection do not change results. +- **Fast** and **automated**: feedback is prompt and needs no intervention. +- **Inspiring** and **predictive**: passing provides proportionate confidence + that the behaviour is suitable for production. +- **Writable** and **readable**: its cost is justified and its motivation is + clear to the next reader. +- **Behavioural** and **structure-insensitive**: behaviour changes affect the + result; rearranging implementation without changing behaviour does not. +- **Specific** and **deterministic**: failure has an obvious cause and unchanged + inputs produce the same result. + +Test through a public interface or stable observable seam. Derive expectations +independently from a requirement, worked example, or known result. For user +interfaces, prefer interactions and outcomes available to a user, such as +accessible roles, names, labels, and visible state. + +Keep CSS classes, incidental DOM shape, private methods, internal collaborator +calls or ordering, broad snapshots, trivial getters, and coverage-padding out +of tests because they do not establish required behaviour. Use test doubles at +uncontrollable system boundaries such as external APIs, time, randomness, and +sometimes persistence; exercise real internal collaborators so refactoring does +not break otherwise valid tests. + +## Steps + +1. Read the request, repository conventions and context, and nearby tests. Run + the smallest relevant existing test set to establish a known baseline. + Record unrelated failures. When a related test already fails for the requested + defect and independently specifies the required behaviour, adopt it as the + Red test; otherwise surface a related failure that prevents a known baseline. + The baseline and the next required behaviour are explicit. +2. Select one smallest behaviour and its most stable observable seam. Infer the + seam from the public contract and ask the user only when viable seams create + a material product or architecture trade-off. For a bug fix, choose a test + that reproduces the defect through that seam. One behaviour and expected + outcome are fixed for the cycle. +3. **Red**: write one test for that behaviour, or use the qualifying failing test + found in the baseline, then run it and confirm it fails for the expected + absence or defect. If it passes or fails for another reason, correct the test + or setup until the failure proves the intended gap. +4. **Green**: write only the production behaviour needed to pass the new test, + then run it and the relevant existing tests. The selected behaviour passes + without regressions or speculative implementation. +5. **Refactor**: while tests are green, improve names, duplication, complexity, + cohesion, or dependencies when a concrete opportunity exists. Make one + behaviour-preserving change at a time and rerun the relevant tests. The code + and tests remain green with worthwhile structure improvements applied. +6. Repeat red-green-refactor for the next behaviour, one test at a time. Finish + by running the complete relevant test set; every required behaviour is + covered by durable passing tests. + +## Handoff + +Report the baseline, behaviours and seams tested, red failures observed, green +commands, refactors performed, final relevant test result, and any unrelated +failure or blocker left for the caller. diff --git a/skills/tdd/agents/openai.yaml b/skills/tdd/agents/openai.yaml new file mode 100644 index 0000000..224675d --- /dev/null +++ b/skills/tdd/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Test-Driven Development' + short_description: 'Build durable tests through red-green-refactor' +policy: + allow_implicit_invocation: true From f32426600b4a8b79adbec382d4d494183bc043c8 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 12:37:24 +0100 Subject: [PATCH 10/52] Skills --- .agents/plugins/marketplace.json | 22 -------------- .codex-plugin/plugin.json | 51 -------------------------------- AGENTS.md | 1 - CONTEXT.md | 4 +++ README.md | 45 ++++++++-------------------- package.json | 4 +-- 6 files changed, 17 insertions(+), 110 deletions(-) delete mode 100644 .agents/plugins/marketplace.json delete mode 100644 .codex-plugin/plugin.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json deleted file mode 100644 index 224097e..0000000 --- a/.agents/plugins/marketplace.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "name": "propulsion", - "interface": { - "displayName": "Propulsion", - "developerName": "Moon Pixels" - }, - "plugins": [ - { - "name": "propulsion", - "source": { - "source": "url", - "url": "https://github.com/moonpixels/propulsion.git", - "ref": "main" - }, - "policy": { - "installation": "AVAILABLE", - "authentication": "ON_INSTALL" - }, - "category": "Coding" - } - ] -} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json deleted file mode 100644 index 7e56420..0000000 --- a/.codex-plugin/plugin.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "name": "propulsion", - "version": "1.2.0", - "description": "Opinionated agentic coding workflow that guides software work from exploration and planning through execution and review.", - "author": { - "name": "Moon Pixels" - }, - "homepage": "https://github.com/moonpixels/propulsion", - "repository": "https://github.com/moonpixels/propulsion", - "license": "MIT", - "keywords": [ - "propulsion", - "agentic-coding", - "software-development", - "skills", - "workflow", - "exploration", - "planning", - "execution", - "review", - "brainstorm", - "interrogate", - "plan", - "execute", - "debug", - "tdd", - "debugging", - "prd", - "developer-tools" - ], - "skills": "./skills/", - "hooks": "./hooks/hooks.json", - "interface": { - "displayName": "Propulsion", - "shortDescription": "Opinionated workflow for agentic software development.", - "longDescription": "Propulsion automatically guides ordinary software requests through an opinionated agentic coding workflow: explore the codebase, resolve scope, create a plan, execute in focused slices, and review the result before handoff. It keeps agents grounded in repo context, explicit decisions, tests, and review loops.", - "developerName": "Moon Pixels", - "category": "Coding", - "capabilities": ["Interactive", "Read", "Write"], - "websiteURL": "https://github.com/moonpixels/propulsion", - "defaultPrompt": [ - "Implement social auth with Google and GitHub", - "Update the app to support team workspaces and role-based access", - "Fix the bug causing saved settings to reset after refresh" - ], - "brandColor": "#FF4F00", - "composerIcon": "./assets/propulsion_icon_square.png", - "logo": "./assets/propulsion_icon_square.png", - "screenshots": [] - } -} diff --git a/AGENTS.md b/AGENTS.md index 1e63dad..2b9a46a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,2 @@ - When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`. - After implementing changes run `bun run checks` before handoff. -- When raising a PR, update `package.json` to the appropriate semantic version for the PR contents and keep mirrored manifest versions in sync. diff --git a/CONTEXT.md b/CONTEXT.md index de63676..55acae7 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -20,6 +20,10 @@ _Avoid_: Automatic skill 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 diff --git a/README.md b/README.md index 667f266..0406f56 100644 --- a/README.md +++ b/README.md @@ -6,50 +6,29 @@ Propulsion is a compact skill set for agentic coding. It gives coding agents a s ## Installation -### Codex CLI +### Remote -Add the Propulsion marketplace: +Install Propulsion from GitHub with the skills installer: ```sh -codex plugin marketplace add moonpixels/propulsion +bunx skills@latest add moonpixels/propulsion ``` -Open Codex, run `/plugins`, select the Propulsion marketplace, install -Propulsion, then restart Codex. +Choose the skills and coding agents you want when prompted. -To update: +### Local -```sh -codex plugin marketplace upgrade propulsion -``` - -### Codex Desktop - -Add the Propulsion marketplace with the Codex CLI: - -```sh -codex plugin marketplace add moonpixels/propulsion -``` - -Open the desktop app's Plugins page, select the Propulsion marketplace, install -Propulsion, then restart the app. - -To update: +When developing Propulsion from a local clone, link each skill you want to use +into the shared Agent Skills directory: ```sh -codex plugin marketplace upgrade propulsion +mkdir -p ~/.agents/skills +ln -s /absolute/path/to/propulsion/skills/elicit ~/.agents/skills/elicit ``` -### OpenCode - -Add Propulsion to `opencode.json`: - -```json -{ - "$schema": "https://opencode.ai/config.json", - "plugin": ["propulsion@git+https://github.com/moonpixels/propulsion.git"] -} -``` +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. ## Acknowledgements diff --git a/package.json b/package.json index 51de0ea..b727e7a 100644 --- a/package.json +++ b/package.json @@ -1,8 +1,6 @@ { "name": "propulsion", - "version": "1.2.0", - "main": "./index.mjs", - "exports": "./index.mjs", + "private": true, "scripts": { "checks": "bun run lint && bun run format && bun run validate:skills", "format": "oxfmt .", From b1d409381f94bdb7c83a30a6cbb79104fd800555 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 15:30:19 +0100 Subject: [PATCH 11/52] Skills --- CONTEXT.md | 53 +- SKILLS_PLAN.md | 662 ++++++++++++++++++ ...n-skills-with-established-methodologies.md | 34 + skills/elicit-with-context/SKILL.md | 20 - skills/elicit-with-context/agents/openai.yaml | 5 - skills/elicit/SKILL.md | 40 -- skills/elicit/agents/openai.yaml | 5 - skills/implement/SKILL.md | 56 -- skills/implement/agents/openai.yaml | 5 - skills/maintain-context/SKILL.md | 69 -- skills/maintain-context/agents/openai.yaml | 5 - .../maintain-context/assets/adr-template.md | 17 - .../assets/context-template.md | 10 - skills/review/SKILL.md | 86 --- skills/review/agents/openai.yaml | 5 - skills/tdd/SKILL.md | 84 --- skills/tdd/agents/openai.yaml | 5 - 17 files changed, 747 insertions(+), 414 deletions(-) create mode 100644 SKILLS_PLAN.md create mode 100644 docs/adr/0001-govern-skills-with-established-methodologies.md delete mode 100644 skills/elicit-with-context/SKILL.md delete mode 100644 skills/elicit-with-context/agents/openai.yaml delete mode 100644 skills/elicit/SKILL.md delete mode 100644 skills/elicit/agents/openai.yaml delete mode 100644 skills/implement/SKILL.md delete mode 100644 skills/implement/agents/openai.yaml delete mode 100644 skills/maintain-context/SKILL.md delete mode 100644 skills/maintain-context/agents/openai.yaml delete mode 100644 skills/maintain-context/assets/adr-template.md delete mode 100644 skills/maintain-context/assets/context-template.md delete mode 100644 skills/review/SKILL.md delete mode 100644 skills/review/agents/openai.yaml delete mode 100644 skills/tdd/SKILL.md delete mode 100644 skills/tdd/agents/openai.yaml diff --git a/CONTEXT.md b/CONTEXT.md index 55acae7..22b47d7 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -42,14 +42,51 @@ _Avoid_: Design guide, skill reference 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 uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates review findings until verified and elicits user intent when a finding would change behaviour, contracts, architecture, or scope. +The user-invoked workflow that uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates code-review findings until verified 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 to behaviour changes when the repository has a runnable test suite. It uses Test Desiderata to favour valuable tests that respond to behaviour without coupling to code structure. -**Review skill**: +**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 self-contained 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. +_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 user-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 + +**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 workflow that uses evidence synthesis to answer a scoped question from primary sources and writes a cited research report. It delegates source discovery, appraisal, and report writing to a background agent when available so the caller receives only the durable report and 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. @@ -67,6 +104,18 @@ _Avoid_: Separate workflow, mode 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**: +The single established methodology that determines a skill's process. Research validates the choice, while the plan and skill use only its canonical name 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 diff --git a/SKILLS_PLAN.md b/SKILLS_PLAN.md new file mode 100644 index 0000000..1acddb3 --- /dev/null +++ b/SKILLS_PLAN.md @@ -0,0 +1,662 @@ +# Propulsion Skills Plan + +This plan defines the fixed v1 Propulsion skill suite. It is the high-level +handoff for implementing each skill independently, not a copy of the finished +skill instructions. + +## Purpose + +Propulsion gives coding agents short, predictable workflows grounded in +well-known methods. Each skill stabilises the process while leaving +context-sensitive outcomes open. + +The v1 suite contains exactly these twelve skills: + +1. **write-skill** +2. **elicit** +3. **maintain-context** +4. **commit** +5. **tdd** +6. **code-review** +7. **elicit-with-context** +8. **pr** +9. **implement** +10. **debug** +11. **research** +12. **review-architecture** + +## Suite Principles + +### Methodology hierarchy + +Every skill has one **governing methodology** that determines its process. +Add a **supporting concept** only when it governs a distinct concern without +competing with that methodology. + +Research validates each choice during design. Plans and skills use canonical +methodology names without author, book, or source attribution. The research +skill is the exception at output level because its reports cite their claims. + +### Behavioural language + +Use familiar terms as leading words to recruit the agent's existing knowledge. +Apply lossless compression until every remaining word or sentence changes +behaviour, preserves a condition, or improves navigation. Keep language plain, +tight, and context-aware rather than explaining concepts the agent already +knows. + +### Predictable composition + +Every skill remains directly useful on its own. A **router skill** contains only +coordination unique to its combined outcome; called skills remain authoritative +and the router neither repeats nor overrides them. + +### Invocation + +User invocation is the default. Permit model invocation only when a skill is a +composed dependency or a broadly reusable workflow whose context cost is +justified. + +| User-invoked | Model-invoked | +| ------------------- | ---------------- | +| write-skill | elicit | +| elicit-with-context | maintain-context | +| pr | commit | +| implement | tdd | +| debug | code-review | +| review-architecture | research | + +Model-invoked skills remain directly invokable by the user. + +### Resources + +Keep common-path behaviour in SKILL.md. Add a reference, asset, or script only +when a confirmed use case requires it: + +- references hold conditional guidance; +- assets hold reusable output material; +- scripts hold deterministic, repeated, or fragile operations. + +## Skill Catalogue + +| Skill | Outcome | Composition | +| ------------------- | ---------------------------------------------------------- | ---------------------------------------------------- | +| write-skill | Create, review, and improve predictable skills | elicit; research when durable evidence is warranted | +| commit | Create coherent conventional commits from uncommitted work | None | +| pr | Publish a ready GitHub pull request | commit | +| elicit | Resolve requirements to confirmed shared understanding | None | +| maintain-context | Keep project language and decisions current | None | +| elicit-with-context | Elicit while maintaining durable context | elicit, maintain-context | +| implement | Deliver a verified implementation through reviewed slices | tdd, code-review | +| tdd | Build observable behaviour through red-green-refactor | None | +| code-review | Report validated requirements and code-health findings | None | +| debug | Reproduce, isolate, repair, and verify a code issue | tdd when applicable | +| research | Persist primary-source findings in a cited report | Background agent when available | +| review-architecture | Produce an interactive report of high-value redesigns | research when durable external evidence is warranted | + +## Standard Skill Brief + +Every implementation handoff below records: + +- proposed name; +- intended outcome; +- use cases; +- boundaries and exclusions; +- governing methodology; +- supporting concepts; +- invocation and composition; +- high-level workflow; +- implementation success criteria; +- open research or design questions. + +## Skill Briefs + +### write-skill + +**Proposed name:** write-skill + +**Intended outcome:** Guide the user through creating, reviewing, or improving a +skill whose process is predictable, whose outcome remains context-sensitive, +and whose language is behaviourally dense. + +**Use cases:** Create a new skill from a need; review an existing skill; improve +an existing skill without unintentionally changing its contract. + +**Boundaries and exclusions:** It authors skill bundles, not the domain work the +new skill will later perform. It does not select a governing methodology without +the user's approval or retain source attribution in the finished skill. + +**Governing methodology:** Use-case modelling. + +**Supporting concepts:** Ubiquitous language, Unix philosophy, leading words, +progressive disclosure, degrees of freedom, ironic process theory, YAGNI, DRY, +design by contract, lossless compression, characterization testing, and +acceptance testing. + +**Invocation and composition:** User-invoked. Invoke **elicit** to resolve the +skill's concrete need and use cases. Invoke **research** when methodology +selection or another material question warrants a durable evidence record; +perform only bounded source verification for smaller factual checks. + +**High-level workflow:** + +1. Establish whether the user is creating, reviewing, or improving a skill. +2. Elicit goals, callers, inputs, preconditions, flows, branches, failure paths, + composition, permissions, outputs, and postconditions. +3. Research candidate governing methodologies and supporting concepts when + needed, recommend the strongest fit, and obtain the user's approval. +4. Choose the name, invocation policy, bundle shape, and necessary resources. +5. Write the bundle from the confirmed use cases and concepts. +6. Compress and semantically test every use case until the skill is concise, + complete, and predictable. + +**Implementation success criteria:** A finished skill handles every confirmed +use case, names one approved governing methodology, uses supporting concepts +only for distinct concerns, contains no repeated authority, and passes +mechanical and semantic validation. + +**Open questions:** None. + +### commit + +**Proposed name:** commit + +**Intended outcome:** Inspect uncommitted work and create one or more coherent +conventional commits without losing or conflating changes. + +**Use cases:** Commit one coherent working-tree change; separate mixed concerns +into multiple commits; provide the commit operation used by **pr**. + +**Boundaries and exclusions:** It does not push, open a pull request, discard +changes, or force unrelated work into one commit. + +**Governing methodology:** Conventional Commits. + +**Supporting concepts:** Atomic commits and interactive staging. + +**Invocation and composition:** Model-invoked and directly user-invokable. It +has no skill dependencies and is called by **pr**. + +**High-level workflow:** + +1. Inspect tracked, staged, unstaged, and untracked changes plus repository + instructions and recent commit conventions. +2. Group changes by coherent intent and identify anything that should remain + uncommitted. +3. Use file- or hunk-level staging to create each atomic change. +4. Write an accurate conventional commit message and verify the resulting + commit before continuing to another concern. + +**Implementation success criteria:** Every created commit is coherent, +conventional, and traceable to the inspected diff; excluded work remains +untouched; mixed changes are not hidden inside a misleading commit. + +**Open questions:** None. + +### pr + +**Proposed name:** pr + +**Intended outcome:** Publish the current GitHub branch as a concise, +ready-for-review pull request. + +**Use cases:** Commit eligible local work, push the branch, and create a pull +request; create a draft only when explicitly requested. + +**Boundaries and exclusions:** GitHub repositories only. Use the configured +default branch unless the user explicitly supplies another base. Stop clearly +when the branch, remote, authentication, or diff prerequisites are not met. + +**Governing methodology:** GitHub flow. + +**Supporting concepts:** Conventional Commits and BLUF. + +**Invocation and composition:** User-invoked. Invoke **commit** for uncommitted +work and leave its staging and atomicity guidance authoritative. + +**High-level workflow:** + +1. Resolve the GitHub remote, current branch, requested or default base branch, + authentication, and repository pull-request instructions. +2. Invoke **commit** when eligible uncommitted changes exist. +3. Inspect the complete branch diff and commit history from the base branch's + merge base. +4. Push the current branch and create a ready pull request, or a draft when + explicitly requested. +5. Use a conventional title and honour a required repository template; + otherwise write one short paragraph explaining what changed and why. + +**Implementation success criteria:** The remote branch exists, the pull request +targets the correct base, its title and body accurately describe the complete +diff, and the resulting URL is returned. + +**Open questions:** None. + +### elicit + +**Proposed name:** elicit + +**Intended outcome:** Turn unresolved requirements into confirmed shared +understanding by closing every material branch one decision at a time. + +**Use cases:** Resolve requirements, constraints, trade-offs, boundaries, +dependencies, terminology, and success conditions before downstream action. + +**Boundaries and exclusions:** It does not begin downstream implementation +before confirmation. It remains unconfirmed when the user pauses, cancels, or +redirects the interview. + +**Governing methodology:** Requirements elicitation. + +**Supporting concepts:** Decision trees, Socratic questioning, falsification, +and theoretical saturation. + +**Invocation and composition:** Model-invoked and directly user-invokable. It is +called by **write-skill** and **elicit-with-context**. + +**High-level workflow:** + +1. Inspect the environment until discoverable facts for the current branch are + known. +2. Build and order the material decision tree. +3. Ask exactly one highest-impact resolved-prerequisite question at a time, + recommending the strongest answer and meaningful alternatives. +4. Test each answer through scenarios, counterexamples, and edge cases. +5. Repeat until theoretical saturation, then present one concise synthesis for + explicit confirmation. + +**Implementation success criteria:** Material branches, constraints, and +success conditions are either confirmed or explicitly unresolved; downstream +work begins only after the user's final confirmation. + +**Open questions:** None. + +### maintain-context + +**Proposed name:** maintain-context + +**Intended outcome:** Keep the codebase's ubiquitous language and consequential +architecture decisions accurate as understanding changes. + +**Use cases:** Resolve project terminology; update the single root CONTEXT.md; +create, supersede, and link concise ADRs. + +**Boundaries and exclusions:** Record project-specific language rather than +general programming definitions. Create an ADR only when changing the decision +would be costly, the choice would surprise a future reader, and viable +alternatives created a genuine trade-off. + +**Governing methodology:** Ubiquitous language. + +**Supporting concepts:** Architecture Decision Records, single source of truth, +progressive disclosure, and inverted pyramid. + +**Invocation and composition:** Model-invoked and directly user-invokable. It is +called by **elicit-with-context**. + +**High-level workflow:** + +1. Compare conversation language with CONTEXT.md and relevant code evidence. +2. Challenge ambiguous or conflicting terms and persist each confirmed term + immediately. +3. Test accepted decisions against the ADR gates. +4. Write brief sequential ADRs only for qualifying decisions and preserve + superseded history in both directions. +5. Re-read changed artifacts for consistency and report unresolved + contradictions. + +**Implementation success criteria:** The root glossary reflects confirmed +language as it resolves; ADRs are brief, accepted, sequential, and historically +linked; inferred or unresolved claims are not persisted. + +**Open questions:** None. + +### elicit-with-context + +**Proposed name:** elicit-with-context + +**Intended outcome:** Elicit confirmed shared understanding while keeping +project language and decisions current. + +**Use cases:** Deliberate interviews whose confirmed terms and qualifying +decisions should become durable project context. + +**Boundaries and exclusions:** It is a router and repeats none of the called +skills' process, terminology rules, or persistence mechanics. + +**Governing methodology:** Inherited requirements elicitation. + +**Supporting concepts:** Inherited from **elicit** and **maintain-context**; +none are restated by the router. + +**Invocation and composition:** User-invoked. Invoke **elicit**, applying +**maintain-context** throughout. + +**High-level workflow:** Route the interview through **elicit** and +**maintain-context**. Treat **elicit**'s final confirmation as the acceptance +boundary for qualifying ADRs, then return the elicitation state, context +changes, and unresolved language or decisions. + +**Implementation success criteria:** The router contains only its composition +and shared acceptance boundary; called skills remain the sole authority for +their own behaviour. + +**Open questions:** None. + +### implement + +**Proposed name:** implement + +**Intended outcome:** Deliver a clear software request through the smallest +verified end-to-end slices and close the review-remediation loop. + +**Use cases:** Implement features, bug fixes, refactors, documentation, or +configuration after the desired outcome is sufficiently clear. + +**Boundaries and exclusions:** It does not duplicate TDD or code-review +instructions, add speculative scope, or commit and publish work without a +separate request. + +**Governing methodology:** Tracer bullets. + +**Supporting concepts:** Feedback loops and YAGNI. + +**Invocation and composition:** User-invoked. Invoke **tdd** for applicable +observable behaviour changes and **code-review** after implementation. + +**High-level workflow:** + +1. Confirm the requested outcome, authorised scope, repository rules, and + verification evidence. +2. Deliver the smallest end-to-end slice; use **tdd** when applicable and the + smallest direct verified change otherwise. +3. Repeat until the requested behaviour is complete. +4. Invoke **code-review**, remediate in-scope findings, and repeat review and + verification until clean. +5. Run the repository's prescribed final checks and report exact evidence. + +**Implementation success criteria:** Every requested behaviour is implemented, +relevant verification passes or has an exact blocker, and the latest review has +no unresolved in-scope finding. + +**Open questions:** None. + +### tdd + +**Proposed name:** tdd + +**Intended outcome:** Build observable behaviour one test at a time through +durable red-green-refactor cycles. + +**Use cases:** Features and bug fixes in repositories that already have a +runnable test suite. + +**Boundaries and exclusions:** Do not create a test harness merely to make TDD +applicable. Documentation, configuration-only changes, and +behaviour-preserving refactors remain outside unless they also change observable +behaviour. + +**Governing methodology:** Test-driven development through red-green-refactor. + +**Supporting concepts:** Classicist TDD, Test Desiderata, and +Arrange-Act-Assert. + +**Invocation and composition:** Model-invoked and directly user-invokable. It is +called by **implement** and **debug**. + +**High-level workflow:** + +1. Establish a known baseline and select one smallest observable behaviour. +2. Test through a stable public seam, using real internal collaborators and + doubles mainly at uncontrollable boundaries. +3. Observe the expected red failure, implement only enough for green, then + refactor while green. +4. Repeat one behaviour at a time and finish with the complete relevant suite. + +**Implementation success criteria:** Every cycle demonstrates meaningful red +and green evidence; retained tests satisfy the Test Desiderata and remain +sensitive to behaviour rather than implementation structure. + +**Open questions:** None. + +### code-review + +**Proposed name:** code-review + +**Intended outcome:** Return prioritised, evidence-validated findings for a +scoped code change without modifying it. + +**Use cases:** Review uncommitted work, a branch, pull request, revision range, +or a caller-supplied implementation. + +**Boundaries and exclusions:** Read-only. Report only issues introduced by or +materially relevant to the scoped change; omit personal preferences, unsupported +speculation, and unrelated pre-existing debt. + +**Governing methodology:** Google code review centred on code health. + +**Supporting concepts:** Requirements traceability, code smells, Test +Desiderata, falsification, and risk-based prioritisation. + +**Invocation and composition:** Model-invoked and directly user-invokable. It is +called by **implement**. + +**High-level workflow:** + +1. Pin the exact diff and recover the best available requirements source. +2. Inspect repository instructions, changed files, relevant surrounding code, + tests, and verification. +3. Perform separate requirements and code-health passes so neither suppresses + the other. +4. Try to disprove every candidate finding with code evidence and targeted + non-mutating checks. +5. Report only actionable findings with priority, evidence, consequence, and + the smallest effective correction. + +**Implementation success criteria:** The report states its scope and +requirements source, every finding is evidenced and actionable, both review +axes are explicit, and a clean review says so plainly. + +**Open questions:** None. + +### debug + +**Proposed name:** debug + +**Intended outcome:** Own the full debugging workflow from reproducible failure +through verified repair. + +**Use cases:** Diagnose and fix incorrect behaviour, failing tests, runtime +errors, regressions, performance faults, or integration issues. Stop before +mutation only when the user explicitly requests diagnosis alone. + +**Boundaries and exclusions:** Do not guess and patch symptoms, change multiple +variables without an experiment, or expand beyond the demonstrated cause. + +**Governing methodology:** Scientific method. + +**Supporting concepts:** Minimal reproducible example, hypothesis testing, +binary search, delta debugging, root-cause analysis, feedback loops, and +regression testing. + +**Invocation and composition:** User-invoked. Invoke **tdd** for the regression +test and repair when applicable. + +**High-level workflow:** + +1. Reproduce the issue and record the expected and observed behaviour. +2. Gather evidence, state falsifiable hypotheses, and run the cheapest + discriminating experiment. +3. Narrow the failing input, change, component, or boundary until the root cause + is established. +4. Add a regression test and apply the smallest causal correction. +5. Verify the original reproduction, relevant regression coverage, and wider + checks. + +**Implementation success criteria:** The failure is reproducible, the root cause +is supported by experiments, the fix addresses that cause, and verification +proves both repair and regression protection. + +**Open questions:** None. + +### research + +**Proposed name:** research + +**Intended outcome:** Investigate a scoped question against high-trust primary +evidence and persist concise, cited findings in the repository. + +**Use cases:** Research a user-requested topic; gather documentation, API, +source-code, standard, publication, or first-party data evidence; provide +durable reading legwork to another skill. + +**Boundaries and exclusions:** Do not trigger for every factual lookup. Secondary +sources are discovery aids whose material claims must be traced to primary +sources. Whenever the skill is invoked, it produces a durable report. + +**Governing methodology:** Evidence synthesis. + +**Supporting concepts:** Source criticism, citation chaining, triangulation, +falsification, reproducibility, and provenance. + +**Invocation and composition:** Model-invoked and directly user-invokable. Spawn +a background agent when the host supports delegation; otherwise perform the +same workflow inline. Other skills invoke it only when the evidence warrants a +durable record. + +**High-level workflow:** + +1. Define the research question, scope, currency needs, and source hierarchy. +2. Give a background agent the question, repository context, primary-source + standard, and report contract while the caller continues independent work. +3. Discover, appraise, compare, and synthesize primary evidence; use secondary + writing only to locate original sources. +4. Write docs/research/YYYYMMDD-{research-title}.md from + assets/research-report-template.md with claim-level citations, method, + conflicts, limitations, and source list. +5. Return only the report path and concise concrete findings to the caller, + which validates the conclusions and citations without loading the raw search + trail. + +The template uses createdAt, updatedAt, and status frontmatter, plus relative +supersedes or supersededBy links only when applicable. Its body contains the +research question and scope, conclusion, cited findings, method, limitations, +conflicts, and primary-source list. + +**Implementation success criteria:** The report maps material claims to primary +sources, exposes uncertainty and conflicts, and is reproducible from its +recorded method. A substantive refresh creates a linked superseding snapshot; +a minor correction preserves createdAt and changes updatedAt without rewriting +history. + +**Open questions:** None. + +### review-architecture + +**Proposed name:** review-architecture + +**Intended outcome:** Analyse a codebase and produce a concise interactive HTML +report of the highest-value architecture redesigns. + +**Use cases:** Review a whole project or explicit scope; expose weak module +boundaries, leaked implementation, shallow interfaces, harmful coupling, and +missing seams; propose framework-aware improvements. + +**Boundaries and exclusions:** Read-only. It recommends a small set of +high-value changes rather than exhaustively cataloguing debt or forcing one +framework-specific implementation pattern. + +**Governing methodology:** Information hiding. + +**Supporting concepts:** Deep modules, design it twice, cohesion and coupling, +single responsibility principle, dependency inversion, seams, ports and +adapters, ATAM, architecture fitness functions, strangler fig pattern, +progressive disclosure, and information visualisation. + +**Invocation and composition:** User-invoked. Invoke **research** only when +external framework, language, or architecture evidence warrants a durable +report. + +**High-level workflow:** + +1. Inspect code, context, decisions, dependency direction, framework + conventions, runtime boundaries, and existing verification. +2. Map cohesive capabilities, public contracts, hidden implementations, + adapters, seams, coupling, and quality-attribute drivers. +3. Generate alternative boundaries through design it twice, then evaluate + benefits, risks, trade-offs, effort, and migration paths. +4. Keep only the highest-value recommendations and define architecture fitness + evidence for each. +5. Generate a self-contained interactive report at + docs/architecture/YYYYMMDD-{scope}-architecture-review.html using + references/report-design.md for tone, hierarchy, accessibility, diagrams, + interaction patterns, and visual QA. + +Each recommendation explains the evidenced problem, affected modules and +contracts, target design, framework fit, quality improvements, costs and risks, +incremental migration, dependencies, and fitness checks. The initial view is +short and plain; diagrams, filters, and expandable evidence disclose complexity +only when requested. + +**Implementation success criteria:** A human can understand and compare the +prioritised recommendations without reading a wall of technical prose; every +recommendation is evidence-backed, framework-aware, trade-off explicit, +incrementally actionable, and visually verified. + +**Open questions:** None. + +## Composition Map + +| Caller | Called skill | Condition | +| ------------------- | ---------------- | --------------------------------------------------------------- | +| write-skill | elicit | Resolve the skill need and use cases | +| write-skill | research | Methodology or another material question needs durable evidence | +| elicit-with-context | elicit | Run the interview | +| elicit-with-context | maintain-context | Maintain language and decisions throughout | +| pr | commit | Eligible uncommitted work exists | +| implement | tdd | An applicable observable behaviour change has a runnable suite | +| implement | code-review | The implementation is ready for independent assessment | +| debug | tdd | The repair can be driven by a regression test | +| review-architecture | research | External evidence warrants a durable report | + +## Suggested Implementation Order + +1. **write-skill** +2. **elicit** +3. **maintain-context** +4. **commit** +5. **tdd** +6. **code-review** +7. **elicit-with-context** +8. **pr** +9. **implement** +10. **debug** +11. **research** +12. **review-architecture** + +The order establishes the authoring workflow first, then independently useful +dependencies, routers, and larger specialised workflows. + +## Suite Acceptance Criteria + +The v1 suite is complete when: + +- all twelve bundles exist under skills/ with the proposed canonical names; +- every skill has one governing methodology and only necessary supporting + concepts; +- descriptions state both capability and invocation conditions; +- invocation metadata matches the agreed user/model map in every supported + client; +- every skill is directly usable and every router contains only unique + coordination; +- callers reference dependencies without repeating or overriding them; +- common-path instructions stay in SKILL.md and every additional resource earns + its place through a confirmed use case; +- research owns assets/research-report-template.md and review-architecture owns + references/report-design.md; +- finished skill text names methodologies without author, book, or source + attribution; +- semantic dry runs exercise normal, branch, failure, and composition paths; +- mechanical validation and every bundle script pass; +- repository context, skill names, and composition agree; and +- bun run checks passes after each implemented skill. diff --git a/docs/adr/0001-govern-skills-with-established-methodologies.md b/docs/adr/0001-govern-skills-with-established-methodologies.md new file mode 100644 index 0000000..f2d5645 --- /dev/null +++ b/docs/adr/0001-govern-skills-with-established-methodologies.md @@ -0,0 +1,34 @@ +--- +status: accepted +--- + +# Govern skills with established methodologies + +## Decision + +Give every Propulsion skill one established governing methodology and add named +supporting concepts only for distinct concerns. Use canonical terms without +source attribution in finished skill text, and keep router skills limited to +unique coordination while called skills remain authoritative. + +## Context + +Propulsion needs predictable agent behaviour without large instructions that +repeat knowledge the agent already has. Detailed bespoke procedures consume +context and drift between skills, while loose prompts do not stabilise the +process. Established methodology names provide a compact shared vocabulary, but +their fit must be researched and confirmed rather than selected for familiarity +alone. Composition also creates a choice between repeating dependency guidance +inside routers and preserving one authority for each behaviour. + +## Ramifications + +Skill design now includes eliciting concrete use cases, selecting and approving +the governing methodology, and compressing the resulting workflow until every +remaining statement affects behaviour. Supporting concepts and resources must +earn their place through distinct needs. Routers stay small and changes to a +called skill propagate without duplicated instructions becoming stale. Source +provenance remains design evidence or a research-report concern rather than +finished skill prose. Reconsider this decision if canonical terminology no +longer produces sufficiently reliable agent behaviour without fuller local +explanation. diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md deleted file mode 100644 index c9c0724..0000000 --- a/skills/elicit-with-context/SKILL.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: elicit-with-context -description: Elicits shared understanding while maintaining project language and decisions. Use for deliberate interviews that should update CONTEXT.md and ADRs. -metadata: - invocation: user -disable-model-invocation: true ---- - -# Elicit with Context - -**Requirements elicitation** resolves a request one decision at a time while -explicit skill composition keeps the project's ubiquitous language current and -records only confirmed architectural decisions. - -## Steps - -1. Invoke `$elicit`, using `$maintain-context` throughout. Persist validated - glossary terms as they resolve, and treat `$elicit`'s final confirmation as - the acceptance boundary for ADRs. The handoff returns the elicitation state, - context files changed, and unresolved language or qualifying decisions. diff --git a/skills/elicit-with-context/agents/openai.yaml b/skills/elicit-with-context/agents/openai.yaml deleted file mode 100644 index ef66b09..0000000 --- a/skills/elicit-with-context/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Elicit with Context' - short_description: 'Interview while maintaining language and decisions' -policy: - allow_implicit_invocation: false diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md deleted file mode 100644 index 23855e2..0000000 --- a/skills/elicit/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: elicit -description: Elicit shared understanding through research and one-question-at-a-time interviews. Use when requirements, constraints, design choices, or user intent remain unresolved. -metadata: - invocation: model -disable-model-invocation: false ---- - -# Elicit - -**Requirements elicitation** turns an unresolved request into confirmed shared -understanding through environment research and one decision at a time. - -## Steps - -1. Establish the subject, then inspect relevant files, tools, behaviour, and - durable context until discoverable facts for the current branch are known. - Treat existing evidence as current state and the user's answers as intent. -2. Build an internal decision tree of every material outcome, boundary, - dependency, constraint, and success condition. Order prerequisites before - dependent decisions. -3. Take the highest-impact decision whose dependencies are resolved. Ask - exactly one question, give the recommended answer first with a brief reason, - add genuinely viable alternatives when useful, then wait for the user's - answer. -4. Test the answer with concrete scenarios, counterexamples, and edge cases. - Surface conflicts with evidence or earlier decisions for the user to resolve. - Inspect newly relevant facts as the tree develops. -5. Repeat the question and validation loop to **theoretical saturation**, when - further answers reveal no new material branches. -6. Present a concise synthesis of the agreed outcome, boundaries, decisions, - constraints, and success conditions. Ask whether it accurately captures the - shared understanding and complete only after explicit confirmation. - -## Rules - -- Keep downstream action pending until shared understanding is confirmed. -- Return an unconfirmed state when the user pauses, cancels, or redirects the - interview before confirmation. -- Keep each response focused on the single active decision. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml deleted file mode 100644 index 0c4c186..0000000 --- a/skills/elicit/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Elicit' - short_description: 'Reach shared understanding through elicitation' -policy: - allow_implicit_invocation: true diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md deleted file mode 100644 index f5d3ccc..0000000 --- a/skills/implement/SKILL.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: implement -description: Implements clear software requests in verified slices with TDD when applicable and a closed review loop. Use when explicitly asked to change code. -metadata: - invocation: user -disable-model-invocation: true ---- - -# Implement - -**Tracer bullets**, from Andrew Hunt and David Thomas's _The Pragmatic -Programmer_, deliver the smallest end-to-end slice and use its feedback to aim -the next one; TDD and review keep each slice safe. - -## Steps - -1. Read the request, repository instructions, relevant context and decisions, - current Git state, and available verification commands. Invoke `$elicit` - before editing when the requested outcome is materially ambiguous; otherwise - record the intended behaviour, authorised scope, acceptance evidence, and - pre-existing changes. The request and its change boundary are explicit. -2. Choose the smallest end-to-end slice that advances the request. Invoke `$tdd` - when the slice changes observable behaviour or fixes a bug and the repository - already has a runnable test suite. For documentation or configuration-only - work without an observable behaviour change, behaviour-preserving refactors, - or repositories without a test suite, implement the smallest change and use - the best existing verification without adding a test harness merely to enable - TDD. The slice passes its targeted verification. -3. Repeat the slice-and-verify loop, running focused tests, type-checking, or - other fast checks regularly. Every requested behaviour and acceptance - condition is implemented without speculative scope. -4. Invoke `$review` with the confirmed request and the exact changes made for - it. Address every in-scope finding in priority order, using `$tdd` for - behavioural corrections when applicable and keeping tests green through - refactors. Invoke `$elicit` when a correction would change agreed behaviour, - a public contract, architecture, or authorised scope; difficulty alone does - not require user intervention. Re-run relevant checks and `$review` until its - latest report has no unresolved in-scope findings. -5. Run the repository's prescribed checks and the full test suite when one - exists. The final verification state is known: available checks pass, or an - exact blocker or unrelated pre-existing failure is reported without claiming - full verification. - -## Rules - -- Preserve pre-existing user changes and keep review and remediation scoped to - the current request. -- Commit or push only when the user explicitly requests that Git operation. -- Prefer the simplest present solution; each abstraction and change must serve - the confirmed request. - -## Handoff - -Report the implemented behaviour and changed files, why TDD did or did not -apply, targeted and final verification evidence, review rounds and remediated -findings, and any unresolved blocker or uncertainty. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml deleted file mode 100644 index e509f4b..0000000 --- a/skills/implement/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Implement' - short_description: 'Implement clear requests through verified review loops' -policy: - allow_implicit_invocation: false diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md deleted file mode 100644 index 47b14b7..0000000 --- a/skills/maintain-context/SKILL.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: maintain-context -description: Maintains a project's ubiquitous language and architecture decision records. Use when domain terms or consequential codebase decisions emerge or change. -metadata: - invocation: model -disable-model-invocation: false ---- - -# Maintain Context - -**Ubiquitous Language**, from Eric Evans's domain-driven design, keeps project -language rigorous by using, testing, and refining the domain model in everyday -work; concise architecture decision records preserve the consequential choices -that shape the codebase. - -## Steps - -1. Compare domain language in the conversation with the root `CONTEXT.md` and - relevant code. - Challenge vague, overloaded, or conflicting terms immediately, propose one - precise canonical term, and test it with concrete scenarios and edge cases. - Treat code as evidence of current behaviour and the user's confirmed answer - as intent; surface contradictions for resolution. The term is either - validated with the user or remains explicitly unresolved. -2. As soon as a term is validated and agreed, create or update the single root - `CONTEXT.md` using the [context template](assets/context-template.md). Keep - definitions to one or two sentences, add `_Avoid_` only for aliases or - ambiguous alternatives that actually occur, and define domain meaning rather - than implementation, specifications, or general programming concepts. The - glossary reflects each resolved term before the discussion continues. -3. Test an accepted codebase decision against all three ADR 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 only when all three gates pass. The decision is either rejected - as routine or identified as a qualifying architectural decision. - -4. After a qualifying decision is accepted, 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 the file - `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision - first, then only the context and significant ramifications needed to explain - it. The new ADR is brief, accepted, sequentially numbered, and readable from - its filename. -5. When an accepted decision changes, read only the specific ADR it supersedes, - preserve that record, and create a new one. Set the old record's `status` to - `superseded` with a relative `superseded-by` link, and give the new record a - relative `supersedes` link; leave the old decision, context, and ramifications - unchanged. Both records expose the decision history in both directions. -6. Re-read every changed artifact against the resolved language, accepted - decisions, and relevant code evidence, then report the files changed and any - unresolved contradiction. The handoff identifies a consistent durable - record or names the exact uncertainty that prevented one. - -## Rules - -- Persist agreed language immediately; keep inferred or unresolved terms in the - conversation until agreement. -- Keep all ubiquitous language in the single root `CONTEXT.md`. -- Give each domain meaning one glossary entry and each architectural decision - one ADR; link supporting material from its authoritative record. -- Require only `Decision`, `Context`, and `Ramifications` as ADR content - sections, in that order. Frontmatter is reserved for `status` and conditional - supersession links. -- Preserve accepted ADR content as history; express a later choice through a - superseding record. -- Reuse a compatible convention when encountered; surface a conflicting - convention and obtain agreement before moving or reshaping durable records. diff --git a/skills/maintain-context/agents/openai.yaml b/skills/maintain-context/agents/openai.yaml deleted file mode 100644 index b5d50ea..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 decision records' -policy: - allow_implicit_invocation: true diff --git a/skills/maintain-context/assets/adr-template.md b/skills/maintain-context/assets/adr-template.md deleted file mode 100644 index 19c3d8d..0000000 --- a/skills/maintain-context/assets/adr-template.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -status: accepted ---- - -# {Decision-shaped title} - -## Decision - -{State what was decided and the essential reason first.} - -## Context - -{Explain the problem, forces, and serious alternatives needed to understand the decision.} - -## Ramifications - -{State the significant consequences, trade-offs, and conditions that could trigger reconsideration.} diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md deleted file mode 100644 index 4bb0d39..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 - -**{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/review/SKILL.md b/skills/review/SKILL.md deleted file mode 100644 index 0add926..0000000 --- a/skills/review/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: review -description: Reviews scoped code changes for requirements, code health, and refactor opportunities. Use when assessing a diff, branch, pull request, or completed implementation. -metadata: - invocation: model -disable-model-invocation: false ---- - -# Review - -Google's **code health** standard governs whether a change improves the system; -independent requirements and code-health passes prevent one concern from -masking the other. - -## Steps - -1. Resolve the change scope in this order: an explicit fixed point or caller - scope, uncommitted tracked and untracked changes, then the current branch - from its default-branch merge base. Confirm any revision exists and the - change set is non-empty; ask the user only when multiple scopes remain - plausible. Recover the originating - request from caller context, a supplied specification or ticket, then the - change description and commit history. If none exists, state that the - Requirements pass has no source instead of inventing one. The exact diff and - available requirements source are pinned. -2. Read repository instructions, relevant context and decisions, documented - standards, changed files in full, nearby tests, and any code needed to judge - effects. Treat surrounding code as context while keeping findings limited to - the scoped change. Both reviewers receive the same evidence and boundaries. -3. Run two fresh independent passes in parallel when the host supports - delegation; otherwise perform the passes separately without allowing one to - suppress or reprioritise the other: - - **Requirements** compares the diff with the confirmed request and reports - missing, partial, incorrect, or unrequested behaviour and relevant edge - cases. - - **Code health** examines design, correctness, complexity, tests, naming, - documentation, security, performance, reliability, and repository - standards where relevant. Assess changed tests for behavioural sensitivity, - structure insensitivity, specificity, and determinism. Use Martin Fowler's - **code smells** from _Refactoring_ to investigate concrete refactor - opportunities; a smell is a prompt for judgement, not a violation by - itself. - - Each pass returns candidate findings with evidence and does not edit files. - -4. Validate every candidate by trying to disprove it against the scoped diff, - full context, requirements, and repository standards. Run targeted - non-mutating tests, type-checking, linting, or other checks when they can - settle a claim. Discard preferences, unsupported speculation, unrelated - pre-existing debt, and issues already enforced by tooling. Every remaining - finding is reproducible or directly evidenced. -5. Assign `critical` to immediate data-loss, security, or production failure; - `high` to incorrect requirements or major behaviour, reliability, security, - or maintenance risk; `medium` to a concrete defect or significant code, - design, or test weakness; and `low` to a local but worthwhile improvement. - Every level remains actionable, while inconsequential nits are omitted. The - two axes are ready for transfer without merging or reranking them against - each other. - -## Rules - -- Keep review read-only; return corrections for the caller to implement. -- Prefer technical evidence and documented repository standards over personal - preference. -- Review the changed lines and their effects completely, but report only issues - introduced by or directly relevant to the scoped change. -- Give refactor opportunities the same evidence, priority, and correction - standard as behavioural findings. - -## Handoff - -Return `## Requirements` and `## Code health`. Use `No requirements source.` -when the first axis has no recoverable source and `No findings.` for a clean -axis. Format every finding as: - -```markdown -### [priority] Concise finding - -- Evidence: exact `path:line` and the observed fact -- Consequence: concrete behaviour or code-health impact -- Correction: smallest effective change -``` - -End with `## Summary` containing the finding count for each axis and any check -that could not run. The report contains findings only; a clean report says both -axes have no findings. diff --git a/skills/review/agents/openai.yaml b/skills/review/agents/openai.yaml deleted file mode 100644 index ff8212f..0000000 --- a/skills/review/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Review' - short_description: 'Review scoped code changes with validated evidence' -policy: - allow_implicit_invocation: true diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md deleted file mode 100644 index cd7a2d7..0000000 --- a/skills/tdd/SKILL.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: tdd -description: Builds observable behaviour through red-green-refactor and Test Desiderata. Use when a feature or bug fix has a runnable test suite. -metadata: - invocation: model -disable-model-invocation: false ---- - -# Test-Driven Development - -**Test-driven development**, from Kent Beck's _Test-Driven Development: By -Example_, builds one behaviour at a time through red, green, and refactor; -**Test Desiderata** governs whether each test is worth keeping. - -## Prerequisites - -- The request changes observable behaviour or fixes a bug. -- The repository already has a runnable test suite. A missing suite makes TDD - inapplicable; use the repository's available verification without installing - a harness solely for this workflow. -- Documentation, configuration-only work, and behaviour-preserving refactors - remain outside TDD unless they also introduce an observable behaviour change. - -## Test Quality - -Assess each test against Beck's Test Desiderata. A test need not maximise every -property, but surrender one only for a property of greater value: - -- **Isolated** and **composable**: order and selection do not change results. -- **Fast** and **automated**: feedback is prompt and needs no intervention. -- **Inspiring** and **predictive**: passing provides proportionate confidence - that the behaviour is suitable for production. -- **Writable** and **readable**: its cost is justified and its motivation is - clear to the next reader. -- **Behavioural** and **structure-insensitive**: behaviour changes affect the - result; rearranging implementation without changing behaviour does not. -- **Specific** and **deterministic**: failure has an obvious cause and unchanged - inputs produce the same result. - -Test through a public interface or stable observable seam. Derive expectations -independently from a requirement, worked example, or known result. For user -interfaces, prefer interactions and outcomes available to a user, such as -accessible roles, names, labels, and visible state. - -Keep CSS classes, incidental DOM shape, private methods, internal collaborator -calls or ordering, broad snapshots, trivial getters, and coverage-padding out -of tests because they do not establish required behaviour. Use test doubles at -uncontrollable system boundaries such as external APIs, time, randomness, and -sometimes persistence; exercise real internal collaborators so refactoring does -not break otherwise valid tests. - -## Steps - -1. Read the request, repository conventions and context, and nearby tests. Run - the smallest relevant existing test set to establish a known baseline. - Record unrelated failures. When a related test already fails for the requested - defect and independently specifies the required behaviour, adopt it as the - Red test; otherwise surface a related failure that prevents a known baseline. - The baseline and the next required behaviour are explicit. -2. Select one smallest behaviour and its most stable observable seam. Infer the - seam from the public contract and ask the user only when viable seams create - a material product or architecture trade-off. For a bug fix, choose a test - that reproduces the defect through that seam. One behaviour and expected - outcome are fixed for the cycle. -3. **Red**: write one test for that behaviour, or use the qualifying failing test - found in the baseline, then run it and confirm it fails for the expected - absence or defect. If it passes or fails for another reason, correct the test - or setup until the failure proves the intended gap. -4. **Green**: write only the production behaviour needed to pass the new test, - then run it and the relevant existing tests. The selected behaviour passes - without regressions or speculative implementation. -5. **Refactor**: while tests are green, improve names, duplication, complexity, - cohesion, or dependencies when a concrete opportunity exists. Make one - behaviour-preserving change at a time and rerun the relevant tests. The code - and tests remain green with worthwhile structure improvements applied. -6. Repeat red-green-refactor for the next behaviour, one test at a time. Finish - by running the complete relevant test set; every required behaviour is - covered by durable passing tests. - -## Handoff - -Report the baseline, behaviours and seams tested, red failures observed, green -commands, refactors performed, final relevant test result, and any unrelated -failure or blocker left for the caller. diff --git a/skills/tdd/agents/openai.yaml b/skills/tdd/agents/openai.yaml deleted file mode 100644 index 224675d..0000000 --- a/skills/tdd/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: 'Test-Driven Development' - short_description: 'Build durable tests through red-green-refactor' -policy: - allow_implicit_invocation: true From 72b2d9f9bd15932f4e4457430f1a7d9a4da95cab Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 16:51:32 +0100 Subject: [PATCH 12/52] Skills --- skills/code-review/SKILL.md | 11 ++ skills/code-review/agents/openai.yaml | 5 + skills/commit/SKILL.md | 11 ++ skills/commit/agents/openai.yaml | 5 + skills/debug/SKILL.md | 11 ++ skills/debug/agents/openai.yaml | 5 + skills/elicit-with-context/SKILL.md | 11 ++ skills/elicit-with-context/agents/openai.yaml | 5 + skills/elicit/SKILL.md | 11 ++ skills/elicit/agents/openai.yaml | 5 + skills/implement/SKILL.md | 11 ++ skills/implement/agents/openai.yaml | 5 + skills/maintain-context/SKILL.md | 11 ++ skills/maintain-context/agents/openai.yaml | 5 + skills/pr/SKILL.md | 11 ++ skills/pr/agents/openai.yaml | 5 + skills/research/SKILL.md | 11 ++ skills/research/agents/openai.yaml | 5 + skills/review-architecture/SKILL.md | 11 ++ skills/review-architecture/agents/openai.yaml | 5 + skills/tdd/SKILL.md | 11 ++ skills/tdd/agents/openai.yaml | 5 + skills/write-skill/SKILL.md | 162 ++++++------------ skills/write-skill/references/SECTIONS.md | 87 ++++++++++ skills/write-skill/scripts/validate-skill.js | 139 +++++---------- 25 files changed, 362 insertions(+), 202 deletions(-) create mode 100644 skills/code-review/SKILL.md create mode 100644 skills/code-review/agents/openai.yaml create mode 100644 skills/commit/SKILL.md create mode 100644 skills/commit/agents/openai.yaml create mode 100644 skills/debug/SKILL.md create mode 100644 skills/debug/agents/openai.yaml create mode 100644 skills/elicit-with-context/SKILL.md create mode 100644 skills/elicit-with-context/agents/openai.yaml create mode 100644 skills/elicit/SKILL.md create mode 100644 skills/elicit/agents/openai.yaml create mode 100644 skills/implement/SKILL.md create mode 100644 skills/implement/agents/openai.yaml create mode 100644 skills/maintain-context/SKILL.md create mode 100644 skills/maintain-context/agents/openai.yaml create mode 100644 skills/pr/SKILL.md create mode 100644 skills/pr/agents/openai.yaml create mode 100644 skills/research/SKILL.md create mode 100644 skills/research/agents/openai.yaml create mode 100644 skills/review-architecture/SKILL.md create mode 100644 skills/review-architecture/agents/openai.yaml create mode 100644 skills/tdd/SKILL.md create mode 100644 skills/tdd/agents/openai.yaml create mode 100644 skills/write-skill/references/SECTIONS.md diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..30854ec --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,11 @@ +--- +name: code-review +description: Reviews scoped code changes for requirements and code health. Use when assessing a diff, branch, pull request, or completed implementation. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Code Review + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml new file mode 100644 index 0000000..faa414c --- /dev/null +++ b/skills/code-review/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Code Review' + short_description: 'Review code for requirements and health' +policy: + allow_implicit_invocation: true diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md new file mode 100644 index 0000000..a65a844 --- /dev/null +++ b/skills/commit/SKILL.md @@ -0,0 +1,11 @@ +--- +name: commit +description: Creates coherent conventional commits from uncommitted work. Use when changes are ready to be inspected, separated, staged, and committed. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Commit + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/commit/agents/openai.yaml b/skills/commit/agents/openai.yaml new file mode 100644 index 0000000..b722eef --- /dev/null +++ b/skills/commit/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Commit' + short_description: 'Create coherent conventional commits' +policy: + allow_implicit_invocation: true diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md new file mode 100644 index 0000000..27ec802 --- /dev/null +++ b/skills/debug/SKILL.md @@ -0,0 +1,11 @@ +--- +name: debug +description: Reproduces, isolates, repairs, and verifies code issues. Use when debugging failures, regressions, runtime errors, or incorrect behaviour. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Debug + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/debug/agents/openai.yaml b/skills/debug/agents/openai.yaml new file mode 100644 index 0000000..4c6d231 --- /dev/null +++ b/skills/debug/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Debug' + short_description: 'Debug issues through verified repair' +policy: + allow_implicit_invocation: false diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md new file mode 100644 index 0000000..bee656a --- /dev/null +++ b/skills/elicit-with-context/SKILL.md @@ -0,0 +1,11 @@ +--- +name: elicit-with-context +description: Elicits shared understanding while maintaining project context. Use when an interview should update language and qualifying architecture decisions. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Elicit with Context + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/elicit-with-context/agents/openai.yaml b/skills/elicit-with-context/agents/openai.yaml new file mode 100644 index 0000000..46f2204 --- /dev/null +++ b/skills/elicit-with-context/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Elicit with Context' + short_description: 'Elicit while maintaining project context' +policy: + allow_implicit_invocation: false diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md new file mode 100644 index 0000000..132c80f --- /dev/null +++ b/skills/elicit/SKILL.md @@ -0,0 +1,11 @@ +--- +name: elicit +description: Elicits confirmed shared understanding one decision at a time. Use when requirements, constraints, trade-offs, or user intent remain unresolved. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Elicit + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml new file mode 100644 index 0000000..5388d3c --- /dev/null +++ b/skills/elicit/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Elicit' + short_description: 'Resolve requirements one decision at a time' +policy: + allow_implicit_invocation: true diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..940429a --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,11 @@ +--- +name: implement +description: Implements clear software requests through verified slices and review. Use when the user asks to change code, documentation, or configuration. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Implement + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml new file mode 100644 index 0000000..302154c --- /dev/null +++ b/skills/implement/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Implement' + short_description: 'Implement changes in verified slices' +policy: + allow_implicit_invocation: false diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md new file mode 100644 index 0000000..77ad21f --- /dev/null +++ b/skills/maintain-context/SKILL.md @@ -0,0 +1,11 @@ +--- +name: maintain-context +description: 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 + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/maintain-context/agents/openai.yaml b/skills/maintain-context/agents/openai.yaml new file mode 100644 index 0000000..e459f7c --- /dev/null +++ b/skills/maintain-context/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Maintain Context' + short_description: 'Maintain project language and decisions' +policy: + allow_implicit_invocation: true diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md new file mode 100644 index 0000000..6667d0d --- /dev/null +++ b/skills/pr/SKILL.md @@ -0,0 +1,11 @@ +--- +name: pr +description: Publishes the current GitHub branch as a concise pull request. Use when work is ready to be committed, pushed, and opened for review. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Pull Request + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/pr/agents/openai.yaml b/skills/pr/agents/openai.yaml new file mode 100644 index 0000000..d9506f9 --- /dev/null +++ b/skills/pr/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Pull Request' + short_description: 'Publish a concise GitHub pull request' +policy: + allow_implicit_invocation: false diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md new file mode 100644 index 0000000..b08fae0 --- /dev/null +++ b/skills/research/SKILL.md @@ -0,0 +1,11 @@ +--- +name: research +description: Investigates questions against primary sources and persists cited findings. Use when research, documentation, API facts, or reading legwork needs a durable report. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Research + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/research/agents/openai.yaml b/skills/research/agents/openai.yaml new file mode 100644 index 0000000..0f9f9ed --- /dev/null +++ b/skills/research/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Research' + short_description: 'Research primary sources into cited reports' +policy: + allow_implicit_invocation: true diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md new file mode 100644 index 0000000..f6c323c --- /dev/null +++ b/skills/review-architecture/SKILL.md @@ -0,0 +1,11 @@ +--- +name: review-architecture +description: Reviews a codebase for modular redesigns and produces an interactive report. Use when architecture boundaries, coupling, or abstractions need assessment. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Review Architecture + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/review-architecture/agents/openai.yaml b/skills/review-architecture/agents/openai.yaml new file mode 100644 index 0000000..9ea18e8 --- /dev/null +++ b/skills/review-architecture/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Review Architecture' + short_description: 'Review architecture and explain redesigns' +policy: + allow_implicit_invocation: false diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md new file mode 100644 index 0000000..ddfcd48 --- /dev/null +++ b/skills/tdd/SKILL.md @@ -0,0 +1,11 @@ +--- +name: tdd +description: Builds observable behaviour through red-green-refactor. Use when a feature or bug fix has a runnable test suite. +metadata: + invocation: model +disable-model-invocation: false +--- + +# Test-Driven Development + +Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. diff --git a/skills/tdd/agents/openai.yaml b/skills/tdd/agents/openai.yaml new file mode 100644 index 0000000..1386203 --- /dev/null +++ b/skills/tdd/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Test-Driven Development' + short_description: 'Build behaviour with red-green-refactor' +policy: + allow_implicit_invocation: true diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 197e6cc..5831226 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: write-skill -description: Create, review, and improve predictable, composable agent skills. Use when writing a new skill or assessing an existing skill's process, structure, or wording. +description: Creates, reviews, and improves predictable agent skills through approved use cases and established methodologies. Use when authoring or assessing a skill's behaviour, structure, or wording. metadata: invocation: user disable-model-invocation: true @@ -8,130 +8,78 @@ disable-model-invocation: true # Write Skill -**Use-case modelling** creates, reviews, and improves skills whose process is -predictable while their context-sensitive outcomes remain open. +**Use-case modelling** turns confirmed needs into skills with predictable +processes and context-sensitive outcomes. ## Steps 1. Inspect the request, complete target bundle, discoverable callers, and host conventions. Select the `Create`, `Review`, or `Improve` branch from the - user's authorised outcome. + user's authorised outcome. The branch, evidence, and change boundary are + explicit. 2. Follow the selected branch. ### Create -1. Invoke `$elicit` to confirm concrete invocations, user goals, inputs, - outputs, preconditions, main flows, branches, failure paths, composition, - permissions, observable postconditions, and the governing approach. Once the - use cases are clear, recall familiar established approaches, recommend one - dominant method with its canonical author or work, and include the user's - choice in the confirmed shared understanding. Add a named principle, theory, - or technique only for a distinct concern; verify a recalled term when its - precision or attribution is uncertain. +1. Invoke `$elicit` to confirm concrete invocations, goals, inputs, outputs, + prerequisites, flows, branches, failures, composition, permissions, + postconditions, and resource needs. During the interview, invoke `$research` + when selecting the methodology or another material question warrants durable + evidence. Recommend one governing methodology and supporting concepts only + for distinct concerns; `$elicit`'s final confirmation approves the complete + contract and authorises writing. 2. Choose a short verb-led name through **ubiquitous language** and an invocation - policy whose context cost matches its expected use. Place the bundle using - the established host convention; use `$elicit` when none is discoverable. -3. Map common-path instructions into `SKILL.md`. Add branch-specific resources - only when an elicited use case requires them, with each resource pointer - beside the condition that loads or uses it. -4. Write the complete bundle to the skill contract below. + policy whose context cost matches expected use. Read + [Skill Sections](references/SECTIONS.md), then use **Unix philosophy** and + **YAGNI** to choose the smallest independently useful bundle. The name, + invocation, structure, and resources serve the confirmed use cases. +3. Write the bundle with canonical **leading words** where they govern + behaviour. Apply **progressive disclosure** to conditional knowledge, + **degrees of freedom** to instruction precision, **DRY** to authority, and + **ironic process theory** to steer language toward the intended action. The + complete bundle expresses the confirmed contract through canonical terms; + source provenance remains in the research evidence. +4. Follow `Validate Create or Improve`. ### Review -1. Recover the intended contract from the full bundle, callers, host +1. Recover the intended contract from the complete bundle, callers, host conventions, and representative prompts. Invoke `$elicit` only when a - material intent decision remains unresolved. -2. Run [scripts/validate-skill.js](scripts/validate-skill.js) for mechanical - evidence, then assess every rule below against the observable process. -3. Return concise, prioritised findings. For each, name the principle, cite the - evidence and behavioural consequence, and recommend the smallest effective - improvement. Affirm the skill plainly when it already meets the standard. + material intent decision remains unresolved. The review scope and available + contract are explicit. +2. Read [Skill Sections](references/SECTIONS.md), run + [scripts/validate-skill.js](scripts/validate-skill.js), and acceptance-test + the representative invocations. Assess the governing methodology, supporting + concepts, predictability, composition, structure, language, resources, and + observable postconditions while preserving the bundle unchanged. +3. Return concise, prioritised findings. For each, name the governing concept, + cite the evidence and behavioural consequence, and recommend the smallest + effective improvement. Affirm the skill plainly when no material finding + remains. ### Improve -1. Complete the `Review` branch, then use **characterization testing** to pin - the existing invocation and process that should survive the change. +1. Complete `Review`, then use **characterization testing** to fix the existing + invocation and behaviour that should survive the change. 2. Invoke `$elicit` for material changes to intent, behaviour, invocation, - composition, or scope. Apply mechanical corrections already authorised by - the request. -3. Update the target and every affected caller while preserving the - characterised contract outside the confirmed change. + composition, or scope. Apply already-authorised mechanical corrections, then + use the `Create` branch's naming, structure, and language guidance to write + the confirmed change while preserving the characterised contract. +3. Follow `Validate Create or Improve`. ### Validate Create or Improve -1. Apply **lossless compression** until each remaining word changes behaviour, - preserves a condition, or improves navigation. -2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and exercise every - script added to the bundle until the mechanical contract passes. -3. Use **acceptance testing** to replay every elicited invocation through its - branches, pointers, and postconditions. Repeat writing, compression, and - validation until the latest version passes every scenario and review. -4. For complex or high-risk skills, give a fresh agent only the finished skill - and a realistic request. Evaluate its observed process independently, then - resolve material findings through the same loop. -5. Report created or changed files, validation evidence, acceptance scenarios, - fresh-agent evidence when used, and any remaining uncertainty. - -## Skill Contract - -- Start `SKILL.md` with frontmatter containing `name`, a one-line - `description`, `metadata.invocation`, and `disable-model-invocation`. -- Make `name` identical to its directory, at most 64 lowercase letters, digits, - and single hyphens. Prefer a short verb-led phrase that reads naturally as - `$skill-name` inside a request. -- Keep `description` at most 200 characters. Start with a strong action verb; - state what the skill does in third-person, action-oriented language; front-load - natural trigger terms; and add `Use when`, `Use for`, or `Use to` with its - invocation conditions. -- Make user invocation the default. Select model invocation when the skill is - expected across most relevant work and earns permanent description context. - -| `metadata.invocation` | `disable-model-invocation` | `policy.allow_implicit_invocation` | -| --------------------- | -------------------------- | ---------------------------------- | -| `user` | `true` | `false` | -| `model` | `false` | `true` | - -- Add `agents/openai.yaml` with `interface.display_name`, - `interface.short_description`, and the matching - `policy.allow_implicit_invocation`. -- Follow frontmatter with a human-readable H1 and one concise introductory - paragraph that makes the governing idea and capability obvious. -- Use the fewest semantically ordered sections that make execution and - maintenance predictable. Put genuine entry gates in `## Prerequisites`, - executable work in `## Steps`, skill-wide invariants in `## Rules`, and a - completed transfer in `## Handoff`. Use descriptive sections when they index - necessary instructions more clearly. -- Number dependent work, use `###` headings for stages or branches, and use - bullets for independent actions or checks. End every ordered step in an - observable postcondition through **design by contract**. -- Put conditional knowledge in `references/`, output templates and static files - in `assets/`, and deterministic repeated or fragile operations in `scripts/`. - Link each resource inline from the step or branch that needs it. - -## Rules - -- **Predictability** governs quality: stabilise the process while preserving - valid variation in outcomes. -- Choose one dominant established method that governs the process. Add a named - principle, theory, or technique only for a distinct concern. Prefer familiar - model knowledge, verifying a recalled term when precision matters. -- **Unix philosophy** governs boundaries: one coherent capability, independently - invokable and composable through explicit preconditions and postconditions. -- **Leading words** recruit existing model knowledge. Bold each established - approach where it first governs behaviour and explain only its - context-specific adaptation. Reinvoke it later only when a branch needs the - reminder. -- **Progressive disclosure** keeps common-path instructions in `SKILL.md` and - moves branch-specific detail behind a contextual pointer. -- Calibrate **degrees of freedom** to fragility: exact execution for brittle - operations, bounded choices for preferred patterns, concise principles for - judgement-heavy work. -- **Ironic process theory** favours positive target behaviour. Pair an essential - safety boundary with the safe action that satisfies it. -- **YAGNI** admits resources required by current use cases. A fragile operation - may justify a deterministic script on first use; other resources earn their - place through demonstrated need. -- **DRY** gives every meaning one authoritative location. Callers and contextual - resource pointers reach that source instead of restating it. -- Keep a constraint used by one step beside that step. Put `## Rules` - constraints across multiple steps or the finished output. +1. Apply **lossless compression** until every remaining word changes behaviour, + preserves a condition, or improves navigation. Each meaning has one + authoritative location. +2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute every + bundled script until the mechanical contract passes. +3. Use **acceptance testing** to replay every confirmed invocation through its + branches, resource pointers, and postconditions. Repeat writing, compression, + and validation until every scenario passes. +4. Forward-test complex or high-risk skills with a fresh agent given only the + finished bundle and a realistic request. Resolve material evidence through + the same loop; let simple skills and thin routers finish without this extra + test. +5. Report changed files, mechanical results, acceptance scenarios, forward-test + evidence when used, and any remaining uncertainty. diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md new file mode 100644 index 0000000..0467136 --- /dev/null +++ b/skills/write-skill/references/SECTIONS.md @@ -0,0 +1,87 @@ +# Skill Sections + +Structure serves behaviour. Every `SKILL.md` has frontmatter, a human-readable +H1, and a strong introduction; every other heading is optional. Use the fewest +clear headings that make the confirmed workflow easy to execute. A small router +may finish after its introduction. + +## Frontmatter + +Include the skill's discovery and invocation contract: + +- `name` matches its directory, uses lowercase letters, digits, and single + hyphens, and reads naturally when invoked. +- `description` is one action-oriented line that states both capability and + natural trigger conditions. Put all triggering guidance here because the body + loads only after invocation. +- `metadata.invocation` records `user` or `model`. +- `disable-model-invocation` and `agents/openai.yaml` use the matching policy. + +Use user invocation by default. Use model invocation when composition or broad +reuse justifies 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. +`interface.default_prompt` remains optional. + +## H1 + +Start the body with one human-readable H1 that makes the skill immediately +recognisable. It may expand an abbreviated directory name when that improves +clarity. + +## Introduction + +For a workflow skill, lead with the canonical governing methodology in bold and +state how it governs the capability in one strong sentence or short paragraph. +Explain only the context-specific adaptation and keep source attribution in the +research evidence rather than the skill. + +For a router, directly invoke the called skills and state only coordination +unique to their combined outcome. The router leaves their methodologies and +instructions authoritative. + +## Common Headings + +These headings are available when their inclusion criterion is met. Rename, +combine, nest, or omit them when another structure communicates the behaviour +more directly. + +### Prerequisites + +Use when external conditions must already be true before execution can begin. +State the condition and the safe route when it is absent. Put setup work the +agent can perform in `Steps`. + +### Steps + +Use for executable work whose sequence matters. Number dependent actions, +introduce branches or stages only for distinct flows, and end each step in an +observable postcondition through **design by contract**. + +### Rules + +Use for an invariant that constrains multiple steps or the finished result. +Keep a condition used by only one step beside that step. + +### Handoff + +Use when completion creates a meaningful transfer to the user or another skill. +State the result, evidence, and unresolved uncertainty that cross the boundary. + +## Bundled Resources + +Use **progressive disclosure** and **YAGNI** to add only resources required by a +confirmed use case: + +- `references/` holds conditional knowledge loaded into context. +- `assets/` holds files used in generated output. +- `scripts/` holds deterministic, repeated, or fragile operations. + +Place each resource pointer beside the step or branch that loads or uses it. +Execute every script and keep each meaning in one authoritative location. diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js index eef830d..7ac6f0a 100644 --- a/skills/write-skill/scripts/validate-skill.js +++ b/skills/write-skill/scripts/validate-skill.js @@ -10,40 +10,24 @@ function addError(message) { errors.push(message); } -function unquote(value) { - const trimmed = value.trim(); - const first = trimmed.at(0); - const last = trimmed.at(-1); - - if ((first === '"' && last === '"') || (first === "'" && last === "'")) { - return trimmed.slice(1, -1); - } - - return trimmed; -} - -function readTopLevel(raw, key) { - const line = raw - .split(/\r?\n/) - .find((candidate) => candidate.startsWith(`${key}:`)); - - return line ? unquote(line.slice(key.length + 1)) : null; +function isRecord(value) { + return value !== null && typeof value === 'object' && !Array.isArray(value); } -function readNested(raw, parent, key) { - const lines = raw.split(/\r?\n/); - const parentIndex = lines.findIndex((line) => line === `${parent}:`); - - if (parentIndex === -1) return null; +function parseYaml(raw, label) { + try { + const value = Bun.YAML.parse(raw); - for (const line of lines.slice(parentIndex + 1)) { - if (/^\S/.test(line)) break; + if (!isRecord(value)) { + addError(`Make ${label} a YAML mapping.`); + return {}; + } - const match = line.match(new RegExp(`^\\s+${key}:\\s*(.+)$`)); - if (match) return unquote(match[1]); + return value; + } catch (error) { + addError(`Parse ${label} as valid YAML: ${error.message}`); + return {}; } - - return null; } function parseFrontmatter(content) { @@ -51,19 +35,20 @@ function parseFrontmatter(content) { if (!match) { addError('Add YAML frontmatter at the start of SKILL.md.'); - return { body: content, raw: '' }; + return { body: content, data: {}, raw: '' }; } return { body: content.slice(match[0].length), + data: parseYaml(match[1], 'SKILL.md frontmatter'), raw: match[1], }; } -function validateName(raw, skillPath) { - const name = readTopLevel(raw, 'name'); +function validateName(frontmatter, skillPath) { + const { name } = frontmatter; - if (!name) { + if (typeof name !== 'string' || !name) { addError('Add the skill name to frontmatter.'); return; } @@ -83,13 +68,13 @@ function validateName(raw, skillPath) { } } -function validateDescription(raw) { - const description = readTopLevel(raw, 'description'); +function validateDescription(frontmatter, raw) { + const { description } = frontmatter; const descriptionLine = raw .split(/\r?\n/) .find((line) => line.startsWith('description:')); - if (!description) { + if (typeof description !== 'string' || !description) { addError('Add a one-line description to frontmatter.'); return; } @@ -117,22 +102,22 @@ function validateDescription(raw) { } } -function validateInvocation(raw, openaiRaw) { - const invocation = readNested(raw, 'metadata', 'invocation'); - const disableModel = readTopLevel(raw, 'disable-model-invocation'); - const allowImplicit = readNested( - openaiRaw, - 'policy', - 'allow_implicit_invocation', - ); +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 expectedDisable = invocation === 'user' ? 'true' : 'false'; - const expectedImplicit = invocation === 'user' ? 'false' : 'true'; + const expectedDisable = invocation === 'user'; + const expectedImplicit = invocation === 'model'; if (disableModel !== expectedDisable) { addError( @@ -147,7 +132,7 @@ function validateInvocation(raw, openaiRaw) { } } -function validateOpenaiYaml(skillPath, raw) { +function validateOpenaiYaml(skillPath, frontmatter) { const openaiPath = join(skillPath, 'agents', 'openai.yaml'); if (!existsSync(openaiPath)) { @@ -156,17 +141,15 @@ function validateOpenaiYaml(skillPath, raw) { } const openaiRaw = readFileSync(openaiPath, 'utf8'); - const displayName = readNested(openaiRaw, 'interface', 'display_name'); - const shortDescription = readNested( - openaiRaw, - 'interface', - 'short_description', - ); + 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 (!displayName) + if (typeof displayName !== 'string' || !displayName) addError('Set interface.display_name in agents/openai.yaml.'); - if (!shortDescription) { + if (typeof shortDescription !== 'string' || !shortDescription) { addError('Set interface.short_description in agents/openai.yaml.'); } else if (shortDescription.length < 25 || shortDescription.length > 64) { addError( @@ -174,8 +157,8 @@ function validateOpenaiYaml(skillPath, raw) { ); } - validateInvocation(raw, openaiRaw); - return openaiRaw; + validateInvocation(frontmatter, openai); + return openai; } function validateBody(body) { @@ -200,40 +183,6 @@ function validateBody(body) { if (!introduction) { addError('Follow the H1 with a concise introductory paragraph.'); } - - const h2s = lines - .map((line, index) => ({ - index, - title: line.match(/^##\s+(.+)$/)?.[1], - })) - .filter(({ title }) => title); - const sectionIndex = new Map(h2s.map(({ index, title }) => [title, index])); - - if (sectionIndex.has('References')) { - addError( - 'Move each resource pointer beside the step or branch that uses it.', - ); - } - - if (sectionIndex.has('Completion Gate')) { - addError('Express completion through observable step postconditions.'); - } - - const prerequisites = sectionIndex.get('Prerequisites'); - const steps = sectionIndex.get('Steps'); - const handoff = sectionIndex.get('Handoff'); - - if ( - prerequisites !== undefined && - steps !== undefined && - prerequisites > steps - ) { - addError('Place Prerequisites before Steps.'); - } - - if (handoff !== undefined && steps !== undefined && handoff < steps) { - addError('Place Handoff after the completed Steps.'); - } } function collectFiles(directory, prefix) { @@ -300,11 +249,11 @@ function validateSkill(skillPath) { } const content = readFileSync(skillFile, 'utf8'); - const { body, raw } = parseFrontmatter(content); + const { body, data, raw } = parseFrontmatter(content); - validateName(raw, skillPath); - validateDescription(raw); - validateOpenaiYaml(skillPath, raw); + validateName(data, skillPath); + validateDescription(data, raw); + validateOpenaiYaml(skillPath, data); validateBody(body); const resourceCount = validateResources(skillPath, body); From 10590b4f884900b23e4acf239e419396b97d3299 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 18:45:56 +0100 Subject: [PATCH 13/52] Skills --- skills/elicit/SKILL.md | 59 ++++++++++++++++++++++++++++++-- skills/elicit/agents/openai.yaml | 2 +- 2 files changed, 58 insertions(+), 3 deletions(-) diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index 132c80f..1698946 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -1,6 +1,6 @@ --- name: elicit -description: Elicits confirmed shared understanding one decision at a time. Use when requirements, constraints, trade-offs, or user intent remain unresolved. +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. metadata: invocation: model disable-model-invocation: false @@ -8,4 +8,59 @@ disable-model-invocation: false # Elicit -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Requirements elicitation** turns choices into confirmed shared understanding +while the user directs every decision. + +## Steps + +1. Inspect the request, conversation, and task-scoped environment for facts + needed by the current branch. Use accessible read-only sources incrementally + as answers expose new branches. Keep pre-confirmation fact-finding read-only; + when establishing a fact requires a state-changing operation, make that + operation a decision and wait for the user's authorisation. When a material + fact remains unavailable, state the inspected evidence, best-supported + inference, and confidence, then ask one factual verification question. The + current branch has an explicit factual basis. +2. Build and continually update an internal, dependency-ordered **decision + tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, + prerequisites, dependencies, constraints, flows, exceptions, permissions, + risks, and success conditions. Treat the active user as the sole decision + authority. Preserve compatible decisions after a redirection, rebuild + affected branches, and select the highest-impact decision whose dependencies + are resolved. One current decision is explicit. +3. Use **Socratic questioning** to ask exactly one question per turn about one + decision. State the context, recommended answer, concise reasoning, and as + many educated alternatives as help the user think, then ask the decision + once while leaving room for their own answer. Derive recommendations from + the user's confirmed outcome, evidence, project conventions, consequences, + and trade-offs. Treat their choice as authoritative and record a logically + necessary consequence without asking it again. The user confirms the current + decision. +4. Apply **falsification** to each answer through relevant scenarios, + counterexamples, and edge cases. Ask another question only when testing + exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or + conflicting answer on the current branch and reframe its single point of + uncertainty. Answer the user's requests for context directly, then return to + the same decision. Present a discovered constraint and its consequence as + facts, then reframe the decision around feasible options. The answer is clear + and consistent with the confirmed tree. +5. Use **contingent scaffolding** when the user has difficulty deciding. Adapt + the form and clarity of support through plain-language restatement, + alternatives and trade-offs, examples, or scenarios. When useful, replace a + complex decision with its highest-impact prerequisite decisions, resolve + them one at a time, and recombine them. The user reaches and confirms the + decision. +6. Continue until **theoretical saturation**: every relevant dimension has been + assessed, every discovered choice has a confirmed answer, dependencies and + answers are consistent, and a final scenario-and-edge-case pass reveals no + new material branch. Present one concise, self-contained synthesis of the + outcome, boundaries, key decisions, constraints, and observable success + conditions, then ask for explicit confirmation. Shared understanding is + ready for confirmation. +7. When the user corrects or rejects the synthesis, rebuild the affected + branches and continue from step 2 until saturation returns. An affirmative + confirmation completes the contract and authorises the already-requested + downstream outcome. A pause returns a concise checkpoint of confirmed + decisions and the active decision; a cancellation acknowledges the user's + direction and ends without a synthesis or handoff. The caller receives only + the handoff the user selected. diff --git a/skills/elicit/agents/openai.yaml b/skills/elicit/agents/openai.yaml index 5388d3c..dc7e24b 100644 --- a/skills/elicit/agents/openai.yaml +++ b/skills/elicit/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Elicit' - short_description: 'Resolve requirements one decision at a time' + short_description: 'Reach shared understanding one decision at a time' policy: allow_implicit_invocation: true From 90383116d2eba3751e4fb825fff3e77828e1ee7d Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 19:30:53 +0100 Subject: [PATCH 14/52] Skills --- skills/research/SKILL.md | 56 ++++++++++++++++++- .../assets/research-report-template.md | 50 +++++++++++++++++ 2 files changed, 105 insertions(+), 1 deletion(-) create mode 100644 skills/research/assets/research-report-template.md diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index b08fae0..528fcce 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -8,4 +8,58 @@ disable-model-invocation: false # Research -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Evidence synthesis** turns a scoped question into a reproducible repository +report whose material claims trace to primary sources. + +## Steps + +1. 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 any ambiguity + that could materially change the investigation; the research contract and + applicable prior evidence are explicit. +2. When the host supports background agents, delegate source discovery, + appraisal, synthesis, and report writing with the complete research + contract, relevant repository context, primary-source standard, and output + contract. Continue only independent caller work while it runs, then validate + its result. Perform the workflow inline when delegation is unavailable or + fails, and repair an invalid delegated result before handoff. One researcher + owns the investigation and report at a time. +3. Discover the strongest applicable primary evidence, including official + documentation, source code, standards, original publications, first-party + APIs, or first-party data. Use secondary sources only to locate originals. + Apply **source criticism** to authority, proximity, currency, applicability, + and stability; use **citation chaining** to reach the evidence behind + material claims. The evidence set is relevant, current enough for the + question, and traceable. +4. Compare independent evidence through **triangulation** and test emerging + conclusions through **falsification**. 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. +5. 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 the primary + evidence. Replace every placeholder and retain only applicable lifecycle + fields. Record enough method and source detail for **reproducibility**, but + omit the raw search trail. The report contains the question and scope, + conclusion, cited findings, method, conflicts, limitations, and primary + sources. When a distinct report already occupies the same dated path, append + `-2` to the filename slug and increment it until available without changing + the frontmatter title or H1. +6. Preserve **provenance** when related research already exists. Apply a minor + correction in place only when it repairs wording, formatting, or the link to + the same evidence without changing a material claim; retain `createdAt` and + change `updatedAt`. New evidence, changed scope, or a materially changed + finding creates a new dated snapshot with `supersedes`; mark the previous + snapshot `superseded` and add its relative `supersededBy` link without + rewriting its historical findings. The report history distinguishes + correction from substantive refresh. +7. Verify that each material claim is supported by its cited primary source, + every link and relative report path resolves, conflicts and uncertainty are + visible, and the recorded method can reproduce the investigation. 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. diff --git a/skills/research/assets/research-report-template.md b/skills/research/assets/research-report-template.md new file mode 100644 index 0000000..a999322 --- /dev/null +++ b/skills/research/assets/research-report-template.md @@ -0,0 +1,50 @@ +--- +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} + +## Conclusion + +{The concise answer, qualified to match the strength of the evidence} + +## Findings + +### {Finding} + +{Material claims with direct links to supporting primary sources. Identify +inferences explicitly.} + +## Conflicts + +{Conflicting evidence and its effect on the conclusion, or "None found."} + +## Limitations + +{Unresolved uncertainty, evidence gaps, and freshness risks, or "None known."} + +## Method + +{How sources were discovered, appraised, compared, and falsified; include the +research date and any reproducibility constraints without retaining the raw +search trail.} + +## Primary sources + +- [{Source title}]({URL or repository-relative path}) — {publisher or owner, + version or publication date, accessed YYYY-MM-DD, and relevance} From 4b27ca8124ae459941acb6d04f7731b5a7be2042 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 19:48:31 +0100 Subject: [PATCH 15/52] Skills --- skills/maintain-context/SKILL.md | 58 ++++++++++++++++++- .../maintain-context/assets/adr-template.md | 17 ++++++ .../assets/context-template.md | 10 ++++ 3 files changed, 84 insertions(+), 1 deletion(-) create mode 100644 skills/maintain-context/assets/adr-template.md create mode 100644 skills/maintain-context/assets/context-template.md diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 77ad21f..8d1eaf7 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -8,4 +8,60 @@ disable-model-invocation: false # Maintain Context -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Ubiquitous language** keeps project terms rigorous through everyday use and +refinement; concise architecture decision records preserve the consequential +choices that shape the codebase. + +## Steps + +1. Compare domain language in the conversation with the root `CONTEXT.md` and + relevant code. Challenge vague, overloaded, or conflicting terms, propose + one precise canonical term, and test it with concrete scenarios and edge + cases. Treat code as evidence of current behaviour and the user's confirmed + answer as intent; surface contradictions for resolution. The term is either + validated with the user or remains explicitly unresolved. +2. As soon as a term is validated and agreed, create or update the single root + `CONTEXT.md` using the [context template](assets/context-template.md). Keep + definitions to one or two sentences, add `_Avoid_` only for aliases or + ambiguous alternatives that actually occur, and define domain meaning rather + than implementation, specifications, or general programming concepts. The + glossary reflects each resolved term before the discussion continues. +3. Test an accepted codebase decision against all three ADR 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 only when all three gates pass. The decision is either rejected + as routine or identified as a qualifying architectural decision. + +4. After a qualifying decision is accepted, 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 the file + `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision + first, then only the context and significant ramifications needed to explain + it. The new ADR is brief, accepted, sequentially numbered, and readable from + its filename. +5. When an accepted decision changes, read only the specific ADR it supersedes, + preserve that record, and create a new one. Set the old record's `status` to + `superseded` with a relative `superseded-by` link, and give the new record a + relative `supersedes` link; leave the old decision, context, and ramifications + unchanged. Both records expose the decision history in both directions. +6. Re-read every changed artifact against the resolved language, accepted + decisions, and relevant code evidence, then report the files changed and any + unresolved contradiction. The handoff identifies a consistent durable + record or names the exact uncertainty that prevented one. + +## Rules + +- Persist agreed language immediately; keep inferred or unresolved terms in the + conversation until agreement. +- Keep all ubiquitous language in the single root `CONTEXT.md`. +- Give each domain meaning one glossary entry and each architectural decision + one ADR; link supporting material from its authoritative record. +- Require only `Decision`, `Context`, and `Ramifications` as ADR content + sections, in that order. Frontmatter is reserved for `status` and conditional + supersession links. +- Preserve accepted ADR content as history; express a later choice through a + superseding record. +- Reuse a compatible convention when encountered; surface a conflicting + convention and obtain agreement before moving or reshaping durable records. diff --git a/skills/maintain-context/assets/adr-template.md b/skills/maintain-context/assets/adr-template.md new file mode 100644 index 0000000..19c3d8d --- /dev/null +++ b/skills/maintain-context/assets/adr-template.md @@ -0,0 +1,17 @@ +--- +status: accepted +--- + +# {Decision-shaped title} + +## Decision + +{State what was decided and the essential reason first.} + +## Context + +{Explain the problem, forces, and serious alternatives needed to understand the decision.} + +## Ramifications + +{State the significant consequences, trade-offs, and conditions that could trigger reconsideration.} diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md new file mode 100644 index 0000000..4bb0d39 --- /dev/null +++ b/skills/maintain-context/assets/context-template.md @@ -0,0 +1,10 @@ +# {Project Name} Context + +{Describe the project domain and why this language exists in one or two +sentences.} + +## Language + +**{Canonical term}**: +{Define what the term is in one or two sentences.} +_Avoid_: {List observed aliases or ambiguous alternatives; omit when none exist.} From 9c360597e35911c22bb72169031147efb7940298 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 19:58:44 +0100 Subject: [PATCH 16/52] Skills --- skills/elicit-with-context/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index bee656a..1e92265 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -8,4 +8,6 @@ disable-model-invocation: true # Elicit with Context -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +Invoke `$elicit`, applying `$maintain-context` throughout. Treat `$elicit`'s +final confirmation as the acceptance boundary for qualifying ADRs, then return +the elicitation state, context changes, and unresolved language or decisions. From 77c4b4659ffe54dc32ec71484052ce3547d82ab8 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 20:26:04 +0100 Subject: [PATCH 17/52] feat(commit): add conventional commit workflow --- skills/commit/SKILL.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index a65a844..41dd114 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -8,4 +8,30 @@ disable-model-invocation: false # Commit -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Conventional Commits** turns uncommitted work into atomic commits whose +messages state each change's intent. + +## Steps + +1. Inspect `git status`, the repository's Git instructions and current + operation, staged, unstaged, and untracked changes, and recent commit messages. + Honour user-supplied scope or message constraints and compatible repository + conventions. The complete candidate diff and commit context are explicit. +2. Partition eligible changes by coherent intent using **atomic commits**. + Keep related implementation, tests, and documentation together while + leaving unrelated or ambiguous work uncommitted. Treat a coherent, + independent pre-staged set as the first commit; when it mixes concerns or + belongs with unstaged work, ask the user before altering the staged set. + Each planned commit has one explainable purpose. +3. For each concern, retain an already exact staged selection or use + **interactive staging** at file or hunk granularity to stage exactly that + change, then inspect the complete staged diff. The index represents one + atomic change while unselected work remains intact. +4. Write an accurate Conventional Commit message in the form + `type[(scope)][!]: description` for the staged diff. +5. Create the commit and allow configured Git hooks to run. A failed hook + remains authoritative; report its output and the resulting Git state for + user direction. +6. Verify each created commit against its recorded diff, inspect the remaining + status before continuing, and return each hash and subject plus work left + uncommitted. From 8cdc99eed6842cd0d7bf3fddef2917c987c2888e Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 20:40:59 +0100 Subject: [PATCH 18/52] feat(pr): add pull request workflow --- skills/pr/SKILL.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md index 6667d0d..dc74f05 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -8,4 +8,39 @@ disable-model-invocation: true # Pull Request -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**GitHub flow** publishes the current branch as a concise, ready-for-review pull +request. Invoke `$commit` when eligible uncommitted work exists; it remains +authoritative for commit selection, staging, and messages. + +## Prerequisites + +A GitHub remote, authenticated push and pull-request access, an attached branch, +and a distinct base branch are required. Use the user-supplied base or the +remote's default branch. Report the missing condition and stop when a +prerequisite cannot be resolved. + +## Steps + +1. Inspect repository instructions and pull-request templates, Git status and + current operation, the current branch, GitHub remotes, authentication, the + selected base, and any existing pull request for the branch. The publication + context and applicable repository requirements are explicit before mutation. +2. Invoke `$commit` when eligible uncommitted work exists. Continue with its + reported commits and intentionally excluded work visible. +3. Fetch the selected remote base, find its merge base with `HEAD`, and inspect + the complete commit history and diff from that point. Stop when the branch + has no publishable diff; otherwise the full pull-request scope is explicit. +4. Derive an accurate Conventional Commit title in the form + `type[(scope)][!]: description` for the complete diff. Populate every required + repository-template section; without a required template, write one short + **BLUF** paragraph explaining what changed and why. The title and body + represent the complete branch rather than one commit. +5. Push the current branch without rewriting remote history and create a ready + pull request against the selected base, or a draft only when the user + explicitly requested one. When an open pull request already represents the + branch, use it instead of creating a duplicate. The remote branch and one + corresponding pull request exist. +6. Verify the pull request's head, base, draft state, title, and body against the + inspected scope and repository requirements. Return its URL and report any + failed publication or verification with the resulting local and remote + state. From a1b1659048c77ed97fdadf3e2c8c670091047aa3 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 20:59:09 +0100 Subject: [PATCH 19/52] fix(skills): resolve calibration findings --- skills/commit/SKILL.md | 7 ++++--- skills/maintain-context/SKILL.md | 33 ++++++++++++-------------------- skills/pr/SKILL.md | 5 +++-- skills/write-skill/SKILL.md | 7 ++++--- 4 files changed, 23 insertions(+), 29 deletions(-) diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 41dd114..daf8db0 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -29,9 +29,10 @@ messages state each change's intent. atomic change while unselected work remains intact. 4. Write an accurate Conventional Commit message in the form `type[(scope)][!]: description` for the staged diff. -5. Create the commit and allow configured Git hooks to run. A failed hook - remains authoritative; report its output and the resulting Git state for - user direction. +5. Create the commit and allow configured Git hooks to run. On any failure, + treat hook output as authoritative when present, preserve the index and + working tree, and report the exact output and resulting Git state. Obtain + user direction for any repository or user Git configuration change. 6. Verify each created commit against its recorded diff, inspect the remaining status before continuing, and return each hash and subject plus work left uncommitted. diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 8d1eaf7..2dd8354 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -18,14 +18,17 @@ choices that shape the codebase. relevant code. Challenge vague, overloaded, or conflicting terms, propose one precise canonical term, and test it with concrete scenarios and edge cases. Treat code as evidence of current behaviour and the user's confirmed - answer as intent; surface contradictions for resolution. The term is either - validated with the user or remains explicitly unresolved. + answer as intent; surface contradictions for resolution. Reuse a compatible + convention and obtain agreement before moving or reshaping conflicting + durable records. The term is either validated with the user or remains + explicitly unresolved. 2. As soon as a term is validated and agreed, create or update the single root `CONTEXT.md` using the [context template](assets/context-template.md). Keep definitions to one or two sentences, add `_Avoid_` only for aliases or ambiguous alternatives that actually occur, and define domain meaning rather - than implementation, specifications, or general programming concepts. The - glossary reflects each resolved term before the discussion continues. + than implementation, specifications, or general programming concepts. Give + each domain meaning one authoritative entry and link supporting material from + it. The glossary reflects each resolved term before the discussion continues. 3. Test an accepted codebase decision against all three ADR gates: - changing it later has meaningful cost; - a future reader would find it surprising without context; and @@ -39,8 +42,11 @@ choices that shape the codebase. next four-digit sequence from filenames alone, and name the file `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision first, then only the context and significant ramifications needed to explain - it. The new ADR is brief, accepted, sequentially numbered, and readable from - its filename. + it. Give each architectural decision one authoritative ADR. Require only + `Decision`, `Context`, and `Ramifications` as content sections, in that order; + reserve frontmatter for `status` and conditional supersession links. Link + supporting material from that record. The new ADR is brief, accepted, + sequentially numbered, and readable from its filename. 5. When an accepted decision changes, read only the specific ADR it supersedes, preserve that record, and create a new one. Set the old record's `status` to `superseded` with a relative `superseded-by` link, and give the new record a @@ -50,18 +56,3 @@ choices that shape the codebase. decisions, and relevant code evidence, then report the files changed and any unresolved contradiction. The handoff identifies a consistent durable record or names the exact uncertainty that prevented one. - -## Rules - -- Persist agreed language immediately; keep inferred or unresolved terms in the - conversation until agreement. -- Keep all ubiquitous language in the single root `CONTEXT.md`. -- Give each domain meaning one glossary entry and each architectural decision - one ADR; link supporting material from its authoritative record. -- Require only `Decision`, `Context`, and `Ramifications` as ADR content - sections, in that order. Frontmatter is reserved for `status` and conditional - supersession links. -- Preserve accepted ADR content as history; express a later choice through a - superseding record. -- Reuse a compatible convention when encountered; surface a conflicting - convention and obtain agreement before moving or reshaping durable records. diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md index dc74f05..02167a9 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -38,8 +38,9 @@ prerequisite cannot be resolved. 5. Push the current branch without rewriting remote history and create a ready pull request against the selected base, or a draft only when the user explicitly requested one. When an open pull request already represents the - branch, use it instead of creating a duplicate. The remote branch and one - corresponding pull request exist. + branch, reuse it and reconcile its base, title, body, and ready or draft state + with the selected publication context. The remote branch and one + corresponding pull request exist with the requested metadata and state. 6. Verify the pull request's head, base, draft state, title, and body against the inspected scope and repository requirements. Return its URL and report any failed publication or verification with the resulting local and remote diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 5831226..128a45a 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -48,10 +48,11 @@ processes and context-sensitive outcomes. material intent decision remains unresolved. The review scope and available contract are explicit. 2. Read [Skill Sections](references/SECTIONS.md), run - [scripts/validate-skill.js](scripts/validate-skill.js), and acceptance-test - the representative invocations. Assess the governing methodology, supporting + [scripts/validate-skill.js](scripts/validate-skill.js), execute every bundled + script in an isolated disposable environment, and acceptance-test the + representative invocations. Assess the governing methodology, supporting concepts, predictability, composition, structure, language, resources, and - observable postconditions while preserving the bundle unchanged. + observable postconditions while preserving the bundle and user work unchanged. 3. Return concise, prioritised findings. For each, name the governing concept, cite the evidence and behavioural consequence, and recommend the smallest effective improvement. Affirm the skill plainly when no material finding From afaa219be734c1e1e5fd46fa9a6bf6be5afaaabf Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 21:15:13 +0100 Subject: [PATCH 20/52] feat(tdd): add test-driven development workflow --- skills/tdd/SKILL.md | 48 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index ddfcd48..def1ed3 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -8,4 +8,50 @@ disable-model-invocation: false # Test-Driven Development -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Test-driven development** builds one observable behaviour at a time through +red-green-refactor. Use **Classicist TDD** to test stable public seams with real +internal collaborators, introducing doubles mainly at uncontrollable boundaries. + +## Prerequisite + +Use an existing runnable test suite. When none exists, report that TDD is not +applicable and return control without creating a test harness. Apply TDD to +observable behaviour, including configuration with observable effects; leave +documentation, configuration-only maintenance, and behaviour-preserving +refactors with the caller. + +## Steps + +1. Read repository instructions, identify the relevant test command, and run the + existing suite to establish a known baseline. Separate unrelated existing + failures from the change, then select the smallest observable behaviour. The + baseline, test seam, and next behaviour are explicit. +2. **Red:** use **Arrange-Act-Assert** to add one focused test through a stable + public interface. For a bug, reproduce the incorrect behaviour; adopt an + already-failing regression test only when it independently specifies the + desired behaviour. Run the test and confirm that it fails for the expected + behavioural reason rather than a test defect or environment error. When it + does not, remain in Red: correct an in-scope test defect or report an + environment blocker, then rerun until the expected failure is observed. + Meaningful red evidence is recorded before Green begins. +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 hiding baseline failures. +4. **Refactor:** improve the test and production code while keeping behaviour + fixed. Run the focused tests after each material change until the design is + clear and green. The cycle ends with no refactor regression. +5. 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. + +## Test Quality + +Apply the **Test Desiderata** to retain tests that are isolated, composable, +fast, inspiring, writable, readable, behavioural, structure-insensitive, +automated, specific, deterministic, and predictive. Retained tests remain +unchanged when production code is refactored without changing observable +behaviour; when structure alone breaks a test, move its assertions to the public +outcome. Prefer assertions on public outcomes over CSS classes, incidental DOM +shape, private methods, internal call sequences, broad snapshots, or +coverage-only cases. From 709c40787abac65c1962dfdc693707501f0ae34f Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 21:46:33 +0100 Subject: [PATCH 21/52] feat(code-review): add code review workflow --- skills/code-review/SKILL.md | 77 ++++++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 1 deletion(-) diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 30854ec..89ebd45 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -8,4 +8,79 @@ disable-model-invocation: false # Code Review -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Google code review** applies the code-health standard to a scoped change. +Separate requirements and code-health passes keep delivery gaps, defects, and +refactor opportunities independently visible. + +## Steps + +1. Resolve the change scope in this order: an explicit caller-supplied scope, + uncommitted tracked and untracked work, then the current branch from its + default-branch merge base. Confirm any revision exists and the change set is + non-empty; report the exact blocker and stop when either check fails, and ask + the user only when multiple scopes remain plausible. Recover requirements + from caller context, a supplied request, specification or ticket, then the + change description and commit history. When none exists, state that there is + no requirements source rather than inventing one. The exact change set and + best available requirements source are explicit. +2. Read repository instructions, relevant context and decisions, changed files + in full, nearby tests, and the surrounding code needed to judge effects. Run + non-mutating verification already required by the repository when its result + materially informs the review. The review evidence and applicable standards + are complete. +3. Perform a **requirements traceability** pass. Compare the change with every + available requirement and identify missing, partial, incorrect, conflicting, + or unrequested behaviour and relevant unhandled cases. When there is no + requirements source, preserve that limitation instead of treating inferred + intent as a requirement. Requirements candidates are explicit. +4. Perform an independent code-health pass across correctness, design, + complexity, tests, naming, documentation, security, performance, reliability, + and repository standards where relevant. Apply the **Test Desiderata** to + changed tests, especially behavioural sensitivity, structure insensitivity, + specificity, and determinism. Use **code smells** as a heuristic baseline: + **Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, + **Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, + **Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, + **Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other + established smells when the changed code provides a concrete cue. A smell + becomes a finding only when evidence shows a worthwhile correction. + Code-health candidates are explicit. +5. Apply **falsification** to every candidate against the scoped change, full + context, requirements, and repository standards. Run targeted non-mutating + tests, type checks, linting, or other checks when they can settle a claim. + Discard personal preferences, unsupported speculation, unrelated pre-existing + debt, and candidates without a demonstrated consequence. Every remaining + finding is reproducible or directly evidenced. +6. Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and + order findings within each from highest to lowest priority. Every reported + finding is actionable. + +## Rules + +- Keep the review read-only and return corrections for the caller to implement. +- Report only issues introduced by or materially relevant to the scoped change. +- Prefer code evidence and documented standards over personal preference. +- Hold refactor opportunities to the same evidence, consequence, priority, and + correction standard as behavioural findings. + +## Handoff + +State the exact scope and requirements source, then return `## Requirements` +and `## Code health`. Use `No requirements source.` when applicable and `No +findings.` for a clean axis. Format each finding as: + +```markdown +### [priority] Concise finding + +- Evidence: exact `path:line` and observed fact +- Consequence: concrete behaviour or code-health impact +- Correction: smallest effective change +``` + +End with `## Summary`, including the finding count for each axis and any check +that could not run. When no material finding remains, say the scoped change is +clean plainly. From 6b7d0303bd04ededcef76300c7690f1ef028c79c Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 22:12:16 +0100 Subject: [PATCH 22/52] feat(implement): add implementation routing workflow --- skills/implement/SKILL.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 940429a..9c1108e 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -8,4 +8,34 @@ disable-model-invocation: true # Implement -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Tracer bullets** deliver the smallest end-to-end slice and use its feedback to +aim the next one. `$tdd` builds applicable behaviour; `$code-review` assesses +the completed implementation independently. + +## Steps + +1. Deliver the smallest end-to-end slice that advances the request. Invoke + `$tdd` when its prerequisite applies; otherwise implement directly with the + best available targeted verification. Repeat until every requested behaviour + and acceptance condition is implemented. +2. Invoke `$code-review` with the confirmed request and exact implementation + scope. Address every in-scope finding in priority order, invoking `$tdd` for + applicable behavioural corrections. Invoke `$elicit` when a correction would + materially change agreed behaviour, a public contract, architecture, or + authorised scope. Re-run relevant verification and `$code-review` until its + latest report has no unresolved in-scope findings. +3. Run the repository's prescribed final checks without modifying pre-existing + out-of-scope changes. Isolate a mutating check when needed; when that cannot + be done safely, leave it unrun and report the blocker. Available checks pass, + or the exact blocker and any unrelated pre-existing failure are reported + without claiming full verification. + +## Rules + +- Preserve pre-existing user changes and keep implementation, review, and + remediation scoped to the current request. + +## Handoff + +Report the implemented behaviour and changed files, `$tdd` applicability, +verification and review evidence, and any unresolved blocker or uncertainty. From dae98b7d2bd2740428dc86b051563c902f1675f7 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 22:12:24 +0100 Subject: [PATCH 23/52] docs(agents): require runtime-context reasoning --- AGENTS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/AGENTS.md b/AGENTS.md index 2b9a46a..38f53f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,2 +1,3 @@ - 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. - After implementing changes run `bun run checks` before handoff. From a1738b469da16b0e25ad22dcdacf4d029a726cd4 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Tue, 14 Jul 2026 22:44:15 +0100 Subject: [PATCH 24/52] feat(debug): add evidence-driven debugging workflow --- .../research/20260714-debugging-techniques.md | 248 ++++++++++++++++++ skills/debug/SKILL.md | 44 +++- skills/debug/references/TECHNIQUES.md | 70 +++++ 3 files changed, 361 insertions(+), 1 deletion(-) create mode 100644 docs/research/20260714-debugging-techniques.md create mode 100644 skills/debug/references/TECHNIQUES.md diff --git a/docs/research/20260714-debugging-techniques.md b/docs/research/20260714-debugging-techniques.md new file mode 100644 index 0000000..f21f5c5 --- /dev/null +++ b/docs/research/20260714-debugging-techniques.md @@ -0,0 +1,248 @@ +--- +title: 'Concrete debugging techniques for coding agents' +createdAt: 2026-07-14 +updatedAt: 2026-07-14 +status: current +--- + +# Concrete debugging techniques for coding agents + +## Research question and scope + +**Question:** Which proven, concrete debugging techniques should Propulsion's +user-invoked `debug` skill expose to help coding agents establish a repeatable +failing signal, isolate a root cause, and verify a repair; and should their +detail live in a progressively disclosed reference rather than `SKILL.md`? + +**Intended use:** Inform a review recommendation only. This report does not +authorise a change to the skill. + +**Scope:** Issue-agnostic techniques for tests, HTTP, CLI, browser, captured +event replay, flaky and concurrent failures, performance, bisection, +instrumentation, causal tracing, and regression verification. Language-specific +debugger commands and generic troubleshooting catalogues are excluded. Stable +classic techniques use original publications; tool examples use official +documentation current on 2026-07-14. Matt Pocock's local `diagnosing-bugs` skill +and obra's `systematic-debugging` skill are design comparators, not evidence of +effectiveness. + +## Conclusion + +The current [`debug` skill](../../skills/debug/SKILL.md) has the right governing +loop and already covers failing tests, benchmarks, traces, probes, minimal +reproductions, binary search, delta debugging, causal repair, and layered +verification. It needs more concrete guidance only where an agent must choose +_how_ to create the signal or discriminating experiment. The material gaps are: + +- an executable signal quality gate that asserts the exact symptom rather than + merely exercising the path; +- capture-and-replay, differential, property/fuzz, flaky/concurrent, + performance, and boundary-tracing selection branches; +- the artefact each branch must retain so another run can reproduce the result. + +One compact `references/TECHNIQUES.md` is justified. The repository's own +[resource rule](../../skills/write-skill/references/SECTIONS.md) assigns +conditional knowledge to `references/` and requires its pointer beside the +branch that uses it; the [suite plan](../../SKILLS_PLAN.md) keeps common-path +behaviour in `SKILL.md`. Keep the scientific loop and no-signal stop condition +in `SKILL.md`, add one conditional pointer when the failing signal or next +experiment is not obvious, and make the reference a decision guide rather than +an encyclopaedia. Source attribution should remain here, not in the eventual +skill. + +## Findings + +### A failing signal needs an oracle, not just an invocation + +The current skill names useful signal forms but does not say what makes one +diagnostically sharp. An HTTP command, CLI invocation, or browser script can run +successfully while missing the reported bug. For example, curl does not treat +HTTP error statuses as command failure by default; `--fail-with-body` changes the +exit status for most 4xx/5xx responses while preserving the body, and the curl +manual records authentication exceptions. A robust HTTP probe therefore needs +explicit assertions for the relevant status, headers, or body, not only a curl +exit code ([curl manual](https://curl.se/docs/manpage.html#--fail-with-body)). +Playwright likewise separates driving the page from asserting the expected +condition, and its web assertions wait for the condition +([Playwright assertions](https://playwright.dev/docs/test-assertions)). + +**Inference:** the common quality gate should require one already-run, +agent-runnable command or probe that (1) reaches the relevant path, (2) asserts +the user's exact symptom, (3) runs quickly enough for the debugging loop, and +(4) is deterministic or reports a measured reproduction rate. Record the +command, fixture or captured input, expected verdict, observed verdict, and any +seed, environment, or schedule needed for replay. This changes agent behaviour; +the labels “HTTP”, “CLI”, and “browser” alone do not. + +### Signal techniques should be selected by symptom and seam + +The reference should offer this compact selection guidance: + +| Condition | Technique and minimum observable signal | Material addition | +| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| A stable test seam reaches the fault | Focused failing test or minimal harness; assert the exact behaviour and preserve the fixture | Mostly present; clarify the oracle quality gate | +| The fault is at an HTTP boundary | Script one request and assert status plus the relevant body/header; preserve request payload and response | Concrete instantiation of “targeted probe” | +| The fault is a CLI contract | Run a fixture input and assert exit status, stdout, and/or stderr against the expected result; record relevant flags and environment | Concrete instantiation of “targeted probe” | +| The fault requires real browser behaviour | Headless browser script asserting the relevant DOM, console, request, or response outcome | Concrete instantiation; browser assertions are distinct from navigation | +| Only a production request or event exposes the fault | Capture the smallest safe request/event artefact and replay it at the nearest stable seam | New branch; useful when local construction loses the trigger | +| The bad input is unknown or combinatorial | Property/fuzz loop with an explicit invariant; preserve the seed/failing artefact and minimise it before diagnosis | New branch; complements rather than replaces an observed-bug reproduction | +| The failure is intermittent | Repeat the exact trigger, report attempts and failure rate, then control time, randomness, order, load, or scheduling one variable at a time | New branch; turns “not deterministic” into a measurable signal | +| The fault is concurrent | Prefer a deterministic/systematic scheduler or recorded schedule when available; use stress only to amplify and capture a failure | New branch; stress alone is not reliable isolation | +| The fault is performance | Establish a controlled baseline and failing threshold, repeat measurements, then profile the failing workload before changing code | Makes the current “benchmark” signal operational | + +These are supported as technique families, not mandates for particular tools. +Playwright documents strict request/payload matching for recorded HAR replay, +which demonstrates how a captured network interaction can become a repeatable +fixture ([Playwright HAR replay](https://playwright.dev/docs/mock#mocking-with-har-files)). +LLVM's current libFuzzer documentation requires a fast, narrow, deterministic +target, writes the failure-inducing input to disk, supports crash minimisation, +and can replay saved inputs as regression tests +([libFuzzer target and corpus guidance](https://llvm.org/docs/LibFuzzer.html)). +The original QuickCheck publication supports generated inputs checked against +executable properties, but also records pitfalls; property/fuzz loops therefore +belong only where a meaningful invariant or failure oracle exists +([Claessen and Hughes, 2000](https://research.chalmers.se/en/publication/237427)). + +For concurrency, repeated stress can raise the chance of observing a bug but +does not make the schedule reproducible. The CHESS publication reports that +ordinary stress has unpredictable coverage, while systematic schedule control +can reproduce the erroneous interleaving +([Musuvathi, Qadeer, and Ball, 2008](https://www.usenix.org/legacy/event/osdi08/tech/full_papers/musuvathi/musuvathi_html/index.html)). +An empirical study of 201 flaky-test fixes found asynchronous waiting, +concurrency, and test-order dependency to be its dominant categories; this +supports deliberately varying timing and order, recording environmental state, +and replacing guessed delays with explicit conditions after the cause is known +([Luo et al., 2014](https://huang.isis.vanderbilt.edu/cs8395/paper/flakytest.pdf)). +Its Apache-heavy sample is evidence for those branches, not universal incidence +rates. +For performance, the exact benchmark tool is contextual, but controlled warmup, +repetition, and reported variance are concrete safeguards against treating one +noisy timing as a cause +([Google Benchmark user guide](https://github.com/google/benchmark/blob/main/docs/user_guide.md#runtime-and-reporting-considerations)). + +### Isolation needs a small set of distinct experiment patterns + +The current skill already names minimal reproducible examples, binary search, +and delta debugging. Delta debugging is strongly applicable: the original +publication automatically reduced a 95-action browser failure to three actions +and 896 lines of HTML to one failure-inducing line, while explicitly requiring +an automated test outcome +([Zeller and Hildebrandt, 2002](https://www.st.cs.uni-saarland.de/papers/tse2002/)). + +Three additional patterns materially improve technique selection: + +1. **Automated bisection:** when known-good and known-bad states exist, drive a + stable predicate across commits, versions, inputs, datasets, or configurations. + Git's official `bisect run` contract demonstrates the critical requirement: + the script must classify good, bad, and untestable states by exit status + ([Git bisect](https://git-scm.com/docs/git-bisect)). +2. **Differential testing:** run the same input through two comparable + implementations, versions, or configurations and inspect the smallest output + difference. McKeeman's original account reports this as useful when an oracle + is expensive, but warns that legitimate unspecified differences create false + positives + ([McKeeman, 1998](https://www.cs.tufts.edu/comp/150FP/archive/bill-mckeeman/DifferentailTesting.pdf)). +3. **Boundary and backward causal tracing:** instrument only the boundaries that + discriminate current hypotheses, correlate a request across components, and + trace the first bad value or invariant violation backwards to the earliest + divergence. OpenTelemetry explains that propagated context correlates signals + across process boundaries + ([context propagation](https://opentelemetry.io/docs/concepts/context-propagation/)); + the original Dapper report supports distributed traces for understanding + behaviour and performance in complex services + ([Sigelman et al., 2010](https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/)). + +The reference should say when to choose each pattern and what result confirms or +rejects a hypothesis. It should not repeat the skill's existing instruction to +change one variable at a time. + +### Verification is already adequate; add only artefact cleanup and replay detail + +The current skill already requires the original reproduction, focused +regression coverage, nearby checks, wider repository checks, and separation of +pre-existing failures. That is stronger than either comparator's verification +summary and needs no second technique catalogue. + +The reference can add two conditional details: convert a minimised failing +artefact into regression protection at the strongest stable seam, and remove or +clearly retain temporary instrumentation and throwaway harnesses. A saved fuzz +input being replayable as a regression test is one concrete example +([libFuzzer](https://llvm.org/docs/LibFuzzer.html)); it does not imply every +debugging artefact belongs permanently in the test suite. The existing `$tdd` +composition remains authoritative for red-green-refactor behaviour. + +### The comparators support discoverability, not effectiveness claims + +Matt Pocock's local +`/Users/adam/Developer/matt-pocock-skills/skills/engineering/diagnosing-bugs/SKILL.md` +provides a useful ordered list of concrete signal constructors and operational +qualities such as exact symptom, speed, determinism, and agent-runnability. +Obra's +[systematic-debugging bundle](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging) +uses a short main workflow plus conditional supporting references, including +backward root-cause tracing. These are good design precedents for a compact +selection reference. + +Neither comparator supplies controlled evidence for its claimed productivity +or success rates. Those claims were excluded from this report. The recommended +techniques instead trace to the publications and official documentation above. + +## Conflicts + +- Matt's comparator recommends repeated stress and injected sleeps for + nondeterministic bugs. CHESS shows that stress coverage is unpredictable for + concurrency defects. Repetition and perturbation should be described as + amplification and evidence capture, with controlled schedule replay preferred + when available—not as proof of cause. +- Differential results are candidates, not automatically bugs: comparable + systems may legitimately differ where behaviour is unspecified. +- curl's failure options do not fully classify application correctness and have + documented HTTP authentication exceptions. An HTTP debugging script needs an + explicit symptom oracle. +- Retries can reveal a flaky failure rate, but a passing retry is not repair + verification. Playwright explicitly categorises fail-then-pass as “flaky” + ([Playwright retries](https://playwright.dev/docs/test-retries)). + +## Limitations + +- Technique effectiveness depends on a valid oracle. No general method turns an + ambiguous expected behaviour into a reliable failing signal. +- Systematic schedulers, profilers, tracing, browser automation, and fuzzers are + ecosystem-dependent. The skill should name the technique and let repository + context select the tool. +- Performance measurements remain environment-sensitive even with warmup and + repetition; a local regression threshold may not represent production. +- Production captures can contain secrets or personal data. Any eventual + reference should require minimisation and safe handling under repository and + user permissions. +- The recommendation has not yet been acceptance-tested against a drafted + `TECHNIQUES.md`; that belongs to the authoring decision if the user approves + the change. + +## Method + +On 2026-07-14, the investigation inspected the current `debug` bundle, its plan, +the host's skill-section rules, and the two user-supplied comparators. Source +discovery then followed claims to original publications and current official +tool/project documentation. Evidence was triangulated across signal +construction, input reduction, bisection, differential testing, concurrency, +measurement, tracing, and replay. Comparator claims lacking primary support +were excluded. Conflicts were tested by looking for conditions under which a +technique fails—especially missing oracles, legitimate differential outputs, +noisy benchmarks, and nondeterministic schedules. + +## Primary sources + +- [Simplifying and Isolating Failure-Inducing Input](https://www.st.cs.uni-saarland.de/papers/tse2002/) — Zeller and Hildebrandt, IEEE TSE 28(2), 2002; delta debugging and automated minimisation. +- [Differential Testing for Software](https://www.cs.tufts.edu/comp/150FP/archive/bill-mckeeman/DifferentailTesting.pdf) — McKeeman, Digital Technical Journal 10(1), 1998; comparable-system oracles and limitations. +- [CHESS: A Systematic Testing Tool for Concurrent Software](https://www.usenix.org/legacy/event/osdi08/tech/full_papers/musuvathi/musuvathi_html/index.html) — Musuvathi, Qadeer, and Ball, OSDI 2008; deterministic schedule exploration and replay. +- [An Empirical Analysis of Flaky Tests](https://huang.isis.vanderbilt.edu/cs8395/paper/flakytest.pdf) — Luo et al., FSE 2014; manifestation and repair patterns for nondeterministic tests in an Apache-project sample. +- [QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs](https://research.chalmers.se/en/publication/237427) — Claessen and Hughes, ICFP 2000; property-based generated testing and pitfalls. +- [Dapper, a Large-Scale Distributed Systems Tracing Infrastructure](https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/) — Sigelman et al., Google, 2010; cross-component behavioural and performance tracing. +- [Git bisect documentation](https://git-scm.com/docs/git-bisect) — Git project, current documentation accessed 2026-07-14; automated good/bad predicates. +- [curl manual](https://curl.se/docs/manpage.html) — curl project, current manual accessed 2026-07-14; HTTP scripting, exit behaviour, and limitations. +- [Playwright assertions, HAR replay, and retries](https://playwright.dev/docs/test-assertions) — Microsoft Playwright project, current documentation accessed 2026-07-14; browser oracles, captured-network replay, and flaky classification. +- [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) — LLVM project, current documentation accessed 2026-07-14; narrow deterministic fuzz targets, saved reproducers, minimisation, and regression replay. +- [Google Benchmark user guide](https://github.com/google/benchmark/blob/main/docs/user_guide.md) — Google Benchmark project, current documentation accessed 2026-07-14; warmup, repetition, and variance reporting. +- [OpenTelemetry context propagation](https://opentelemetry.io/docs/concepts/context-propagation/) — OpenTelemetry project, current documentation accessed 2026-07-14; cross-boundary signal correlation. +- [Skill Sections](../../skills/write-skill/references/SECTIONS.md) and [Propulsion Skills Plan](../../SKILLS_PLAN.md) — repository authorities accessed 2026-07-14; progressive disclosure and resource placement. diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 27ec802..ba59d62 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -8,4 +8,46 @@ disable-model-invocation: true # Debug -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Scientific method** turns a repeatable failing signal into a verified causal +repair through falsifiable hypotheses and discriminating experiments. + +## Steps + +1. Read repository instructions and establish the authorised scope, expected + behaviour, observed behaviour, and a repeatable failing signal. Use the + smallest reliable reproduction: a failing test, benchmark, trace, log + pattern, or targeted probe may substitute for a local reproduction when it + distinguishes the fault. When the signal or a later discriminating experiment + is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select + and tighten the smallest applicable one. Preserve pre-existing user work. + When no repeatable signal can be established, leave the implementation + unchanged and report the evidence, blocker, and next discriminating + experiment. The failure and mutation boundary are explicit. +2. Gather evidence and state falsifiable hypotheses in evidence-supported + order. Run the cheapest experiment that distinguishes the leading + hypotheses, changing one variable at a time and recording the result. Use a + **minimal reproducible example**, **binary search**, or **delta debugging** + when it will narrow the failing input, change, component, or boundary. + Repeat until **root-cause analysis** identifies a cause supported by the + experiments rather than a correlated symptom. The demonstrated cause is + explicit before repair. +3. When the user explicitly requested diagnosis only, stop before mutation and + follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and + the fault has a stable regression seam. When TDD is not applicable, apply + the smallest correction to the demonstrated cause and use the repeatable + signal as the immediate feedback loop. Keep the repair within the authorised + scope; report a cause that requires external access or expanded authority as + a blocker. The repair is causal, focused, and covered by the strongest + feasible regression protection. +4. Re-run the original reproduction and confirm the expected behaviour, then + run focused regression coverage, relevant nearby checks, and the + repository-prescribed wider checks. Separate unrelated pre-existing failures + from repair regressions. The original fault is repaired and relevant checks + pass, or the exact remaining failure and uncertainty are explicit. + +## Handoff + +Report the expected and observed behaviour, failing signal, hypotheses and +experiments, root cause, changed files, regression protection, verification +commands and results, and any blocker or unresolved uncertainty. For +diagnosis-only work, state plainly that no implementation was changed. diff --git a/skills/debug/references/TECHNIQUES.md b/skills/debug/references/TECHNIQUES.md new file mode 100644 index 0000000..87e4e5a --- /dev/null +++ b/skills/debug/references/TECHNIQUES.md @@ -0,0 +1,70 @@ +# Debugging Techniques + +Use this reference when the repeatable failing signal or next discriminating +experiment is not obvious. Select the smallest applicable technique; combine +techniques only when each settles a distinct question, then return to the main +workflow. + +## Tighten the Signal + +Run the signal at least once and record its command or probe, input, 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 + non-deterministic 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; compare the +measured failure rate under the same conditions. + +## 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. | +| The fault requires browser behaviour | Headless browser script | Assert the relevant DOM, console, request, or response outcome; retain the smallest trace or fixture that exposes the symptom. | +| Only a production request or event exposes the fault | Capture and replay | Capture the smallest safe request, event, trace, or payload and replay it at the nearest stable seam; retain correlation and environment context without secrets. | +| 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 | Repetition loop | Run the exact trigger repeatedly, report failures per attempts, and control time, randomness, order, load, and environment one dimension at a time. | +| The fault is concurrent | Controlled schedule or race probe | Prefer a recorded or systematic schedule and repository-supported race tooling. Use stress only to amplify and capture a failure, not to prove its absence. | +| The fault is performance | Benchmark loop | Define a representative workload and failing threshold; warm up, repeat, and report variance before profiling the same workload. | + +## 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** | Record hypothesis-relevant input, output, state, configuration, timing, and correlation 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 | Vary one timing, order, load, or scheduling dimension and compare the measured rate. Prefer waiting for observable conditions over guessed delays. | +| A controlled benchmark proves a regression | Profiler, query plan, or resource trace | Identify the work responsible for the measured difference before changing it; 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. From ef05a9012ec195819697e83646e23d9a936027a8 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 08:22:23 +0100 Subject: [PATCH 25/52] feat(review-architecture): add architecture review workflow --- .../20260714-architecture-review-method.md | 231 ++++++++++++++++++ skills/review-architecture/SKILL.md | 75 +++++- .../references/architecture-analysis.md | 149 +++++++++++ .../references/report-design.md | 139 +++++++++++ 4 files changed, 592 insertions(+), 2 deletions(-) create mode 100644 docs/research/20260714-architecture-review-method.md create mode 100644 skills/review-architecture/references/architecture-analysis.md create mode 100644 skills/review-architecture/references/report-design.md diff --git a/docs/research/20260714-architecture-review-method.md b/docs/research/20260714-architecture-review-method.md new file mode 100644 index 0000000..e76baf2 --- /dev/null +++ b/docs/research/20260714-architecture-review-method.md @@ -0,0 +1,231 @@ +--- +title: 'Architecture review method and interactive report design' +createdAt: 2026-07-14 +updatedAt: 2026-07-15 +status: current +--- + +# Architecture review method and interactive report design + +## Research question and scope + +**Question:** Which established methods should govern Propulsion's +`review-architecture` skill, how should it select high-value redesigns from a +codebase, and what interaction and accessibility criteria should govern its +self-contained HTML report? + +**Intended use:** Support the confirmed `review-architecture` skill and its +progressively disclosed analysis and report-design references. + +**Scope:** Static repository inspection, context-aware modular redesign, +quality-attribute trade-offs, incremental migration, architecture fitness +evidence, information visualisation, and accessible HTML. A formal stakeholder +ATAM workshop, implementation of recommendations, framework-specific design +rules, and proof of business priority from source code alone are excluded. + +## Conclusion + +**Information hiding** is the strongest governing methodology. It gives the +review a concrete unit of analysis: difficult or change-prone design decisions +should be hidden behind cohesive module contracts. **Deep modules** operationalise +the desired result, while **design it twice** prevents the first plausible +decomposition from becoming the recommendation by default. + +Use a lightweight adaptation of **ATAM** to rank candidates against evidenced +quality-attribute scenarios and expose risks and trade-offs. The review should +inspect all in-scope architecture and report every redesign whose benefit, +reach, feasibility, and confidence justify action without imposing a minimum or +maximum count. Every retained recommendation should include an incremental +migration path and an observable fitness check. + +Two references are justified: + +- `references/architecture-analysis.md` should hold the conditional diagnostic, + alternative-design, ranking, migration, and fitness guidance; +- `references/report-design.md` should hold the stable HTML information + architecture, visual language, interaction, accessibility, and visual-QA + contract. + +The common inspection-to-report sequence belongs in `SKILL.md`. A reusable +HTML asset or generator script is not yet justified: the report structure is +stable, but its diagrams and evidence are codebase-specific, and the existing +plan explicitly assigns `report-design.md` to this skill. + +## Findings + +### Information hiding supplies the governing decomposition criterion + +Parnas rejects decomposition by processing order and instead starts from +difficult or likely-to-change design decisions, assigning modules that hide +those decisions from one another +([Parnas, 1972](https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf)). +This directly matches the intended review targets: leaked implementation, +shallow interfaces, weak boundaries, and harmful change propagation. + +Ousterhout's Stanford notes make the same criterion operational: a module has +an interface and implementation; information leakage occurs when other modules +depend on implementation knowledge; and bringing leaked knowledge together can +produce a simpler, deeper interface +([modular design notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter18/lecture.php%3Ftopic%3DmodularDesign)). +His course review explicitly includes deep and shallow classes, information +hiding, dependencies, and design it twice as linked design ideas +([course review](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter20/lecture.php?topic=bookReview)). + +**Inference:** the review should map capabilities and contracts rather than +equating modules with directories, files, classes, or services. For each +candidate boundary it should identify the knowledge or design decision being +hidden, the consumers that should depend on the contract, and the details that +should move behind it. A candidate is weaker when it merely adds a layer, +renames folders, or redistributes code without reducing exposed knowledge or +change propagation. + +### Quality scenarios turn general preferences into prioritised redesigns + +ATAM translates business context into quality-attribute scenarios described by +a stimulus and desired response, prioritises them by mission importance and +perceived risk, traces the highest-priority scenarios through architectural +approaches, and identifies risks, sensitivity points, and trade-off points +([SEI report](https://www.sei.cmu.edu/documents/629/2000_005_001_13706.pdf)). +For modifiability, it measures response through affected components, +connectors, interfaces, and change effort. + +The skill cannot run a formal stakeholder workshop from repository evidence +alone. It can still apply the useful core: + +1. recover explicit quality drivers from product context, decisions, + operational configuration, tests, incidents, and repeated change patterns; +2. express relevant drivers as concrete change or runtime scenarios; +3. trace each scenario through modules, contracts, data, and runtime boundaries; +4. label inferred drivers and uncertain priorities rather than presenting them + as stakeholder-confirmed facts; +5. compare at least two materially different boundaries for every serious + candidate before selecting a target design; +6. rank candidates by evidenced quality impact, architectural reach or + recurrence, migration feasibility and risk, and confidence in the evidence. + +This preserves ATAM's trade-off discipline without pretending a static review +has stakeholder authority it does not possess. Recommendation count should be +determined only by the qualifying evidence, including zero findings; ties should +favour higher confidence and an independently deliverable first slice. + +### Supporting principles are diagnostics and conditional patterns + +The supporting concepts should not become an architecture-pattern checklist. +Their useful roles are distinct: + +- **Cohesion and coupling** test whether knowledge that changes together is + gathered behind one contract and whether consumers know more than that + contract requires. **Single responsibility principle** sharpens the same + question around actors or reasons for change + ([Martin's formulation](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html)). +- **Dependency inversion** is relevant when policy depends directly on a + volatile mechanism. **Ports and adapters** is a candidate only when a + purposeful application conversation needs multiple technologies, isolated + tests, or an inside/outside boundary; Cockburn explicitly defines ports by + purposeful conversations and adapters by technology translation + ([original article](https://alistair.cockburn.us/hexagonal-architecture)). +- **Seams** identify places where behaviour can be verified or a dependency + replaced during migration. They are evidence of incremental feasibility, not + a reason to introduce an interface everywhere. +- **Strangler fig** is appropriate when a high-risk existing boundary must be + replaced gradually rather than through a big-bang rewrite + ([Fowler's updated description](https://martinfowler.com/bliki/StranglerFigApplication.html)). +- **Architecture fitness functions** turn a claimed improvement into objective, + repeatable feedback. They may be structural dependency checks, contract or + scenario tests, performance thresholds, security checks, or operational + signals; the measure must correspond to the quality claim + ([Thoughtworks](https://www.thoughtworks.com/en-gb/insights/articles/fitness-function-driven-development)). + +**Inference:** every recommendation should say why its selected pattern fits +this codebase and name a credible alternative it rejected. A recommendation +that invokes a fashionable pattern without evidence of the problem it solves +should be discarded. + +### The report should support comparison before deep reading + +Shneiderman's visual information-seeking method begins with an overview, then +zooming and filtering, then details on demand +([1996 paper](https://www.cs.umd.edu/~ben/papers/Shneiderman1996eyes.pdf)). +This fits the report's decision task: a reader first needs the ranked overview, +then comparison by impact, effort, risk, confidence, or affected capability, +then evidence and migration detail for one recommendation. + +The initial view should therefore contain the review scope, evidence confidence, +current-system overview, and compact recommendation cards. Each card should +make the problem, target boundary, expected improvement, cost, risk, and first +slice comparable without expansion. Details should disclose the evidence, +affected contracts, rejected alternative, migration stages, dependencies, +fitness checks, and source locations. Diagrams should communicate boundary and +dependency changes; prose should remain the fallback when a diagram is not the +clearest representation. + +The confirmed project constraint is one generated HTML file, not offline or +dependency-free operation. It may load current CDN scripts and styles such as +Tailwind and Mermaid when they improve the report, without a graceful-degradation +or long-term compatibility requirement. Visual QA must verify those dependencies +at generation time. WCAG 2.2 requires keyboard operation for all functionality, +and W3C guidance also calls for visible focus, adequate contrast, consistent +interactive styles, and information that does not rely on colour alone +([WCAG 2.2](https://www.w3.org/TR/WCAG22/), +[WAI design guidance](https://w3c.github.io/wai-website/tips/designing/)). + +Visual QA should verify the generated artifact at desktop and narrow viewport +sizes, exercise every control by keyboard, inspect default and expanded states, +check overflow and print output, and confirm that diagrams and evidence remain +understandable without colour. Source links and paths should resolve where the +runtime permits; missing tools should be reported as an explicit verification +limitation rather than silently skipped. + +## Conflicts + +- Single responsibility, dependency inversion, ports and adapters, and the + strangler fig pattern can all improve a design, but applying them as universal + rules can add shallow interfaces and indirection. Information hiding remains + authoritative; the patterns are conditional candidate designs. +- A codebase may evidence technical quality drivers but not their true business + priority. The report must distinguish explicit context from reviewer + inference and lower confidence accordingly. +- Quantitative architecture metrics can create false precision. Ranking should + be an explained comparison supported by source evidence, not an opaque score + whose arithmetic substitutes for judgment. + +## Limitations + +- The primary source for deep modules and design it twice is split between a + commercial book and the author's Stanford course notes. The notes confirm the + concepts and their relationship but do not reproduce the book's full + treatment. +- Forward testing generated and structurally validated an interactive + architecture report, including its filters and unavailable-browser branch. + Actual browser rendering and the optional CDN dependency path remain + unverified because the available browser blocked the local report URL. +- Framework-specific constraints change over time. The eventual skill should + invoke `research` only when a recommendation materially depends on external + framework, language, platform, or architecture evidence that deserves a + durable cited record. + +## Method + +On 2026-07-14, the investigation inspected `SKILLS_PLAN.md`, `CONTEXT.md`, the +target bundle, the authoring contract, the skill-section rules, and the current +research template. It then followed concepts in the plan to original papers, +authors' publications, official institutional reports, and W3C standards. +Evidence was compared across module decomposition, alternative design, +quality-attribute evaluation, migration, continuous verification, information +visualisation, and accessibility. The proposed workflow was falsified against +three risks: pattern-driven overdesign, false stakeholder certainty, and an +interactive report that hides rather than clarifies evidence. + +## Primary sources + +- [On the Criteria To Be Used in Decomposing Systems into Modules](https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf) — David L. Parnas, Communications of the ACM 15(12), 1972; information-hiding decomposition. +- [Modular Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter18/lecture.php%3Ftopic%3DmodularDesign) — John Ousterhout, Stanford CS 190 lecture notes, 2018; deep interfaces and information leakage. +- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter20/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190 lecture notes, 2020; deep modules and design it twice. +- [ATAM: Method for Architecture Evaluation](https://www.sei.cmu.edu/documents/629/2000_005_001_13706.pdf) — Kazman, Klein, and Clements, CMU/SEI-2000-TR-004, 2000; quality scenarios, risk, and trade-offs. +- [Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture) — Alistair Cockburn, original 2005 article; purpose-led ports and technology adapters. +- [The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html) — Robert C. Martin, 2014; actors, reasons for change, cohesion, and coupling. +- [Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html) — Martin Fowler, updated 2024; gradual legacy replacement. +- [Fitness function-driven development](https://www.thoughtworks.com/en-gb/insights/articles/fitness-function-driven-development) — Paula Paul and Rosemary Wang, Thoughtworks, 2019; objective architectural feedback. +- [The Eyes Have It](https://www.cs.umd.edu/~ben/papers/Shneiderman1996eyes.pdf) — Ben Shneiderman, IEEE Symposium on Visual Languages, 1996; overview, filtering, and details on demand. +- [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) — W3C Recommendation, 2023; interaction and presentation accessibility requirements. +- [Designing for Web Accessibility](https://w3c.github.io/wai-website/tips/designing/) — W3C Web Accessibility Initiative, accessed 2026-07-14; practical focus, contrast, colour, and interaction guidance. diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index f6c323c..fa67661 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -1,6 +1,6 @@ --- name: review-architecture -description: Reviews a codebase for modular redesigns and produces an interactive report. Use when architecture boundaries, coupling, or abstractions need assessment. +description: Reviews a codebase or scope for high-value modular redesigns and produces an interactive HTML report. Use when architecture boundaries, coupling, abstractions, or change isolation need assessment. metadata: invocation: user disable-model-invocation: true @@ -8,4 +8,75 @@ disable-model-invocation: true # Review Architecture -Implementation is pending; its confirmed contract is documented in `SKILLS_PLAN.md`. +**Information hiding** turns codebase evidence into modular redesigns whose +small, stable contracts hide cohesive implementation and change-prone decisions. + +## Steps + +1. Establish the review scope. Use the user's explicit scope or the whole + repository with the slug `full-codebase`. Convert an explicit scope to a + concise lowercase hyphenated slug. Inspect project context, architecture + decisions, source, tests, contracts, schemas, dependencies, build and + deployment configuration, and documentation. Exclude generated output, + vendored dependencies, caches, and binaries from detailed analysis unless + they participate in a material boundary. The inspected scope and exclusions + are explicit. +2. Recover quality drivers from explicit project evidence, then apply the + priority order in [Architecture Analysis](references/architecture-analysis.md). + Distinguish confirmed drivers from inference. Ask the user only when an + unknown priority could materially change which redesigns qualify or how they + rank. The review has an evidence-backed quality hierarchy. +3. Use the reference's diagnostics to map cohesive capabilities, public + contracts, hidden decisions, dependency direction, adapters, seams, runtime + boundaries, verification, and change propagation. Treat a module as a + capability with a contract, not as a directory, file, class, or service. + Record repository-relative paths and precise locations for material + evidence. The current architecture and its material pressures are traceable. +4. Apply **design it twice** to every serious candidate. Compare at least two + materially different boundaries, including their contracts, hidden + decisions, dependency direction, quality effects, trade-offs, and migration + seams. Use principles and patterns from the reference only when their + conditions fit the evidence. Discard rearrangements, new layers, and + fashionable patterns that do not materially improve a priority quality. Each + candidate has a tested alternative and a codebase-specific rationale. +5. Invoke `$research` when a candidate materially depends on an external + framework, language, platform, or architecture claim that warrants durable + verification. Use the resulting report as evidence and link it from the + architecture report without duplicating its source catalogue. Repository + evidence remains sufficient when no material external claim exists. +6. Evaluate candidates with explained `high`, `medium`, or `low` impact, + effort, risk, and confidence labels; do not calculate a composite score. + Retain every redesign that clears the reference's high-value threshold, + whether none or many, and rank retained recommendations through the quality + hierarchy and evidence. Record reviewed areas without a qualifying redesign + as concise coverage rather than low-value findings. The result contains no + quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. +7. For each recommendation, define the evidenced problem, affected modules and + contracts, target boundary, rejected alternative, expected quality + improvements, framework fit, costs, risks, dependencies, incremental stages, + containment or rollback route, smallest useful first slice, and observable + architecture fitness checks. Stop before changing implementation or + producing a file-by-file implementation plan. Every recommendation is + independently understandable, actionable, and verifiable. +8. Read [Report Design](references/report-design.md), then create one interactive + HTML file at + `docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an + existing path by adding `-2`, `-3`, and so on before `.html` unless the user + explicitly requests replacement. Generate the overview, comparison, + diagrams, progressive detail, evidence, coverage, and research links from + the completed analysis. The artifact follows the report contract and no + existing report is unintentionally overwritten. +9. Validate the HTML structure and inspect the report in an available browser + at desktop and narrow widths. Verify loaded scripts and styles, diagrams, + filters, pointer and keyboard operation, visible focus, collapsed and + expanded states, overflow, and print output. Correct every material content, + interaction, accessibility, or layout defect. When browser inspection is + unavailable, complete structural checks and mark visual acceptance as + incomplete. The report is either visually accepted or carries an explicit + verification limitation. + +## Handoff + +Return the report path, scope and exclusions, recommendation count, invoked +research reports, validation performed, and unresolved evidence or visual-QA +limitations. Preserve the reviewed implementation unchanged. diff --git a/skills/review-architecture/references/architecture-analysis.md b/skills/review-architecture/references/architecture-analysis.md new file mode 100644 index 0000000..dab0302 --- /dev/null +++ b/skills/review-architecture/references/architecture-analysis.md @@ -0,0 +1,149 @@ +# Architecture Analysis + +Load this reference while mapping, comparing, and ranking architecture +redesigns. It supplies diagnostics and decision criteria; `SKILL.md` owns the +workflow and report boundary. + +## Quality Priority + +Apply the first applicable evidence in this order: + +1. Safety, correctness, security, and data integrity constraints. +2. Explicit project quality drivers. +3. Information hiding and change isolation. +4. Cohesion, coupling, and interface depth. +5. Testability and migration safety. +6. Operability, reliability, performance, scalability, and portability when + evidenced by the system. + +Explicit project evidence overrides the baseline. Recover it 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 concrete scenario: stimulus, affected +capability or boundary, expected response, and observable measure. Label an +inferred driver and its confidence. Ask the user when competing designs depend +on an unknown priority that the repository cannot establish. + +## Architecture Map + +Map capabilities before proposing structure: + +- the purpose and knowledge owned by each capability; +- its public contract, consumers, and promised behaviour; +- the implementation and change-prone decisions the contract hides; +- dependencies entering and leaving the boundary, including shared data; +- framework, storage, network, UI, process, and deployment adapters; +- test, replacement, migration, and operational seams; +- runtime flows for important quality scenarios; +- repeated changes that cross boundaries or force coordinated edits. + +Do not infer an architectural boundary from a directory, namespace, class, +package, service, or deployment unit alone. One architecture module may contain +several internal actions, and one directory may mix several capabilities. + +## Diagnostics + +Use these as questions, not as a pattern checklist. + +| Signal | Test | Redesign direction | Guardrail | +| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | +| Information leakage | Which consumers know a representation, ordering rule, protocol, framework type, or policy that belongs elsewhere? | Gather the knowledge behind one explicit contract. | Moving the same leaked fact to a new helper is not hiding it. | +| Shallow or pass-through interface | Does the interface expose nearly as much complexity as its implementation or repeat another layer's API? | Pull cohesive complexity behind a smaller contract or remove the redundant boundary. | A small function is not automatically a shallow architecture module. | +| Temporal decomposition | Are modules organised by processing steps although the underlying decisions change together? | Group by owned knowledge or capability rather than execution order. | Preserve genuinely independent pipeline stages. | +| Weak cohesion | Do unrelated actors, policies, or change reasons force edits to the same module? | Separate the knowledge that changes for different reasons. | Do not split cohesive internal actions merely to make files smaller. | +| Harmful coupling | Does a change propagate through consumers, create cycles, rely on shared mutable data, or reverse intended policy direction? | Narrow the contract, move ownership, introduce a seam, or invert the volatile dependency. | Coupling is necessary; remove knowledge and coordination, not all connection. | +| Missing seam | Can behaviour be verified or replaced only through the full runtime stack? | Expose the smallest purposeful contract at the volatile boundary. | Do not create interfaces without a verification, replacement, or migration need. | +| Framework leakage | Does domain or application policy depend on transport, persistence, UI, or vendor types? | Translate at an adapter and keep the capability contract in its own language. | Framework conventions may be the correct boundary for framework-owned code. | +| Duplicated policy | Is one rule reimplemented across entry points, services, jobs, or clients? | Give one cohesive module ownership and make callers depend on its contract. | Similar syntax is not necessarily the same policy. | +| Runtime boundary mismatch | Do process, transaction, data ownership, failure, or deployment boundaries cut through a supposedly atomic capability? | Align the contract and migration plan with actual consistency and failure constraints. | Do not force distribution when an in-process boundary is sufficient. | + +Trace every material signal to repository-relative paths and precise locations. +Separate observed facts, conclusions supported by several observations, and +uncertainty. Metrics may locate candidates, but they do not prove a redesign. + +## Design It Twice + +For every serious candidate, compare at least two materially different designs. +A variation in naming, file placement, or interface syntax is not a second +design. For each alternative state: + +- the capability boundary and public contract; +- the knowledge and volatile decisions hidden inside it; +- consumer and dependency direction changes; +- the quality scenarios it improves or worsens; +- framework fit and runtime consequences; +- migration seam, first useful slice, and containment route; +- new complexity, risks, and decisions it creates. + +Prefer the design that hides more relevant knowledge behind the simpler stable +contract while satisfying the higher-priority quality evidence. Reject an +alternative explicitly; do not present the first plausible design as inevitable. + +## Conditional Concepts + +Use a concept only under its condition: + +| Concept | Use when | Avoid when | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| Deep module | A cohesive capability can hide substantial knowledge behind a small stable interface. | The boundary merely combines unrelated work or grows an equally complex interface. | +| Single responsibility | Different actors or change reasons are entangled in one boundary. | A cohesive capability has several internal implementation steps. | +| Dependency inversion | Stable policy depends directly on a volatile mechanism and a purposeful contract can reverse that knowledge dependency. | The abstraction has one accidental consumer and hides no meaningful volatility. | +| Ports and adapters | A purposeful application conversation needs multiple technologies, isolated verification, or replacement. | It would wrap every framework call or create ports without alternate adapters or isolation value. | +| Seam | Verification, replacement, observation, or incremental migration needs a controlled boundary. | Direct use is already stable, observable, and local. | +| Strangler fig | A high-risk boundary must be replaced gradually while old behaviour remains live. | A safe local replacement can be completed and verified atomically. | +| Fitness function | A quality claim can be guarded by an objective repeatable signal. | The proposed measure is a subjective proxy unrelated to the claimed improvement. | + +## Evaluation + +Assign each label with a one-sentence evidence-based rationale: + +- **Impact** — `high` changes a constraint or explicit driver, or removes a + repeated high-reach pressure; `medium` materially improves a bounded + capability; `low` is marginal or mostly local. +- **Effort** — `high` crosses several boundaries or requires staged data, + contract, or deployment work; `medium` needs multiple 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 or an unverified assumption. + +Do not combine labels into a score. Rank qualifying recommendations by the +quality priority, then the strength and reach of impact, confidence in the +evidence, and migration feasibility and risk. Explain judgment where the order +is not obvious. + +A redesign qualifies only when it: + +- materially improves at least one priority quality; +- traces the problem and expected improvement to repository evidence; +- hides or realigns architectural knowledge rather than performing a local + refactor or cosmetic rearrangement; +- has a credible incremental route with known dependencies and risks; and +- is supported strongly enough to recommend, with material uncertainty visible. + +Report every qualifying redesign and none below the threshold. Zero is valid; +there is no minimum or maximum. Record non-qualifying areas only in review +coverage. + +## Migration and Fitness + +For a retained redesign, define stages that keep the system operable and +verifiable. Name prerequisites, the smallest independently useful first slice, +coexistence between old and new boundaries, data or contract transition, +containment or rollback, and removal of the superseded path. Stop before a +file-by-file implementation plan. + +Pair each claimed improvement with observable fitness evidence, such as: + +- forbidden or allowed dependency checks; +- public contract or quality-scenario tests; +- change-impact checks across module boundaries; +- adapter conformance or replacement tests; +- performance, reliability, security, or operability thresholds; +- deployment, telemetry, or runtime signals. + +State the signal, expected result, and where it should run. Prefer existing +verification when it proves the quality; propose new machinery only when needed. diff --git a/skills/review-architecture/references/report-design.md b/skills/review-architecture/references/report-design.md new file mode 100644 index 0000000..e62cd4e --- /dev/null +++ b/skills/review-architecture/references/report-design.md @@ -0,0 +1,139 @@ +# Architecture Review Report Design + +Use this reference when generating and visually verifying the architecture +review HTML. The report is a decision tool, not a static audit or a wall of +technical prose. + +## Information Architecture + +Use one HTML document with this reading order: + +1. **Header** — title, review date, scope, exclusions, evidence confidence, and + a one-sentence outcome. +2. **Current architecture** — a concise capability and boundary overview with a + diagram only when it improves understanding. +3. **Recommendations** — the complete ranked set as comparable summary cards, + followed by filters and progressive detail. A zero-result state plainly says + that no redesign crossed the evidence threshold. +4. **Review coverage** — areas examined without a qualifying redesign and any + evidence limitations. +5. **Method and sources** — repository evidence conventions, invoked research + reports, generation time, and visual-verification status. + +The initial viewport should explain the result and expose the ranked +recommendations without requiring detailed reading. Preserve the ranking as the +default view. When several recommendations exist, allow filtering by affected +capability, impact, effort, risk, and confidence; show the visible count and +provide a clear reset. + +## Recommendation Design + +Make every collapsed card comparable through: + +- rank and action-led title; +- one-sentence evidenced problem; +- target module or boundary; +- expected quality improvement; +- impact, effort, risk, and confidence labels; +- affected capabilities or contracts; +- smallest useful first slice. + +Its expanded detail contains: + +- observed evidence with repository-relative paths and precise locations; +- current and target boundary diagrams where useful; +- the hidden knowledge and proposed public contract; +- framework and runtime fit; +- the alternative considered and why it lost; +- benefits, costs, risks, and unresolved uncertainty; +- dependencies, migration stages, coexistence, and containment or rollback; +- fitness checks with expected results; +- links to any durable research report. + +Use plain language in summaries and retain exact technical names in evidence. +Do not hide a recommendation's main cost, risk, or uncertainty inside the +expanded content. + +## Visual and Interaction Language + +Use strong hierarchy, generous spacing, readable line lengths, restrained +colour, and consistent cards and labels. Paths, symbols, and contracts may use a +monospace face. Use colour to reinforce meaning, never to carry it alone. Avoid +decoration that competes with comparison or implies unsupported precision. + +Scripts, styles, fonts, and diagram libraries may load from CDNs when they help +the current report. Tailwind and Mermaid are suitable defaults: + +```html +<script src="https://cdn.tailwindcss.com"></script> +<script type="module"> + import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; + mermaid.initialize({ + startOnLoad: true, + theme: 'neutral', + securityLevel: 'loose', + }); +</script> +``` + +The artifact must be one generated HTML file, but it need not work offline or +preserve CDN compatibility indefinitely. Verify every selected dependency in +the rendered report at generation time. Escape repository-derived text before +placing it in HTML, attributes, scripts, or diagram definitions. + +Prefer semantic HTML controls and disclosure elements. Filters update results +immediately, preserve an obvious current state, and remain operable without a +pointer. Avoid interactions whose only purpose is visual novelty. + +## Diagrams + +Use a diagram when boundaries, dependency direction, runtime flow, or migration +stages are materially clearer visually. Choose the smallest fitting form: + +- a dependency or boundary graph for current and target modules; +- a flow or sequence for a quality scenario; +- a before-and-after comparison for changed ownership; +- a staged flow for incremental migration. + +Give each diagram one question to answer. Keep nodes few, labels short, arrows +directional, and current and target semantics consistent. Place a concise text +explanation beside it, label the relationship in prose, and do not rely on +colour alone. Avoid ornamental system maps and unreadable whole-repository +graphs. + +## Accessibility and Layout + +- Use semantic landmarks, ordered headings, labelled controls, buttons for + actions, and native disclosure where practical. +- Make every interaction keyboard-operable with a visible focus indicator and + logical focus order. +- Maintain readable text and non-text contrast and pair colour with words, + shapes, or symbols. +- Give tables headers, diagrams accessible names and adjacent explanations, and + icon-only controls accessible labels. +- Reflow cards, filters, diagrams, and evidence at narrow widths without hiding + content or requiring page-level horizontal scrolling. +- Provide print styles that expand recommendation detail, remove interactive + chrome, preserve diagrams and evidence, and avoid splitting short cards + unnecessarily. + +## Visual QA + +Inspect the actual file rather than inferring appearance from source: + +1. Open it with network access and confirm every external script, style, font, + and diagram dependency loads without a material error. +2. Check the overview, the report's actual zero-or-many recommendation state, + filters, reset, and every collapsed and expanded state. +3. Exercise controls with pointer and keyboard; verify focus visibility, order, + labels, and no keyboard trap. +4. Inspect desktop and narrow viewports for hierarchy, wrapping, overflow, + diagram readability, and content order. +5. Check that labels and diagrams remain understandable without colour and that + evidence paths are legible. +6. Inspect print preview for expanded detail, clipping, missing diagrams, and + wasteful page breaks. + +Correct material defects and rerun affected checks. If browser inspection is +unavailable, validate document structure and scripts as far as the environment +allows, then mark visual acceptance incomplete in both the report and handoff. From 3bfb48ad4fccf41860ca2fcb541e5504dc1e527a Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 10:11:37 +0100 Subject: [PATCH 26/52] fix(skills): tighten reviewed contracts --- CONTEXT.md | 4 ++-- SKILLS_PLAN.md | 18 +++++++++++------- skills/code-review/SKILL.md | 3 +-- skills/commit/SKILL.md | 9 ++++++--- skills/research/SKILL.md | 11 +++++------ skills/review-architecture/SKILL.md | 4 ++-- .../references/report-design.md | 10 ++++++---- skills/tdd/SKILL.md | 13 +++++++------ skills/write-skill/SKILL.md | 16 ++++++++++------ 9 files changed, 50 insertions(+), 38 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 22b47d7..10a9f6d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -50,7 +50,7 @@ _Avoid_: Pipeline skill The user-invoked workflow that uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates code-review findings until verified 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 to behaviour changes when the repository has a runnable test suite. It uses Test Desiderata to favour valuable tests that respond to behaviour without coupling to code structure. +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. @@ -61,7 +61,7 @@ The user-invoked workflow that analyses a project's architecture and produces an _Avoid_: Improve-architecture skill **Architecture review report**: -A self-contained 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. +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**: diff --git a/SKILLS_PLAN.md b/SKILLS_PLAN.md index 1acddb3..75618c0 100644 --- a/SKILLS_PLAN.md +++ b/SKILLS_PLAN.md @@ -124,7 +124,9 @@ an existing skill without unintentionally changing its contract. **Boundaries and exclusions:** It authors skill bundles, not the domain work the new skill will later perform. It does not select a governing methodology without -the user's approval or retain source attribution in the finished skill. +the user's approval or retain source attribution in the finished skill. It +executes bundled scripts only within a boundary that blocks external mutation +and production credentials. **Governing methodology:** Use-case modelling. @@ -164,8 +166,9 @@ mechanical and semantic validation. **Intended outcome:** Inspect uncommitted work and create one or more coherent conventional commits without losing or conflating changes. -**Use cases:** Commit one coherent working-tree change; separate mixed concerns -into multiple commits; provide the commit operation used by **pr**. +**Use cases:** Commit one coherent working-tree change at the user's request; +separate mixed concerns into multiple commits; provide the authorised commit +operation used by **pr**. **Boundaries and exclusions:** It does not push, open a pull request, discard changes, or force unrelated work into one commit. @@ -175,7 +178,8 @@ changes, or force unrelated work into one commit. **Supporting concepts:** Atomic commits and interactive staging. **Invocation and composition:** Model-invoked and directly user-invokable. It -has no skill dependencies and is called by **pr**. +acts only from an explicit user request or authorised caller, has no skill +dependencies, and is called by **pr**. **High-level workflow:** @@ -388,8 +392,8 @@ no unresolved in-scope finding. **Intended outcome:** Build observable behaviour one test at a time through durable red-green-refactor cycles. -**Use cases:** Features and bug fixes in repositories that already have a -runnable test suite. +**Use cases:** Features and bug fixes that an existing runnable test suite can +exercise through a stable public seam. **Boundaries and exclusions:** Do not create a test harness merely to make TDD applicable. Documentation, configuration-only changes, and @@ -587,7 +591,7 @@ report. benefits, risks, trade-offs, effort, and migration paths. 4. Keep only the highest-value recommendations and define architecture fitness evidence for each. -5. Generate a self-contained interactive report at +5. Generate a single-file interactive report at docs/architecture/YYYYMMDD-{scope}-architecture-review.html using references/report-design.md for tone, hierarchy, accessibility, diagrams, interaction patterns, and visual QA. diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 89ebd45..9790fc2 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -48,8 +48,7 @@ refactor opportunities independently visible. 5. Apply **falsification** to every candidate against the scoped change, full context, requirements, and repository standards. Run targeted non-mutating tests, type checks, linting, or other checks when they can settle a claim. - Discard personal preferences, unsupported speculation, unrelated pre-existing - debt, and candidates without a demonstrated consequence. Every remaining + Discard any candidate without a demonstrated consequence. Every remaining finding is reproducible or directly evidenced. 6. Use **risk-based prioritisation**: `critical` for immediate data loss, security compromise, or production failure; `high` for incorrect requirements diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index daf8db0..0024a4d 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,6 +1,6 @@ --- name: commit -description: Creates coherent conventional commits from uncommitted work. Use when changes are ready to be inspected, separated, staged, and committed. +description: Creates coherent conventional commits from uncommitted work. Use when the user or an authorised publishing workflow requests ready changes be inspected, separated, staged, and committed. metadata: invocation: model disable-model-invocation: false @@ -13,10 +13,13 @@ messages state each change's intent. ## Steps -1. Inspect `git status`, the repository's Git instructions and current +1. Establish commit authority from an explicit user request or authorised + caller. Inspect `git status`, the repository's Git instructions and current operation, staged, unstaged, and untracked changes, and recent commit messages. Honour user-supplied scope or message constraints and compatible repository - conventions. The complete candidate diff and commit context are explicit. + conventions. When authority is absent or no eligible change remains, report + it and stop without changing Git state. Otherwise the complete candidate diff + and commit context are explicit. 2. Partition eligible changes by coherent intent using **atomic commits**. Keep related implementation, tests, and documentation together while leaving unrelated or ambiguous work uncommitted. Treat a coherent, diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 528fcce..ce78af8 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -43,12 +43,11 @@ report whose material claims trace to primary sources. [the research report template](assets/research-report-template.md). Use a concise lowercase hyphenated title and claim-level links to the primary evidence. Replace every placeholder and retain only applicable lifecycle - fields. Record enough method and source detail for **reproducibility**, but - omit the raw search trail. The report contains the question and scope, - conclusion, cited findings, method, conflicts, limitations, and primary - sources. When a distinct report already occupies the same dated path, append - `-2` to the filename slug and increment it until available without changing - the frontmatter title or H1. + fields. Complete every applicable template section and record enough method + and source detail for **reproducibility**, but omit the raw search trail. When + a distinct report already occupies the same dated path, append `-2` to the + filename slug and increment it until available without changing the + frontmatter title or H1. 6. Preserve **provenance** when related research already exists. Apply a minor correction in place only when it repairs wording, formatting, or the link to the same evidence without changing a material claim; retain `createdAt` and diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index fa67661..1b94048 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -58,8 +58,8 @@ small, stable contracts hide cohesive implementation and change-prone decisions. architecture fitness checks. Stop before changing implementation or producing a file-by-file implementation plan. Every recommendation is independently understandable, actionable, and verifiable. -8. Read [Report Design](references/report-design.md), then create one interactive - HTML file at +8. Read [Report Design](references/report-design.md), then create one single-file + interactive HTML report at `docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an existing path by adding `-2`, `-3`, and so on before `.html` unless the user explicitly requests replacement. Generate the overview, comparison, diff --git a/skills/review-architecture/references/report-design.md b/skills/review-architecture/references/report-design.md index e62cd4e..ee11596 100644 --- a/skills/review-architecture/references/report-design.md +++ b/skills/review-architecture/references/report-design.md @@ -76,10 +76,12 @@ the current report. Tailwind and Mermaid are suitable defaults: </script> ``` -The artifact must be one generated HTML file, but it need not work offline or -preserve CDN compatibility indefinitely. Verify every selected dependency in -the rendered report at generation time. Escape repository-derived text before -placing it in HTML, attributes, scripts, or diagram definitions. +The artifact is a single generated HTML file whose markup and behaviour remain +together; verified CDN dependencies may provide scripts, styles, fonts, and +diagram libraries. It need not work offline or preserve CDN compatibility +indefinitely. Verify every selected dependency in the rendered report at +generation time. Escape repository-derived text before placing it in HTML, +attributes, scripts, or diagram definitions. Prefer semantic HTML controls and disclosure elements. Filters update results immediately, preserve an obvious current state, and remain operable without a diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index def1ed3..db17d1a 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: tdd -description: Builds observable behaviour through red-green-refactor. Use when a feature or bug fix has a runnable test suite. +description: Builds observable behaviour through red-green-refactor. Use when a feature or bug fix can be exercised by an existing runnable test suite through a stable seam. metadata: invocation: model disable-model-invocation: false @@ -14,11 +14,12 @@ internal collaborators, introducing doubles mainly at uncontrollable boundaries. ## Prerequisite -Use an existing runnable test suite. When none exists, report that TDD is not -applicable and return control without creating a test harness. Apply TDD to -observable behaviour, including configuration with observable effects; leave -documentation, configuration-only maintenance, and behaviour-preserving -refactors with the caller. +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. ## Steps diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 128a45a..33c2906 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -15,8 +15,11 @@ processes and context-sensitive outcomes. 1. Inspect the request, complete target bundle, discoverable callers, and host conventions. Select the `Create`, `Review`, or `Improve` branch from the - user's authorised outcome. The branch, evidence, and change boundary are - explicit. + user's authorised outcome. Before executing a bundled script, establish a + disposable filesystem, inert fixtures, blocked external mutation, and no + production credentials; when that boundary is unavailable, leave the script + unexecuted and record the limitation. The branch, evidence, change boundary, + and script-execution boundary are explicit. 2. Follow the selected branch. ### Create @@ -48,8 +51,8 @@ processes and context-sensitive outcomes. material intent decision remains unresolved. The review scope and available contract are explicit. 2. Read [Skill Sections](references/SECTIONS.md), run - [scripts/validate-skill.js](scripts/validate-skill.js), execute every bundled - script in an isolated disposable environment, and acceptance-test the + [scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled + script, execute each safely isolated script, and acceptance-test the representative invocations. Assess the governing methodology, supporting concepts, predictability, composition, structure, language, resources, and observable postconditions while preserving the bundle and user work unchanged. @@ -73,8 +76,9 @@ processes and context-sensitive outcomes. 1. Apply **lossless compression** until every remaining word changes behaviour, preserves a condition, or improves navigation. Each meaning has one authoritative location. -2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute every - bundled script until the mechanical contract passes. +2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute each + safely isolated bundled script until the mechanical contract passes. Report + any script that the common isolation boundary leaves unexecuted. 3. Use **acceptance testing** to replay every confirmed invocation through its branches, resource pointers, and postconditions. Repeat writing, compression, and validation until every scenario passes. From 9533a77f430dbcd2b285aef9bda39f52dc58f10f Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 10:37:07 +0100 Subject: [PATCH 27/52] docs(readme): document recommended workflow --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0406f56..edaac2a 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,57 @@ 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 + +Propulsion skills are independently invocable. For most feature and change +requests, use this recommended workflow: + +1. Shape the idea with `$elicit-with-context` until the request is understood + and confirmed. + + ```text + $elicit-with-context Help me work through an idea for <desired outcome>. + ``` + +2. Implement the confirmed request with `$implement`. + + ```text + $implement the request we just confirmed. + ``` + +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. + +4. Commit the reviewed changes, then create the pull request. + + ```text + $commit the reviewed changes. + Create a $pr for the current branch. + ``` + +### Alternative entry points + +For a bug, start with `$debug` instead of elicitation and implementation: + +```text +$debug Fix <observed problem>. +``` + +After the repair, rejoin the recommended workflow at human review, followed by +`$commit` and `$pr`. + +For codebase improvements, start with `$review-architecture` to produce an +architecture report: + +```text +$review-architecture Review <scope> for high-value architecture improvements. +``` + +Review the report, then take each accepted recommendation through the +recommended workflow separately, beginning with `$elicit-with-context`. + ## Acknowledgements Propulsion is heavily inspired by: -- [obra/superpowers](https://github.com/obra/superpowers) for workflow discipline, review loops, debugging process, and OpenCode plugin ideas - [mattpocock/skills](https://github.com/mattpocock/skills) for brevity, wording discipline, and the question-by-question discovery style From 37d449dce718446e7b093ffc087595c93ff81f99 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 11:23:12 +0100 Subject: [PATCH 28/52] feat(skills): add agent and product definition workflows --- CONTEXT.md | 6 + .../20260715-product-definition-method.md | 144 ++++++++++++++++++ skills/define-product/SKILL.md | 55 +++++++ skills/define-product/agents/openai.yaml | 5 + .../define-product/assets/product-template.md | 63 ++++++++ skills/define-product/references/DISCOVERY.md | 74 +++++++++ skills/maintain-agents/SKILL.md | 49 ++++++ skills/maintain-agents/agents/openai.yaml | 5 + 8 files changed, 401 insertions(+) create mode 100644 docs/research/20260715-product-definition-method.md create mode 100644 skills/define-product/SKILL.md create mode 100644 skills/define-product/agents/openai.yaml create mode 100644 skills/define-product/assets/product-template.md create mode 100644 skills/define-product/references/DISCOVERY.md create mode 100644 skills/maintain-agents/SKILL.md create mode 100644 skills/maintain-agents/agents/openai.yaml diff --git a/CONTEXT.md b/CONTEXT.md index 10a9f6d..5e25794 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -76,6 +76,12 @@ _Avoid_: Large class, shallow module The user-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 Product Vision Board workflow that composes contextual elicitation and conditional research to maintain an evidence-aware root `PRODUCT.md` and domain language in `CONTEXT.md`. It defines strategic direction and capabilities without becoming a roadmap or implementation 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 diff --git a/docs/research/20260715-product-definition-method.md b/docs/research/20260715-product-definition-method.md new file mode 100644 index 0000000..af6d4e5 --- /dev/null +++ b/docs/research/20260715-product-definition-method.md @@ -0,0 +1,144 @@ +--- +title: 'Product definition method' +createdAt: 2026-07-15 +updatedAt: 2026-07-15 +status: current +--- + +# Product definition method + +## Research question and scope + +**Question:** Which established methods should govern a skill that elicits and +documents a new or existing product's purpose, users, needs, differentiation, +strategic features, goals, evidence, and uncertainty without becoming a +roadmap or implementation plan? + +**Intended use:** Support the confirmed `define-product` skill, its reusable +`PRODUCT.md` template, and its conditional discovery reference. + +**Scope:** User-led discovery, static repository evidence, product vision and +strategy, value propositions, strategic feature traceability, and early product +risk. Customer interviews, experiments, roadmap sequencing, feature-level +requirements, delivery planning, and architecture design are excluded. + +## Conclusion + +The **Product Vision Board** is the strongest governing methodology because it +captures an enduring vision and a compact product strategy through target +groups, needs, standout capabilities, and business goals. It applies to new +products and material changes to existing ones while explicitly keeping a +detailed backlog outside the strategy. + +Use three supporting techniques for distinct gaps: the **Value Proposition +Canvas** when user needs and product value are vague; **Impact Mapping** to +trace feature concepts from goals through actors and behaviour change; and the +four product risks to expose uncertainty about value, usability, feasibility, +and viability. Repository archaeology supplies evidence of an existing +product's current behaviour but cannot establish product intent without user +confirmation. + +A reusable `PRODUCT.md` asset and a conditional technique reference are +justified. The asset stabilises the repeated output contract; the reference +keeps branch-specific discovery prompts out of the main skill and avoids +duplicating the elicitation and research dependencies. + +## Findings + +### Product Vision Board defines the durable product strategy + +Roman Pichler's Product Vision Board separates the product's overarching +purpose from the strategy chosen to realise it. Its strategy fields cover the +target market and users, their main needs, three to five standout capabilities, +and business goals. Pichler explicitly places detailed features in the product +backlog and describes the board as applicable to both new products and changes +to existing ones +([Product Vision Board](https://www.romanpichler.com/blog/the-product-vision-board/)). + +**Inference:** `PRODUCT.md` should preserve those stable strategic meanings but +may add current-state evidence, boundaries, risks, and open questions required +by this skill's confirmed use cases. Strategic features should remain +coarse-grained and differentiated rather than becoming an exhaustive feature +inventory. + +### Value Proposition Canvas supplies conditional user-value prompts + +Strategyzer's Value Proposition Canvas distinguishes a customer's jobs, pains, +and gains from the products, pain relievers, and gain creators designed to +serve them. It recommends adjusting the value proposition using customer +evidence rather than treating the initial mapping as established fit +([official template](https://www.strategyzer.com/library/the-value-proposition-canvas)). + +**Inference:** jobs, pains, and gains are useful contingent scaffolding when a +user cannot yet articulate needs or differentiation. They should not become +mandatory fields for every product or imply external validation that has not +occurred. + +### Impact Mapping prevents feature lists without strategic causality + +Impact Mapping grows scope through four linked questions: goal, actors, desired +behaviour impacts, and deliverables. Its primary guidance argues that this +trace makes the reasoning behind a feature inspectable and helps discard work +that does not contribute to a critical impact +([Drawing impact maps](https://www.impactmapping.org/drawing.html)). + +**Inference:** every strategic capability in `PRODUCT.md` should trace to an +actor, desired impact, and product or business goal. The skill should preserve +multiple plausible deliverables as hypotheses and stop before prioritising or +sequencing them into a roadmap. + +### Four product risks expose uncertainty without blocking definition + +SVPG distinguishes value risk, usability risk, feasibility risk, and business +viability risk. The taxonomy broadens discovery beyond whether a feature can be +built and makes the product's different uncertainty classes explicit +([The Four Big Risks](https://www.svpg.com/four-big-risks/)). + +**Inference:** the skill should complete a four-risk pass but may finish with +labelled hypotheses and open questions. Requiring every risk to be resolved +would incorrectly turn product definition into a full validation programme. + +### Existing-system evidence and product intent have different authorities + +Source code, tests, routes, public contracts, and operational configuration can +show what an existing system currently does. They cannot establish why the +product should exist or which future direction is intended. + +**Inference:** the existing-product branch should inspect representative +repository evidence before questioning, label it as observed current state, +and ask the user to resolve contradictions with intended direction. Absence +from inspected code remains unknown rather than proof that a capability does +not exist. + +## Conflicts + +The Product Vision Board recommends validated strategy statements, while the +confirmed skill must also support early ideas that cannot yet be validated. +The skill resolves this by preserving the board's dimensions while explicitly +labelling observations, user-confirmed direction, research, hypotheses, and +unknowns. It does not describe hypotheses as validated findings. + +## Limitations + +The method can establish a coherent product definition from repository and +user evidence, but it cannot prove customer demand, usability, technical +feasibility, or business viability without the corresponding research and +experiments. Impact Mapping establishes a causal hypothesis, not proof that a +feature will create the intended impact. + +## Method + +On 2026-07-15, primary descriptions from the method authors and organisations +were compared against the confirmed use cases. Each method was tested for a +distinct responsibility, overlap with composed skills, applicability to new +and existing products, and risk of crossing into roadmap or implementation +planning. The selected stack was falsified against early unvalidated ideas, +existing repositories whose implementation conflicts with intent, vague user +segments, and feature lists without outcome traces. + +## Primary sources + +- [The Product Vision Board](https://www.romanpichler.com/blog/the-product-vision-board/) — Roman Pichler, updated 2025-10-13, accessed 2026-07-15; vision and product-strategy structure. +- [The Value Proposition Canvas](https://www.strategyzer.com/library/the-value-proposition-canvas) — Strategyzer, published 2026-01-28, accessed 2026-07-15; customer jobs, pains, gains, and value mapping. +- [Drawing impact maps](https://www.impactmapping.org/drawing.html) — Impact Mapping, accessed 2026-07-15; goal, actor, impact, and deliverable trace. +- [The Four Big Risks](https://www.svpg.com/four-big-risks/) — Silicon Valley Product Group, published 2017-12-04, accessed 2026-07-15; value, usability, feasibility, and viability risk taxonomy. diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md new file mode 100644 index 0000000..5d26e0a --- /dev/null +++ b/skills/define-product/SKILL.md @@ -0,0 +1,55 @@ +--- +name: define-product +description: Defines and maintains a product through confirmed discovery. Use when exploring a new product or documenting and redirecting an existing one. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Define Product + +The **Product Vision Board** turns a new idea or existing system into a shared, +evidence-aware product definition that guides strategic features without +becoming a delivery plan. + +## Steps + +1. Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions + and research, and the smallest representative repository evidence. Select a + create or improve branch. For an existing product, treat code and tests as + evidence of current behaviour and the user as the authority on intent; + expose contradictions between them. The branch, current evidence, and + definition boundary are explicit. +2. Invoke `$elicit-with-context` to reach shared understanding of the vision, + users and customers, needs, product type, value proposition, alternatives, + differentiating capabilities, business goals, success signals, boundaries, + current state, and intended direction. When a dimension is unclear, load + only the relevant section of [Discovery Techniques](references/DISCOVERY.md). + Invoke `$research` when external evidence could materially resolve a product + question or help the user formulate a decision; keep its report authoritative + and link applicable findings. Each product dimension is confirmed, supported, + or explicitly uncertain. +3. Use **Impact Mapping** to trace every strategic capability or feature concept + through an actor and desired behaviour change to a product or business goal. + Apply the product-discovery risks of value, usability, feasibility, and + viability as a completeness pass. Classify product state as `current`, + `confirmed direction`, or `hypothesis`, and evidence as `observed`, + `user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature + ideas without a strategic trace or retain them as explicit open questions. + The definition distinguishes direction from evidence and exposes its risks. +4. At `$elicit-with-context`'s final confirmation, create or update the single + root `PRODUCT.md` from the + [Product Definition Template](assets/product-template.md). Preserve one + authoritative meaning for each statement, use canonical terms from + `CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to + durable evidence. Record high-level capabilities and feature concepts while + leaving sequencing, estimates, tickets, implementation, architecture, and + feature-level acceptance criteria to downstream work. The living product + definition reflects the confirmed contract without overstating certainty. +5. Verify every current-state claim against cited repository evidence, every + direction claim against user confirmation, every strategic feature against + its impact trace, and every material uncertainty against the risk pass. + Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and + research reports. Return changed files, the confirmed current state and + direction, supporting research, and unresolved questions. The user receives + a coherent product guide ready to inform later feature work. diff --git a/skills/define-product/agents/openai.yaml b/skills/define-product/agents/openai.yaml new file mode 100644 index 0000000..b14341f --- /dev/null +++ b/skills/define-product/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Define Product' + short_description: 'Discover and document a product direction' +policy: + allow_implicit_invocation: false diff --git a/skills/define-product/assets/product-template.md b/skills/define-product/assets/product-template.md new file mode 100644 index 0000000..7b8b49c --- /dev/null +++ b/skills/define-product/assets/product-template.md @@ -0,0 +1,63 @@ +# {Product name} + +{One sentence stating who the product serves, the outcome it enables, and what +makes its approach distinct.} _Evidence: {status and source}._ + +## Vision + +{The product's purpose and positive change, independent of a particular +implementation.} _Evidence: {status and source}._ + +## Current state + +{For an existing product, summarise its observed purpose, users, capability +groups, lifecycle stage, and material constraints. Cite representative +repository evidence. Omit this section for a new product without a current +state.} + +## Users and needs + +| User or customer | Need or desired outcome | Evidence | +| ---------------- | ----------------------- | ------------------- | +| {Distinct actor} | {Prioritised need} | {Status and source} | + +## Value proposition and differentiation + +{State why each primary user would choose this product over current +alternatives, including non-consumption or manual work. Keep differentiators +specific and few.} _Evidence: {status and source}._ + +## Strategic capabilities + +| State | Capability or feature concept | Actor | Desired impact | Product or business goal | Evidence | +| --------------------------------------------- | ----------------------------- | ------- | ----------------------------- | ------------------------ | ------------------- | +| {current, confirmed direction, or hypothesis} | {High-level capability} | {Actor} | {Behaviour change or outcome} | {Goal} | {Status and source} | + +## Business goals and success signals + +| Goal | Observable success signal | Evidence | +| ------------------------------------- | ------------------------------ | ------------------- | +| {Desired product or business outcome} | {Measure or observable change} | {Status and source} | + +## Boundaries and non-goals + +- {A durable product boundary and why it focuses the definition.} _Evidence: + {status and source}._ + +## Risks and evidence + +| Risk | Current evidence | Hypothesis or open question | +| ----------- | --------------------- | ------------------------------ | +| Value | {Evidence or unknown} | {Material uncertainty or none} | +| Usability | {Evidence or unknown} | {Material uncertainty or none} | +| Feasibility | {Evidence or unknown} | {Material uncertainty or none} | +| Viability | {Evidence or unknown} | {Material uncertainty or none} | + +## Open questions + +- {Unresolved question, why it matters, and the evidence that could resolve it.} + +## Evidence + +- [{Repository artifact or research report}]({relative path}) — {Claim or + decision it supports.} diff --git a/skills/define-product/references/DISCOVERY.md b/skills/define-product/references/DISCOVERY.md new file mode 100644 index 0000000..a916965 --- /dev/null +++ b/skills/define-product/references/DISCOVERY.md @@ -0,0 +1,74 @@ +# Discovery Techniques + +Load only the technique needed by the active elicitation branch. These methods +support product-specific discovery; `$elicit-with-context` remains authoritative +for questioning, confirmation, language, and qualifying architecture decisions. + +## Establish an existing product + +Use **repository archaeology** to recover observed behaviour before asking the +user to restate it. Start with root documentation and manifests, then sample +user entry points, routes or commands, public contracts, data boundaries, +tests, and operational configuration. Follow evidence only until the major +actors and capability groups are stable. Treat absence from the repository as +unknown rather than proof, distinguish shipped behaviour from abandoned or +planned code, and present contradictions with stated intent for resolution. + +## Shape the product strategy + +Use the **Product Vision Board** in needs-first order after establishing the +vision: + +1. State the positive change and enduring purpose. +2. Separate users, customers, and other influential actors. +3. Identify and prioritise their main needs or desired outcomes. +4. Describe the product type and the few capabilities that make it stand out. +5. Define the product or business outcomes that justify investment. + +For an existing product, distinguish the observed current strategy from the +user's confirmed future strategy instead of blending them. + +## Clarify users and value + +When needs or differentiation remain vague, use the **Value Proposition +Canvas** one segment at a time. Ask what the actor is trying to accomplish, +which pains or risks obstruct that outcome, which gains define success, and how +the product relieves the important pains or creates the important gains. Rank +the few that materially influence adoption; preserve unsupported claims as +hypotheses. + +## Trace strategic features + +Use **Impact Mapping** to test each high-level capability or feature concept: + +1. Why: which product or business goal does it support? +2. Who: which actor can help or hinder that goal? +3. How: what observable behaviour or outcome should change? +4. What: which capability might cause or enable that impact? + +Discard an untraceable feature from the definition or record the missing link +as an open question. Keep multiple plausible capabilities as hypotheses; this +is strategic scope, not a roadmap, backlog, or implementation specification. + +## Establish differentiation + +Compare the product with the alternatives users employ today, including manual +work and doing nothing. Invoke `$research` when competitor capabilities, +market conditions, standards, regulation, or user evidence would materially +change the conclusion. Retain only differentiators that serve a prioritised +need and can plausibly influence choice; label the remainder as hypotheses. + +## Expose product risk + +Test the emerging definition against four product-discovery risks: + +- **Value**: users or customers may not choose, adopt, or pay for it. +- **Usability**: users may not understand or successfully use it. +- **Feasibility**: the product may not be buildable with the available + technology, skills, time, or constraints. +- **Viability**: it may not work for the organisation, operating model, legal + obligations, economics, channels, or brand. + +For each material risk, record the available evidence, the remaining +hypothesis, and the smallest evidence that could resolve it. The definition may +finish with uncertainty when that uncertainty is visible and actionable. diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md new file mode 100644 index 0000000..aedee24 --- /dev/null +++ b/skills/maintain-agents/SKILL.md @@ -0,0 +1,49 @@ +--- +name: maintain-agents +description: Initializes and compresses repository-wide agent guidance. Use when creating or improving a root AGENTS.md. +metadata: + invocation: user +disable-model-invocation: true +--- + +# Maintain AGENTS.md + +**Lossless compression** turns repository-wide constraints into the smallest +durable instruction surface an agent needs before reading the code. + +## Steps + +1. Locate the repository root and inspect the root `AGENTS.md`, applicable + instruction layers, and task-relevant repository evidence. Read manifests, + task-runner configuration, CI, and contributor documentation only far enough + to identify the canonical project harness and recover the intent of existing + guidance. The target file, active instruction chain, and candidate harness + are explicit. +2. Classify every existing and proposed instruction. Keep only succinct + project-wide behaviour that applies across tasks and cannot be reliably + inferred from the relevant code, configuration, or documentation, plus a + canonical command whose selection prevents ambiguous verification. Remove + stale guidance, rationale, boilerplate, repository description, duplicated + enforcement, personal preferences, and task-specific workflows. Report each + useful displaced instruction with its smallest appropriate destination, such + as an existing skill, a scoped instruction file, or executable enforcement; + leave those destinations unchanged. Every retained instruction earns its + permanent context cost. +3. Ensure the file states: `When the user corrects you with a reusable, +project-wide rule, ask whether to update AGENTS.md.` Inspect available check + entry points and select one safe aggregate harness that represents completed + work. When alternatives materially differ or a candidate has external side + effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the + check instruction rather than inventing one. The correction feedback loop + and, when available, one canonical completion check are explicit. +4. Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, + merge overlapping meanings, remove headings that add no navigation, and + apply lossless compression until every word changes agent behaviour or + preserves a necessary condition. The file contains one authoritative + expression of each retained rule. +5. Re-read every line against its repository-wide scope and runtime value. + Verify the selected harness exists and run it when it is safe and applicable. + Return the changed file, harness result or limitation, removed instructions + with destinations, and any unresolved conflict in the active instruction + chain. The user receives a thin verified root instruction file and a visible + account of displaced guidance. diff --git a/skills/maintain-agents/agents/openai.yaml b/skills/maintain-agents/agents/openai.yaml new file mode 100644 index 0000000..4755f87 --- /dev/null +++ b/skills/maintain-agents/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Maintain AGENTS.md' + short_description: 'Create or compress repository-wide agent guidance' +policy: + allow_implicit_invocation: false From 9f824beb1f335a051ad41f32b48902c3922d7f2c Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 11:38:48 +0100 Subject: [PATCH 29/52] feat(maintain-context): group related glossary terms --- skills/maintain-context/SKILL.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 2dd8354..8564963 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -25,10 +25,12 @@ choices that shape the codebase. 2. As soon as a term is validated and agreed, create or update the single root `CONTEXT.md` using the [context template](assets/context-template.md). Keep definitions to one or two sentences, add `_Avoid_` only for aliases or - ambiguous alternatives that actually occur, and define domain meaning rather - than implementation, specifications, or general programming concepts. Give - each domain meaning one authoritative entry and link supporting material from - it. The glossary reflects each resolved term before the discussion continues. + ambiguous alternatives that actually occur, and group terms under descriptive + subheadings when natural clusters emerge; keep a flat list when all terms form + one cohesive area. Define domain meaning rather than implementation, + specifications, or general programming concepts. Give each domain meaning one + authoritative entry and link supporting material from it. The glossary + reflects each resolved term before the discussion continues. 3. Test an accepted codebase decision against all three ADR gates: - changing it later has meaningful cost; - a future reader would find it surprising without context; and From 6c4b1a481764b3588d99f5eb719473d1c93415fb Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 13:43:10 +0100 Subject: [PATCH 30/52] refactor(skills): standardize process sections --- CONTEXT.md | 10 +- skills/code-review/SKILL.md | 107 +++++++----- skills/commit/SKILL.md | 73 +++++--- skills/debug/SKILL.md | 77 +++++---- skills/define-product/SKILL.md | 96 ++++++----- skills/elicit-with-context/SKILL.md | 5 + skills/elicit/SKILL.md | 126 ++++++++------ skills/implement/SKILL.md | 42 +++-- skills/maintain-agents/SKILL.md | 84 +++++---- skills/maintain-context/SKILL.md | 109 +++++++----- skills/pr/SKILL.md | 69 +++++--- skills/research/SKILL.md | 122 +++++++------ skills/review-architecture/SKILL.md | 152 +++++++++------- skills/tdd/SKILL.md | 62 ++++--- skills/write-skill/SKILL.md | 172 ++++++++++++------- skills/write-skill/references/SECTIONS.md | 39 +++-- skills/write-skill/scripts/validate-skill.js | 8 + 17 files changed, 806 insertions(+), 547 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 5e25794..7ed7a12 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -106,6 +106,10 @@ _Avoid_: Title, label 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 @@ -139,7 +143,7 @@ A condition that must be true before a skill can begin. Its failure stops the sk _Avoid_: Setup step, pre-flight check **Step**: -An action the agent performs as part of the skill, ordered when sequence matters and ended by an observable postcondition. +A numbered subheading used when actions within a process or branch must occur in order. Its paragraphs describe the action and end in an observable postcondition. _Avoid_: Instruction, rule **Postcondition**: @@ -147,11 +151,11 @@ An observable state that marks a step complete without requiring a separate comp _Avoid_: Completion criterion, completion gate **Rule**: -A cross-cutting invariant that constrains multiple steps or the finished output. +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 steps are complete. +A transfer or route that becomes available after the skill's process is complete. _Avoid_: Next step, final step **Reference**: diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 9790fc2..9e78866 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -12,51 +12,68 @@ disable-model-invocation: false Separate requirements and code-health passes keep delivery gaps, defects, and refactor opportunities independently visible. -## Steps - -1. Resolve the change scope in this order: an explicit caller-supplied scope, - uncommitted tracked and untracked work, then the current branch from its - default-branch merge base. Confirm any revision exists and the change set is - non-empty; report the exact blocker and stop when either check fails, and ask - the user only when multiple scopes remain plausible. Recover requirements - from caller context, a supplied request, specification or ticket, then the - change description and commit history. When none exists, state that there is - no requirements source rather than inventing one. The exact change set and - best available requirements source are explicit. -2. Read repository instructions, relevant context and decisions, changed files - in full, nearby tests, and the surrounding code needed to judge effects. Run - non-mutating verification already required by the repository when its result - materially informs the review. The review evidence and applicable standards - are complete. -3. Perform a **requirements traceability** pass. Compare the change with every - available requirement and identify missing, partial, incorrect, conflicting, - or unrequested behaviour and relevant unhandled cases. When there is no - requirements source, preserve that limitation instead of treating inferred - intent as a requirement. Requirements candidates are explicit. -4. Perform an independent code-health pass across correctness, design, - complexity, tests, naming, documentation, security, performance, reliability, - and repository standards where relevant. Apply the **Test Desiderata** to - changed tests, especially behavioural sensitivity, structure insensitivity, - specificity, and determinism. Use **code smells** as a heuristic baseline: - **Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, - **Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, - **Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, - **Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other - established smells when the changed code provides a concrete cue. A smell - becomes a finding only when evidence shows a worthwhile correction. - Code-health candidates are explicit. -5. Apply **falsification** to every candidate against the scoped change, full - context, requirements, and repository standards. Run targeted non-mutating - tests, type checks, linting, or other checks when they can settle a claim. - Discard any candidate without a demonstrated consequence. Every remaining - finding is reproducible or directly evidenced. -6. Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and - order findings within each from highest to lowest priority. Every reported - finding is actionable. +## Process + +### 1. Resolve the scope + +Resolve the change scope in this order: an explicit caller-supplied scope, +uncommitted tracked and untracked work, then the current branch from its +default-branch merge base. Confirm any revision exists and the change set is +non-empty; report the exact blocker and stop when either check fails, and ask +the user only when multiple scopes remain plausible. Recover requirements +from caller context, a supplied request, specification or ticket, then the +change description and commit history. When none exists, state that there is +no requirements source rather than inventing one. The exact change set and +best available requirements source are explicit. + +### 2. Gather the evidence + +Read repository instructions, relevant context and decisions, changed files +in full, nearby tests, and the surrounding code needed to judge effects. Run +non-mutating verification already required by the repository when its result +materially informs the review. The review evidence and applicable standards +are complete. + +### 3. Trace the requirements + +Perform a **requirements traceability** pass. Compare the change with every +available requirement and identify missing, partial, incorrect, conflicting, +or unrequested behaviour and relevant unhandled cases. When there is no +requirements source, preserve that limitation instead of treating inferred +intent as a requirement. Requirements candidates are explicit. + +### 4. Assess code health + +Perform an independent code-health pass across correctness, design, +complexity, tests, naming, documentation, security, performance, reliability, +and repository standards where relevant. Apply the **Test Desiderata** to +changed tests, especially behavioural sensitivity, structure insensitivity, +specificity, and determinism. Use **code smells** as a heuristic baseline: +**Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, +**Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, +**Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, +**Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other +established smells when the changed code provides a concrete cue. A smell +becomes a finding only when evidence shows a worthwhile correction. +Code-health candidates are explicit. + +### 5. Validate the candidates + +Apply **falsification** to every candidate against the scoped change, full +context, requirements, and repository standards. Run targeted non-mutating +tests, type checks, linting, or other checks when they can settle a claim. +Discard any candidate without a demonstrated consequence. Every remaining +finding is reproducible or directly evidenced. + +### 6. Prioritise the findings + +Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and +order findings within each from highest to lowest priority. Every reported +finding is actionable. ## Rules diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 0024a4d..2b0965c 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -11,31 +11,48 @@ disable-model-invocation: false **Conventional Commits** turns uncommitted work into atomic commits whose messages state each change's intent. -## Steps - -1. Establish commit authority from an explicit user request or authorised - caller. Inspect `git status`, the repository's Git instructions and current - operation, staged, unstaged, and untracked changes, and recent commit messages. - Honour user-supplied scope or message constraints and compatible repository - conventions. When authority is absent or no eligible change remains, report - it and stop without changing Git state. Otherwise the complete candidate diff - and commit context are explicit. -2. Partition eligible changes by coherent intent using **atomic commits**. - Keep related implementation, tests, and documentation together while - leaving unrelated or ambiguous work uncommitted. Treat a coherent, - independent pre-staged set as the first commit; when it mixes concerns or - belongs with unstaged work, ask the user before altering the staged set. - Each planned commit has one explainable purpose. -3. For each concern, retain an already exact staged selection or use - **interactive staging** at file or hunk granularity to stage exactly that - change, then inspect the complete staged diff. The index represents one - atomic change while unselected work remains intact. -4. Write an accurate Conventional Commit message in the form - `type[(scope)][!]: description` for the staged diff. -5. Create the commit and allow configured Git hooks to run. On any failure, - treat hook output as authoritative when present, preserve the index and - working tree, and report the exact output and resulting Git state. Obtain - user direction for any repository or user Git configuration change. -6. Verify each created commit against its recorded diff, inspect the remaining - status before continuing, and return each hash and subject plus work left - uncommitted. +## Process + +### 1. Establish authority and scope + +Establish commit authority from an explicit user request or authorised +caller. Inspect `git status`, the repository's Git instructions and current +operation, staged, unstaged, and untracked changes, and recent commit messages. +Honour user-supplied scope or message constraints and compatible repository +conventions. When authority is absent or no eligible change remains, report +it and stop without changing Git state. Otherwise the complete candidate diff +and commit context are explicit. + +### 2. Partition coherent concerns + +Partition eligible changes by coherent intent using **atomic commits**. +Keep related implementation, tests, and documentation together while +leaving unrelated or ambiguous work uncommitted. Treat a coherent, +independent pre-staged set as the first commit; when it mixes concerns or +belongs with unstaged work, ask the user before altering the staged set. +Each planned commit has one explainable purpose. + +### 3. Stage one concern + +For each concern, retain an already exact staged selection or use +**interactive staging** at file or hunk granularity to stage exactly that +change, then inspect the complete staged diff. The index represents one +atomic change while unselected work remains intact. + +### 4. Write the message + +Write an accurate Conventional Commit message in the form +`type[(scope)][!]: description` for the staged diff. + +### 5. Create the commit + +Create the commit and allow configured Git hooks to run. On any failure, +treat hook output as authoritative when present, preserve the index and +working tree, and report the exact output and resulting Git state. Obtain +user direction for any repository or user Git configuration change. + +### 6. Verify the commits + +Verify each created commit against its recorded diff, inspect the remaining +status before continuing, and return each hash and subject plus work left +uncommitted. diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index ba59d62..0a72fc3 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -11,39 +11,50 @@ disable-model-invocation: true **Scientific method** turns a repeatable failing signal into a verified causal repair through falsifiable hypotheses and discriminating experiments. -## Steps - -1. Read repository instructions and establish the authorised scope, expected - behaviour, observed behaviour, and a repeatable failing signal. Use the - smallest reliable reproduction: a failing test, benchmark, trace, log - pattern, or targeted probe may substitute for a local reproduction when it - distinguishes the fault. When the signal or a later discriminating experiment - is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select - and tighten the smallest applicable one. Preserve pre-existing user work. - When no repeatable signal can be established, leave the implementation - unchanged and report the evidence, blocker, and next discriminating - experiment. The failure and mutation boundary are explicit. -2. Gather evidence and state falsifiable hypotheses in evidence-supported - order. Run the cheapest experiment that distinguishes the leading - hypotheses, changing one variable at a time and recording the result. Use a - **minimal reproducible example**, **binary search**, or **delta debugging** - when it will narrow the failing input, change, component, or boundary. - Repeat until **root-cause analysis** identifies a cause supported by the - experiments rather than a correlated symptom. The demonstrated cause is - explicit before repair. -3. When the user explicitly requested diagnosis only, stop before mutation and - follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and - the fault has a stable regression seam. When TDD is not applicable, apply - the smallest correction to the demonstrated cause and use the repeatable - signal as the immediate feedback loop. Keep the repair within the authorised - scope; report a cause that requires external access or expanded authority as - a blocker. The repair is causal, focused, and covered by the strongest - feasible regression protection. -4. Re-run the original reproduction and confirm the expected behaviour, then - run focused regression coverage, relevant nearby checks, and the - repository-prescribed wider checks. Separate unrelated pre-existing failures - from repair regressions. The original fault is repaired and relevant checks - pass, or the exact remaining failure and uncertainty are explicit. +## Process + +### 1. Establish a repeatable signal + +Read repository instructions and establish the authorised scope, expected +behaviour, observed behaviour, and a repeatable failing signal. Use the +smallest reliable reproduction: a failing test, benchmark, trace, log +pattern, or targeted probe may substitute for a local reproduction when it +distinguishes the fault. When the signal or a later discriminating experiment +is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select +and tighten the smallest applicable one. Preserve pre-existing user work. +When no repeatable signal can be established, leave the implementation +unchanged and report the evidence, blocker, and next discriminating +experiment. The failure and mutation boundary are explicit. + +### 2. Isolate the root cause + +Gather evidence and state falsifiable hypotheses in evidence-supported +order. Run the cheapest experiment that distinguishes the leading +hypotheses, changing one variable at a time and recording the result. Use a +**minimal reproducible example**, **binary search**, or **delta debugging** +when it will narrow the failing input, change, component, or boundary. +Repeat until **root-cause analysis** identifies a cause supported by the +experiments rather than a correlated symptom. The demonstrated cause is +explicit before repair. + +### 3. Repair the cause + +When the user explicitly requested diagnosis only, stop before mutation and +follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and +the fault has a stable regression seam. When TDD is not applicable, apply +the smallest correction to the demonstrated cause and use the repeatable +signal as the immediate feedback loop. Keep the repair within the authorised +scope; report a cause that requires external access or expanded authority as +a blocker. The repair is causal, focused, and covered by the strongest +feasible regression protection. + +### 4. Verify the repair + +Re-run the original reproduction and confirm the expected behaviour, then +run focused regression coverage, relevant nearby checks, and the +repository-prescribed wider checks. Separate unrelated pre-existing failures +from repair regressions. The original fault is repaired and relevant checks +pass, or the exact remaining failure and uncertainty are explicit. ## Handoff diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md index 5d26e0a..e4f79a1 100644 --- a/skills/define-product/SKILL.md +++ b/skills/define-product/SKILL.md @@ -12,44 +12,58 @@ The **Product Vision Board** turns a new idea or existing system into a shared, evidence-aware product definition that guides strategic features without becoming a delivery plan. -## Steps - -1. Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions - and research, and the smallest representative repository evidence. Select a - create or improve branch. For an existing product, treat code and tests as - evidence of current behaviour and the user as the authority on intent; - expose contradictions between them. The branch, current evidence, and - definition boundary are explicit. -2. Invoke `$elicit-with-context` to reach shared understanding of the vision, - users and customers, needs, product type, value proposition, alternatives, - differentiating capabilities, business goals, success signals, boundaries, - current state, and intended direction. When a dimension is unclear, load - only the relevant section of [Discovery Techniques](references/DISCOVERY.md). - Invoke `$research` when external evidence could materially resolve a product - question or help the user formulate a decision; keep its report authoritative - and link applicable findings. Each product dimension is confirmed, supported, - or explicitly uncertain. -3. Use **Impact Mapping** to trace every strategic capability or feature concept - through an actor and desired behaviour change to a product or business goal. - Apply the product-discovery risks of value, usability, feasibility, and - viability as a completeness pass. Classify product state as `current`, - `confirmed direction`, or `hypothesis`, and evidence as `observed`, - `user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature - ideas without a strategic trace or retain them as explicit open questions. - The definition distinguishes direction from evidence and exposes its risks. -4. At `$elicit-with-context`'s final confirmation, create or update the single - root `PRODUCT.md` from the - [Product Definition Template](assets/product-template.md). Preserve one - authoritative meaning for each statement, use canonical terms from - `CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to - durable evidence. Record high-level capabilities and feature concepts while - leaving sequencing, estimates, tickets, implementation, architecture, and - feature-level acceptance criteria to downstream work. The living product - definition reflects the confirmed contract without overstating certainty. -5. Verify every current-state claim against cited repository evidence, every - direction claim against user confirmation, every strategic feature against - its impact trace, and every material uncertainty against the risk pass. - Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and - research reports. Return changed files, the confirmed current state and - direction, supporting research, and unresolved questions. The user receives - a coherent product guide ready to inform later feature work. +## Process + +### 1. Inspect the product context + +Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions +and research, and the smallest representative repository evidence. Select a +create or improve branch. For an existing product, treat code and tests as +evidence of current behaviour and the user as the authority on intent; +expose contradictions between them. The branch, current evidence, and +definition boundary are explicit. + +### 2. Elicit shared understanding + +Invoke `$elicit-with-context` to reach shared understanding of the vision, +users and customers, needs, product type, value proposition, alternatives, +differentiating capabilities, business goals, success signals, boundaries, +current state, and intended direction. When a dimension is unclear, load +only the relevant section of [Discovery Techniques](references/DISCOVERY.md). +Invoke `$research` when external evidence could materially resolve a product +question or help the user formulate a decision; keep its report authoritative +and link applicable findings. Each product dimension is confirmed, supported, +or explicitly uncertain. + +### 3. Trace strategic value + +Use **Impact Mapping** to trace every strategic capability or feature concept +through an actor and desired behaviour change to a product or business goal. +Apply the product-discovery risks of value, usability, feasibility, and +viability as a completeness pass. Classify product state as `current`, +`confirmed direction`, or `hypothesis`, and evidence as `observed`, +`user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature +ideas without a strategic trace or retain them as explicit open questions. +The definition distinguishes direction from evidence and exposes its risks. + +### 4. Write the product definition + +At `$elicit-with-context`'s final confirmation, create or update the single +root `PRODUCT.md` from the +[Product Definition Template](assets/product-template.md). Preserve one +authoritative meaning for each statement, use canonical terms from +`CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to +durable evidence. Record high-level capabilities and feature concepts while +leaving sequencing, estimates, tickets, implementation, architecture, and +feature-level acceptance criteria to downstream work. The living product +definition reflects the confirmed contract without overstating certainty. + +### 5. Verify the definition + +Verify every current-state claim against cited repository evidence, every +direction claim against user confirmation, every strategic feature against +its impact trace, and every material uncertainty against the risk pass. +Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and +research reports. Return changed files, the confirmed current state and +direction, supporting research, and unresolved questions. The user receives +a coherent product guide ready to inform later feature work. diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index 1e92265..7a91fe4 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -8,6 +8,11 @@ disable-model-invocation: true # Elicit with Context +Shared understanding stays aligned with durable project language and +qualifying architecture decisions. + +## Process + Invoke `$elicit`, applying `$maintain-context` throughout. Treat `$elicit`'s final confirmation as the acceptance boundary for qualifying ADRs, then return the elicitation state, context changes, and unresolved language or decisions. diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index 1698946..029943c 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -11,56 +11,76 @@ disable-model-invocation: false **Requirements elicitation** turns choices into confirmed shared understanding while the user directs every decision. -## Steps - -1. Inspect the request, conversation, and task-scoped environment for facts - needed by the current branch. Use accessible read-only sources incrementally - as answers expose new branches. Keep pre-confirmation fact-finding read-only; - when establishing a fact requires a state-changing operation, make that - operation a decision and wait for the user's authorisation. When a material - fact remains unavailable, state the inspected evidence, best-supported - inference, and confidence, then ask one factual verification question. The - current branch has an explicit factual basis. -2. Build and continually update an internal, dependency-ordered **decision - tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, - prerequisites, dependencies, constraints, flows, exceptions, permissions, - risks, and success conditions. Treat the active user as the sole decision - authority. Preserve compatible decisions after a redirection, rebuild - affected branches, and select the highest-impact decision whose dependencies - are resolved. One current decision is explicit. -3. Use **Socratic questioning** to ask exactly one question per turn about one - decision. State the context, recommended answer, concise reasoning, and as - many educated alternatives as help the user think, then ask the decision - once while leaving room for their own answer. Derive recommendations from - the user's confirmed outcome, evidence, project conventions, consequences, - and trade-offs. Treat their choice as authoritative and record a logically - necessary consequence without asking it again. The user confirms the current - decision. -4. Apply **falsification** to each answer through relevant scenarios, - counterexamples, and edge cases. Ask another question only when testing - exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or - conflicting answer on the current branch and reframe its single point of - uncertainty. Answer the user's requests for context directly, then return to - the same decision. Present a discovered constraint and its consequence as - facts, then reframe the decision around feasible options. The answer is clear - and consistent with the confirmed tree. -5. Use **contingent scaffolding** when the user has difficulty deciding. Adapt - the form and clarity of support through plain-language restatement, - alternatives and trade-offs, examples, or scenarios. When useful, replace a - complex decision with its highest-impact prerequisite decisions, resolve - them one at a time, and recombine them. The user reaches and confirms the - decision. -6. Continue until **theoretical saturation**: every relevant dimension has been - assessed, every discovered choice has a confirmed answer, dependencies and - answers are consistent, and a final scenario-and-edge-case pass reveals no - new material branch. Present one concise, self-contained synthesis of the - outcome, boundaries, key decisions, constraints, and observable success - conditions, then ask for explicit confirmation. Shared understanding is - ready for confirmation. -7. When the user corrects or rejects the synthesis, rebuild the affected - branches and continue from step 2 until saturation returns. An affirmative - confirmation completes the contract and authorises the already-requested - downstream outcome. A pause returns a concise checkpoint of confirmed - decisions and the active decision; a cancellation acknowledges the user's - direction and ends without a synthesis or handoff. The caller receives only - the handoff the user selected. +## Process + +### 1. Establish the factual basis + +Inspect the request, conversation, and task-scoped environment for facts +needed by the current branch. Use accessible read-only sources incrementally +as answers expose new branches. Keep pre-confirmation fact-finding read-only; +when establishing a fact requires a state-changing operation, make that +operation a decision and wait for the user's authorisation. When a material +fact remains unavailable, state the inspected evidence, best-supported +inference, and confidence, then ask one factual verification question. The +current branch has an explicit factual basis. + +### 2. Build the decision tree + +Build and continually update an internal, dependency-ordered **decision +tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, +prerequisites, dependencies, constraints, flows, exceptions, permissions, +risks, and success conditions. Treat the active user as the sole decision +authority. Preserve compatible decisions after a redirection, rebuild +affected branches, and select the highest-impact decision whose dependencies +are resolved. One current decision is explicit. + +### 3. Ask one decision + +Use **Socratic questioning** to ask exactly one question per turn about one +decision. State the context, recommended answer, concise reasoning, and as +many educated alternatives as help the user think, then ask the decision +once while leaving room for their own answer. Derive recommendations from +the user's confirmed outcome, evidence, project conventions, consequences, +and trade-offs. Treat their choice as authoritative and record a logically +necessary consequence without asking it again. The user confirms the current +decision. + +### 4. Test the answer + +Apply **falsification** to each answer through relevant scenarios, +counterexamples, and edge cases. Ask another question only when testing +exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or +conflicting answer on the current branch and reframe its single point of +uncertainty. Answer the user's requests for context directly, then return to +the same decision. Present a discovered constraint and its consequence as +facts, then reframe the decision around feasible options. The answer is clear +and consistent with the confirmed tree. + +### 5. Scaffold the decision + +Use **contingent scaffolding** when the user has difficulty deciding. Adapt +the form and clarity of support through plain-language restatement, +alternatives and trade-offs, examples, or scenarios. When useful, replace a +complex decision with its highest-impact prerequisite decisions, resolve +them one at a time, and recombine them. The user reaches and confirms the +decision. + +### 6. Reach theoretical saturation + +Continue until **theoretical saturation**: every relevant dimension has been +assessed, every discovered choice has a confirmed answer, dependencies and +answers are consistent, and a final scenario-and-edge-case pass reveals no +new material branch. Present one concise, self-contained synthesis of the +outcome, boundaries, key decisions, constraints, and observable success +conditions, then ask for explicit confirmation. Shared understanding is +ready for confirmation. + +### 7. Complete or redirect + +When the user corrects or rejects the synthesis, rebuild the affected +branches and continue from step 2 until saturation returns. An affirmative +confirmation completes the contract and authorises the already-requested +downstream outcome. A pause returns a concise checkpoint of confirmed +decisions and the active decision; a cancellation acknowledges the user's +direction and ends without a synthesis or handoff. The caller receives only +the handoff the user selected. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 9c1108e..ca554f5 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -12,23 +12,31 @@ disable-model-invocation: true aim the next one. `$tdd` builds applicable behaviour; `$code-review` assesses the completed implementation independently. -## Steps - -1. Deliver the smallest end-to-end slice that advances the request. Invoke - `$tdd` when its prerequisite applies; otherwise implement directly with the - best available targeted verification. Repeat until every requested behaviour - and acceptance condition is implemented. -2. Invoke `$code-review` with the confirmed request and exact implementation - scope. Address every in-scope finding in priority order, invoking `$tdd` for - applicable behavioural corrections. Invoke `$elicit` when a correction would - materially change agreed behaviour, a public contract, architecture, or - authorised scope. Re-run relevant verification and `$code-review` until its - latest report has no unresolved in-scope findings. -3. Run the repository's prescribed final checks without modifying pre-existing - out-of-scope changes. Isolate a mutating check when needed; when that cannot - be done safely, leave it unrun and report the blocker. Available checks pass, - or the exact blocker and any unrelated pre-existing failure are reported - without claiming full verification. +## Process + +### 1. Deliver a verified slice + +Deliver the smallest end-to-end slice that advances the request. Invoke +`$tdd` when its prerequisite applies; otherwise implement directly with the +best available targeted verification. Repeat until every requested behaviour +and acceptance condition is implemented. + +### 2. Review and remediate + +Invoke `$code-review` with the confirmed request and exact implementation +scope. Address every in-scope finding in priority order, invoking `$tdd` for +applicable behavioural corrections. Invoke `$elicit` when a correction would +materially change agreed behaviour, a public contract, architecture, or +authorised scope. Re-run relevant verification and `$code-review` until its +latest report has no unresolved in-scope findings. + +### 3. Run the final checks + +Run the repository's prescribed final checks without modifying pre-existing +out-of-scope changes. Isolate a mutating check when needed; when that cannot +be done safely, leave it unrun and report the blocker. Available checks pass, +or the exact blocker and any unrelated pre-existing failure are reported +without claiming full verification. ## Rules diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md index aedee24..186823c 100644 --- a/skills/maintain-agents/SKILL.md +++ b/skills/maintain-agents/SKILL.md @@ -11,39 +11,53 @@ disable-model-invocation: true **Lossless compression** turns repository-wide constraints into the smallest durable instruction surface an agent needs before reading the code. -## Steps - -1. Locate the repository root and inspect the root `AGENTS.md`, applicable - instruction layers, and task-relevant repository evidence. Read manifests, - task-runner configuration, CI, and contributor documentation only far enough - to identify the canonical project harness and recover the intent of existing - guidance. The target file, active instruction chain, and candidate harness - are explicit. -2. Classify every existing and proposed instruction. Keep only succinct - project-wide behaviour that applies across tasks and cannot be reliably - inferred from the relevant code, configuration, or documentation, plus a - canonical command whose selection prevents ambiguous verification. Remove - stale guidance, rationale, boilerplate, repository description, duplicated - enforcement, personal preferences, and task-specific workflows. Report each - useful displaced instruction with its smallest appropriate destination, such - as an existing skill, a scoped instruction file, or executable enforcement; - leave those destinations unchanged. Every retained instruction earns its - permanent context cost. -3. Ensure the file states: `When the user corrects you with a reusable, +## Process + +### 1. Inspect the instruction surface + +Locate the repository root and inspect the root `AGENTS.md`, applicable +instruction layers, and task-relevant repository evidence. Read manifests, +task-runner configuration, CI, and contributor documentation only far enough +to identify the canonical project harness and recover the intent of existing +guidance. The target file, active instruction chain, and candidate harness +are explicit. + +### 2. Classify the instructions + +Classify every existing and proposed instruction. Keep only succinct +project-wide behaviour that applies across tasks and cannot be reliably +inferred from the relevant code, configuration, or documentation, plus a +canonical command whose selection prevents ambiguous verification. Remove +stale guidance, rationale, boilerplate, repository description, duplicated +enforcement, personal preferences, and task-specific workflows. Report each +useful displaced instruction with its smallest appropriate destination, such +as an existing skill, a scoped instruction file, or executable enforcement; +leave those destinations unchanged. Every retained instruction earns its +permanent context cost. + +### 3. Establish the required guidance + +Ensure the file states: `When the user corrects you with a reusable, project-wide rule, ask whether to update AGENTS.md.` Inspect available check - entry points and select one safe aggregate harness that represents completed - work. When alternatives materially differ or a candidate has external side - effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the - check instruction rather than inventing one. The correction feedback loop - and, when available, one canonical completion check are explicit. -4. Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, - merge overlapping meanings, remove headings that add no navigation, and - apply lossless compression until every word changes agent behaviour or - preserves a necessary condition. The file contains one authoritative - expression of each retained rule. -5. Re-read every line against its repository-wide scope and runtime value. - Verify the selected harness exists and run it when it is safe and applicable. - Return the changed file, harness result or limitation, removed instructions - with destinations, and any unresolved conflict in the active instruction - chain. The user receives a thin verified root instruction file and a visible - account of displaced guidance. +entry points and select one safe aggregate harness that represents completed +work. When alternatives materially differ or a candidate has external side +effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the +check instruction rather than inventing one. The correction feedback loop +and, when available, one canonical completion check are explicit. + +### 4. Write the root instructions + +Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, +merge overlapping meanings, remove headings that add no navigation, and +apply lossless compression until every word changes agent behaviour or +preserves a necessary condition. The file contains one authoritative +expression of each retained rule. + +### 5. Verify and hand off + +Re-read every line against its repository-wide scope and runtime value. +Verify the selected harness exists and run it when it is safe and applicable. +Return the changed file, harness result or limitation, removed instructions +with destinations, and any unresolved conflict in the active instruction +chain. The user receives a thin verified root instruction file and a visible +account of displaced guidance. diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 8564963..46ce193 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -12,49 +12,66 @@ disable-model-invocation: false refinement; concise architecture decision records preserve the consequential choices that shape the codebase. -## Steps - -1. Compare domain language in the conversation with the root `CONTEXT.md` and - relevant code. Challenge vague, overloaded, or conflicting terms, propose - one precise canonical term, and test it with concrete scenarios and edge - cases. Treat code as evidence of current behaviour and the user's confirmed - answer as intent; surface contradictions for resolution. Reuse a compatible - convention and obtain agreement before moving or reshaping conflicting - durable records. The term is either validated with the user or remains - explicitly unresolved. -2. As soon as a term is validated and agreed, create or update the single root - `CONTEXT.md` using the [context template](assets/context-template.md). Keep - definitions to one or two sentences, add `_Avoid_` only for aliases or - ambiguous alternatives that actually occur, and group terms under descriptive - subheadings when natural clusters emerge; keep a flat list when all terms form - one cohesive area. Define domain meaning rather than implementation, - specifications, or general programming concepts. Give each domain meaning one - authoritative entry and link supporting material from it. The glossary - reflects each resolved term before the discussion continues. -3. Test an accepted codebase decision against all three ADR 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 only when all three gates pass. The decision is either rejected - as routine or identified as a qualifying architectural decision. - -4. After a qualifying decision is accepted, 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 the file - `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision - first, then only the context and significant ramifications needed to explain - it. Give each architectural decision one authoritative ADR. Require only - `Decision`, `Context`, and `Ramifications` as content sections, in that order; - reserve frontmatter for `status` and conditional supersession links. Link - supporting material from that record. The new ADR is brief, accepted, - sequentially numbered, and readable from its filename. -5. When an accepted decision changes, read only the specific ADR it supersedes, - preserve that record, and create a new one. Set the old record's `status` to - `superseded` with a relative `superseded-by` link, and give the new record a - relative `supersedes` link; leave the old decision, context, and ramifications - unchanged. Both records expose the decision history in both directions. -6. Re-read every changed artifact against the resolved language, accepted - decisions, and relevant code evidence, then report the files changed and any - unresolved contradiction. The handoff identifies a consistent durable - record or names the exact uncertainty that prevented one. +## Process + +### 1. Resolve project language + +Compare domain language in the conversation with the root `CONTEXT.md` and +relevant code. Challenge vague, overloaded, or conflicting terms, propose +one precise canonical term, and test it with concrete scenarios and edge +cases. Treat code as evidence of current behaviour and the user's confirmed +answer as intent; surface contradictions for resolution. Reuse a compatible +convention and obtain agreement before moving or reshaping conflicting +durable records. The term is either validated with the user or remains +explicitly unresolved. + +### 2. Maintain the glossary + +As soon as a term is validated and agreed, create or update the single root +`CONTEXT.md` using the [context template](assets/context-template.md). Keep +definitions to one or two sentences, add `_Avoid_` only for aliases or +ambiguous alternatives that actually occur, and group terms under descriptive +subheadings when natural clusters emerge; keep a flat list when all terms form +one cohesive area. Define domain meaning rather than implementation, +specifications, or general programming concepts. Give each domain meaning one +authoritative entry and link supporting material from it. The glossary +reflects each resolved term before the discussion continues. + +### 3. Test the ADR gates + +Test an accepted codebase decision against all three ADR 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 only when all three gates pass. The decision is either rejected +as routine or identified as a qualifying architectural decision. + +### 4. Record a qualifying decision + +After a qualifying decision is accepted, 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 the file +`NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision +first, then only the context and significant ramifications needed to explain +it. Give each architectural decision one authoritative ADR. Require only +`Decision`, `Context`, and `Ramifications` as content sections, in that order; +reserve frontmatter for `status` and conditional supersession links. Link +supporting material from that record. The new ADR is brief, accepted, +sequentially numbered, and readable from its filename. + +### 5. Supersede a changed decision + +When an accepted decision changes, read only the specific ADR it supersedes, +preserve that record, and create a new one. Set the old record's `status` to +`superseded` with a relative `superseded-by` link, and give the new record a +relative `supersedes` link; leave the old decision, context, and ramifications +unchanged. Both records expose the decision history in both directions. + +### 6. Verify and hand off + +Re-read every changed artifact against the resolved language, accepted +decisions, and relevant code evidence, then report the files changed and any +unresolved contradiction. The handoff identifies a consistent durable +record or names the exact uncertainty that prevented one. diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md index 02167a9..289da12 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -19,29 +19,46 @@ and a distinct base branch are required. Use the user-supplied base or the remote's default branch. Report the missing condition and stop when a prerequisite cannot be resolved. -## Steps - -1. Inspect repository instructions and pull-request templates, Git status and - current operation, the current branch, GitHub remotes, authentication, the - selected base, and any existing pull request for the branch. The publication - context and applicable repository requirements are explicit before mutation. -2. Invoke `$commit` when eligible uncommitted work exists. Continue with its - reported commits and intentionally excluded work visible. -3. Fetch the selected remote base, find its merge base with `HEAD`, and inspect - the complete commit history and diff from that point. Stop when the branch - has no publishable diff; otherwise the full pull-request scope is explicit. -4. Derive an accurate Conventional Commit title in the form - `type[(scope)][!]: description` for the complete diff. Populate every required - repository-template section; without a required template, write one short - **BLUF** paragraph explaining what changed and why. The title and body - represent the complete branch rather than one commit. -5. Push the current branch without rewriting remote history and create a ready - pull request against the selected base, or a draft only when the user - explicitly requested one. When an open pull request already represents the - branch, reuse it and reconcile its base, title, body, and ready or draft state - with the selected publication context. The remote branch and one - corresponding pull request exist with the requested metadata and state. -6. Verify the pull request's head, base, draft state, title, and body against the - inspected scope and repository requirements. Return its URL and report any - failed publication or verification with the resulting local and remote - state. +## Process + +### 1. Inspect the publication context + +Inspect repository instructions and pull-request templates, Git status and +current operation, the current branch, GitHub remotes, authentication, the +selected base, and any existing pull request for the branch. The publication +context and applicable repository requirements are explicit before mutation. + +### 2. Commit eligible work + +Invoke `$commit` when eligible uncommitted work exists. Continue with its +reported commits and intentionally excluded work visible. + +### 3. Establish the pull-request scope + +Fetch the selected remote base, find its merge base with `HEAD`, and inspect +the complete commit history and diff from that point. Stop when the branch +has no publishable diff; otherwise the full pull-request scope is explicit. + +### 4. Write the pull request + +Derive an accurate Conventional Commit title in the form +`type[(scope)][!]: description` for the complete diff. Populate every required +repository-template section; without a required template, write one short +**BLUF** paragraph explaining what changed and why. The title and body +represent the complete branch rather than one commit. + +### 5. Publish the branch + +Push the current branch without rewriting remote history and create a ready +pull request against the selected base, or a draft only when the user +explicitly requested one. When an open pull request already represents the +branch, reuse it and reconcile its base, title, body, and ready or draft state +with the selected publication context. The remote branch and one +corresponding pull request exist with the requested metadata and state. + +### 6. Verify the pull request + +Verify the pull request's head, base, draft state, title, and body against the +inspected scope and repository requirements. Return its URL and report any +failed publication or verification with the resulting local and remote +state. diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index ce78af8..43e8f52 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -11,54 +11,74 @@ disable-model-invocation: false **Evidence synthesis** turns a scoped question into a reproducible repository report whose material claims trace to primary sources. -## Steps - -1. 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 any ambiguity - that could materially change the investigation; the research contract and - applicable prior evidence are explicit. -2. When the host supports background agents, delegate source discovery, - appraisal, synthesis, and report writing with the complete research - contract, relevant repository context, primary-source standard, and output - contract. Continue only independent caller work while it runs, then validate - its result. Perform the workflow inline when delegation is unavailable or - fails, and repair an invalid delegated result before handoff. One researcher - owns the investigation and report at a time. -3. Discover the strongest applicable primary evidence, including official - documentation, source code, standards, original publications, first-party - APIs, or first-party data. Use secondary sources only to locate originals. - Apply **source criticism** to authority, proximity, currency, applicability, - and stability; use **citation chaining** to reach the evidence behind - material claims. The evidence set is relevant, current enough for the - question, and traceable. -4. Compare independent evidence through **triangulation** and test emerging - conclusions through **falsification**. 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. -5. 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 the primary - evidence. Replace every placeholder and retain only applicable lifecycle - fields. Complete every applicable template section and record enough method - and source detail for **reproducibility**, but omit the raw search trail. When - a distinct report already occupies the same dated path, append `-2` to the - filename slug and increment it until available without changing the - frontmatter title or H1. -6. Preserve **provenance** when related research already exists. Apply a minor - correction in place only when it repairs wording, formatting, or the link to - the same evidence without changing a material claim; retain `createdAt` and - change `updatedAt`. New evidence, changed scope, or a materially changed - finding creates a new dated snapshot with `supersedes`; mark the previous - snapshot `superseded` and add its relative `supersededBy` link without - rewriting its historical findings. The report history distinguishes - correction from substantive refresh. -7. Verify that each material claim is supported by its cited primary source, - every link and relative report path resolves, conflicts and uncertainty are - visible, and the recorded method can reproduce the investigation. 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. +## Process + +### 1. Define the research contract + +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 any ambiguity +that could materially change the investigation; the research contract and +applicable prior evidence are explicit. + +### 2. Assign the investigation + +When the host supports background agents, delegate source discovery, +appraisal, synthesis, and report writing with the complete research +contract, relevant repository context, primary-source standard, and output +contract. Continue only independent caller work while it runs, then validate +its result. Perform the workflow inline when delegation is unavailable or +fails, and repair an invalid delegated result before handoff. One researcher +owns the investigation and report at a time. + +### 3. Discover primary evidence + +Discover the strongest applicable primary evidence, including official +documentation, source code, standards, original publications, first-party +APIs, or first-party data. Use secondary sources only to locate originals. +Apply **source criticism** to authority, proximity, currency, applicability, +and stability; use **citation chaining** to reach the evidence behind +material claims. The evidence set is relevant, current enough for the +question, and traceable. + +### 4. Synthesize the findings + +Compare independent evidence through **triangulation** and test emerging +conclusions through **falsification**. 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. + +### 5. Write the research report + +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 the primary +evidence. Replace every placeholder and retain only applicable lifecycle +fields. Complete every applicable template section and record enough method +and source detail for **reproducibility**, but omit the raw search trail. When +a distinct report already occupies the same dated path, append `-2` to the +filename slug and increment it until available without changing the +frontmatter title or H1. + +### 6. Preserve provenance + +Preserve **provenance** when related research already exists. Apply a minor +correction in place only when it repairs wording, formatting, or the link to +the same evidence without changing a material claim; retain `createdAt` and +change `updatedAt`. New evidence, changed scope, or a materially changed +finding creates a new dated snapshot with `supersedes`; mark the previous +snapshot `superseded` and add its relative `supersededBy` link without +rewriting its historical findings. The report history distinguishes +correction from substantive refresh. + +### 7. Verify and hand off + +Verify that each material claim is supported by its cited primary source, +every link and relative report path resolves, conflicts and uncertainty are +visible, and the recorded method can reproduce the investigation. 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. diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index 1b94048..8e9c5bd 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -11,69 +11,95 @@ disable-model-invocation: true **Information hiding** turns codebase evidence into modular redesigns whose small, stable contracts hide cohesive implementation and change-prone decisions. -## Steps - -1. Establish the review scope. Use the user's explicit scope or the whole - repository with the slug `full-codebase`. Convert an explicit scope to a - concise lowercase hyphenated slug. Inspect project context, architecture - decisions, source, tests, contracts, schemas, dependencies, build and - deployment configuration, and documentation. Exclude generated output, - vendored dependencies, caches, and binaries from detailed analysis unless - they participate in a material boundary. The inspected scope and exclusions - are explicit. -2. Recover quality drivers from explicit project evidence, then apply the - priority order in [Architecture Analysis](references/architecture-analysis.md). - Distinguish confirmed drivers from inference. Ask the user only when an - unknown priority could materially change which redesigns qualify or how they - rank. The review has an evidence-backed quality hierarchy. -3. Use the reference's diagnostics to map cohesive capabilities, public - contracts, hidden decisions, dependency direction, adapters, seams, runtime - boundaries, verification, and change propagation. Treat a module as a - capability with a contract, not as a directory, file, class, or service. - Record repository-relative paths and precise locations for material - evidence. The current architecture and its material pressures are traceable. -4. Apply **design it twice** to every serious candidate. Compare at least two - materially different boundaries, including their contracts, hidden - decisions, dependency direction, quality effects, trade-offs, and migration - seams. Use principles and patterns from the reference only when their - conditions fit the evidence. Discard rearrangements, new layers, and - fashionable patterns that do not materially improve a priority quality. Each - candidate has a tested alternative and a codebase-specific rationale. -5. Invoke `$research` when a candidate materially depends on an external - framework, language, platform, or architecture claim that warrants durable - verification. Use the resulting report as evidence and link it from the - architecture report without duplicating its source catalogue. Repository - evidence remains sufficient when no material external claim exists. -6. Evaluate candidates with explained `high`, `medium`, or `low` impact, - effort, risk, and confidence labels; do not calculate a composite score. - Retain every redesign that clears the reference's high-value threshold, - whether none or many, and rank retained recommendations through the quality - hierarchy and evidence. Record reviewed areas without a qualifying redesign - as concise coverage rather than low-value findings. The result contains no - quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. -7. For each recommendation, define the evidenced problem, affected modules and - contracts, target boundary, rejected alternative, expected quality - improvements, framework fit, costs, risks, dependencies, incremental stages, - containment or rollback route, smallest useful first slice, and observable - architecture fitness checks. Stop before changing implementation or - producing a file-by-file implementation plan. Every recommendation is - independently understandable, actionable, and verifiable. -8. Read [Report Design](references/report-design.md), then create one single-file - interactive HTML report at - `docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an - existing path by adding `-2`, `-3`, and so on before `.html` unless the user - explicitly requests replacement. Generate the overview, comparison, - diagrams, progressive detail, evidence, coverage, and research links from - the completed analysis. The artifact follows the report contract and no - existing report is unintentionally overwritten. -9. Validate the HTML structure and inspect the report in an available browser - at desktop and narrow widths. Verify loaded scripts and styles, diagrams, - filters, pointer and keyboard operation, visible focus, collapsed and - expanded states, overflow, and print output. Correct every material content, - interaction, accessibility, or layout defect. When browser inspection is - unavailable, complete structural checks and mark visual acceptance as - incomplete. The report is either visually accepted or carries an explicit - verification limitation. +## Process + +### 1. Establish the review scope + +Establish the review scope. Use the user's explicit scope or the whole +repository with the slug `full-codebase`. Convert an explicit scope to a +concise lowercase hyphenated slug. Inspect project context, architecture +decisions, source, tests, contracts, schemas, dependencies, build and +deployment configuration, and documentation. Exclude generated output, +vendored dependencies, caches, and binaries from detailed analysis unless +they participate in a material boundary. The inspected scope and exclusions +are explicit. + +### 2. Recover the quality drivers + +Recover quality drivers from explicit project evidence, then apply the +priority order in [Architecture Analysis](references/architecture-analysis.md). +Distinguish confirmed drivers from inference. Ask the user only when an +unknown priority could materially change which redesigns qualify or how they +rank. The review has an evidence-backed quality hierarchy. + +### 3. Map the architecture + +Use the reference's diagnostics to map cohesive capabilities, public +contracts, hidden decisions, dependency direction, adapters, seams, runtime +boundaries, verification, and change propagation. Treat a module as a +capability with a contract, not as a directory, file, class, or service. +Record repository-relative paths and precise locations for material +evidence. The current architecture and its material pressures are traceable. + +### 4. Design each candidate twice + +Apply **design it twice** to every serious candidate. Compare at least two +materially different boundaries, including their contracts, hidden +decisions, dependency direction, quality effects, trade-offs, and migration +seams. Use principles and patterns from the reference only when their +conditions fit the evidence. Discard rearrangements, new layers, and +fashionable patterns that do not materially improve a priority quality. Each +candidate has a tested alternative and a codebase-specific rationale. + +### 5. Research material external claims + +Invoke `$research` when a candidate materially depends on an external +framework, language, platform, or architecture claim that warrants durable +verification. Use the resulting report as evidence and link it from the +architecture report without duplicating its source catalogue. Repository +evidence remains sufficient when no material external claim exists. + +### 6. Evaluate and rank the candidates + +Evaluate candidates with explained `high`, `medium`, or `low` impact, +effort, risk, and confidence labels; do not calculate a composite score. +Retain every redesign that clears the reference's high-value threshold, +whether none or many, and rank retained recommendations through the quality +hierarchy and evidence. Record reviewed areas without a qualifying redesign +as concise coverage rather than low-value findings. The result contains no +quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. + +### 7. Define the recommendations + +For each recommendation, define the evidenced problem, affected modules and +contracts, target boundary, rejected alternative, expected quality +improvements, framework fit, costs, risks, dependencies, incremental stages, +containment or rollback route, smallest useful first slice, and observable +architecture fitness checks. Stop before changing implementation or +producing a file-by-file implementation plan. Every recommendation is +independently understandable, actionable, and verifiable. + +### 8. Create the report + +Read [Report Design](references/report-design.md), then create one single-file +interactive HTML report at +`docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an +existing path by adding `-2`, `-3`, and so on before `.html` unless the user +explicitly requests replacement. Generate the overview, comparison, +diagrams, progressive detail, evidence, coverage, and research links from +the completed analysis. The artifact follows the report contract and no +existing report is unintentionally overwritten. + +### 9. Validate the report + +Validate the HTML structure and inspect the report in an available browser +at desktop and narrow widths. Verify loaded scripts and styles, diagrams, +filters, pointer and keyboard operation, visible focus, collapsed and +expanded states, overflow, and print output. Correct every material content, +interaction, accessibility, or layout defect. When browser inspection is +unavailable, complete structural checks and mark visual acceptance as +incomplete. The report is either visually accepted or carries an explicit +verification limitation. ## Handoff diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index db17d1a..42d2fc4 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -21,30 +21,44 @@ 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. -## Steps - -1. Read repository instructions, identify the relevant test command, and run the - existing suite to establish a known baseline. Separate unrelated existing - failures from the change, then select the smallest observable behaviour. The - baseline, test seam, and next behaviour are explicit. -2. **Red:** use **Arrange-Act-Assert** to add one focused test through a stable - public interface. For a bug, reproduce the incorrect behaviour; adopt an - already-failing regression test only when it independently specifies the - desired behaviour. Run the test and confirm that it fails for the expected - behavioural reason rather than a test defect or environment error. When it - does not, remain in Red: correct an in-scope test defect or report an - environment blocker, then rerun until the expected failure is observed. - Meaningful red evidence is recorded before Green begins. -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 hiding baseline failures. -4. **Refactor:** improve the test and production code while keeping behaviour - fixed. Run the focused tests after each material change until the design is - clear and green. The cycle ends with no refactor regression. -5. 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. +## Process + +### 1. Establish the baseline + +Read repository instructions, identify the relevant test command, and run the +existing suite to establish a known baseline. Separate unrelated existing +failures from the change, then select the smallest observable behaviour. The +baseline, test seam, and next behaviour are explicit. + +### 2. Red + +Use **Arrange-Act-Assert** to add one focused test through a stable +public interface. For a bug, reproduce the incorrect behaviour; adopt an +already-failing regression test only when it independently specifies the +desired behaviour. Run the test and confirm that it fails for the expected +behavioural reason rather than a test defect or environment error. When it +does not, remain in Red: correct an in-scope test defect or report an +environment blocker, then rerun until the expected failure is observed. +Meaningful red evidence is recorded before Green begins. + +### 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 hiding baseline failures. + +### 4. Refactor + +Improve the test and production code while keeping behaviour +fixed. Run the focused tests after each material change until the design is +clear and green. The cycle ends with no refactor regression. + +### 5. Complete the cycles + +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. ## Test Quality diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 33c2906..fec700c 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -11,80 +11,124 @@ disable-model-invocation: true **Use-case modelling** turns confirmed needs into skills with predictable processes and context-sensitive outcomes. -## Steps +## Process -1. Inspect the request, complete target bundle, discoverable callers, and host - conventions. Select the `Create`, `Review`, or `Improve` branch from the - user's authorised outcome. Before executing a bundled script, establish a - disposable filesystem, inert fixtures, blocked external mutation, and no - production credentials; when that boundary is unavailable, leave the script - unexecuted and record the limitation. The branch, evidence, change boundary, - and script-execution boundary are explicit. -2. Follow the selected branch. +### 1. Select the branch + +Inspect the request, complete target bundle, discoverable callers, and host +conventions. Select the `Create`, `Review`, or `Improve` branch from the +user's authorised outcome. Before executing a bundled script, establish a +disposable filesystem, inert fixtures, blocked external mutation, and no +production credentials; when that boundary is unavailable, leave the script +unexecuted and record the limitation. The branch, evidence, change boundary, +and script-execution boundary are explicit. + +Follow the selected branch. ### Create -1. Invoke `$elicit` to confirm concrete invocations, goals, inputs, outputs, - prerequisites, flows, branches, failures, composition, permissions, - postconditions, and resource needs. During the interview, invoke `$research` - when selecting the methodology or another material question warrants durable - evidence. Recommend one governing methodology and supporting concepts only - for distinct concerns; `$elicit`'s final confirmation approves the complete - contract and authorises writing. -2. Choose a short verb-led name through **ubiquitous language** and an invocation - policy whose context cost matches expected use. Read - [Skill Sections](references/SECTIONS.md), then use **Unix philosophy** and - **YAGNI** to choose the smallest independently useful bundle. The name, - invocation, structure, and resources serve the confirmed use cases. -3. Write the bundle with canonical **leading words** where they govern - behaviour. Apply **progressive disclosure** to conditional knowledge, - **degrees of freedom** to instruction precision, **DRY** to authority, and - **ironic process theory** to steer language toward the intended action. The - complete bundle expresses the confirmed contract through canonical terms; - source provenance remains in the research evidence. -4. Follow `Validate Create or Improve`. +#### 1. Confirm the contract + +Invoke `$elicit` to confirm concrete invocations, goals, inputs, outputs, +prerequisites, flows, branches, failures, composition, permissions, +postconditions, and resource needs. During the interview, invoke `$research` +when selecting the methodology or another material question warrants durable +evidence. Recommend one governing methodology and supporting concepts only +for distinct concerns; `$elicit`'s final confirmation approves the complete +contract and authorises writing. + +#### 2. Design the bundle + +Choose a short verb-led name through **ubiquitous language** and an invocation +policy whose context cost matches expected use. Read +[Skill Sections](references/SECTIONS.md), then use **Unix philosophy** and +**YAGNI** to choose the smallest independently useful bundle. The name, +invocation, structure, and resources serve the confirmed use cases. + +#### 3. Write the bundle + +Write the bundle with canonical **leading words** where they govern +behaviour. Apply **progressive disclosure** to conditional knowledge, +**degrees of freedom** to instruction precision, **DRY** to authority, and +**ironic process theory** to steer language toward the intended action. The +complete bundle expresses the confirmed contract through canonical terms; +source provenance remains in the research evidence. + +#### 4. Validate the bundle + +Follow `Validate Create or Improve`. ### Review -1. Recover the intended contract from the complete bundle, callers, host - conventions, and representative prompts. Invoke `$elicit` only when a - material intent decision remains unresolved. The review scope and available - contract are explicit. -2. Read [Skill Sections](references/SECTIONS.md), run - [scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled - script, execute each safely isolated script, and acceptance-test the - representative invocations. Assess the governing methodology, supporting - concepts, predictability, composition, structure, language, resources, and - observable postconditions while preserving the bundle and user work unchanged. -3. Return concise, prioritised findings. For each, name the governing concept, - cite the evidence and behavioural consequence, and recommend the smallest - effective improvement. Affirm the skill plainly when no material finding - remains. +#### 1. Recover the contract + +Recover the intended contract from the complete bundle, callers, host +conventions, and representative prompts. Invoke `$elicit` only when a +material intent decision remains unresolved. The review scope and available +contract are explicit. + +#### 2. Assess the bundle + +Read [Skill Sections](references/SECTIONS.md), run +[scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled +script, execute each safely isolated script, and acceptance-test the +representative invocations. Assess the governing methodology, supporting +concepts, predictability, composition, structure, language, resources, and +observable postconditions while preserving the bundle and user work unchanged. + +#### 3. Return the findings + +Return concise, prioritised findings. For each, name the governing concept, +cite the evidence and behavioural consequence, and recommend the smallest +effective improvement. Affirm the skill plainly when no material finding +remains. ### Improve -1. Complete `Review`, then use **characterization testing** to fix the existing - invocation and behaviour that should survive the change. -2. Invoke `$elicit` for material changes to intent, behaviour, invocation, - composition, or scope. Apply already-authorised mechanical corrections, then - use the `Create` branch's naming, structure, and language guidance to write - the confirmed change while preserving the characterised contract. -3. Follow `Validate Create or Improve`. +#### 1. Characterize the contract + +Complete `Review`, then use **characterization testing** to fix the existing +invocation and behaviour that should survive the change. + +#### 2. Write the confirmed improvement + +Invoke `$elicit` for material changes to intent, behaviour, invocation, +composition, or scope. Apply already-authorised mechanical corrections, then +use the `Create` branch's naming, structure, and language guidance to write +the confirmed change while preserving the characterised contract. + +#### 3. Validate the improvement + +Follow `Validate Create or Improve`. ### Validate Create or Improve -1. Apply **lossless compression** until every remaining word changes behaviour, - preserves a condition, or improves navigation. Each meaning has one - authoritative location. -2. Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute each - safely isolated bundled script until the mechanical contract passes. Report - any script that the common isolation boundary leaves unexecuted. -3. Use **acceptance testing** to replay every confirmed invocation through its - branches, resource pointers, and postconditions. Repeat writing, compression, - and validation until every scenario passes. -4. Forward-test complex or high-risk skills with a fresh agent given only the - finished bundle and a realistic request. Resolve material evidence through - the same loop; let simple skills and thin routers finish without this extra - test. -5. Report changed files, mechanical results, acceptance scenarios, forward-test - evidence when used, and any remaining uncertainty. +#### 1. Compress the bundle + +Apply **lossless compression** until every remaining word changes behaviour, +preserves a condition, or improves navigation. Each meaning has one +authoritative location. + +#### 2. Run mechanical validation + +Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute each +safely isolated bundled script until the mechanical contract passes. Report +any script that the common isolation boundary leaves unexecuted. + +#### 3. Run acceptance testing + +Use **acceptance testing** to replay every confirmed invocation through its +branches, resource pointers, and postconditions. Repeat writing, compression, +and validation until every scenario passes. + +#### 4. Forward-test when warranted + +Forward-test complex or high-risk skills with a fresh agent given only the +finished bundle and a realistic request. Resolve material evidence through +the same loop; let simple skills and thin routers finish without this extra +test. + +#### 5. Report the result + +Report changed files, mechanical results, acceptance scenarios, forward-test +evidence when used, and any remaining uncertainty. diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md index 0467136..e40c0a0 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -1,9 +1,8 @@ # Skill Sections Structure serves behaviour. Every `SKILL.md` has frontmatter, a human-readable -H1, and a strong introduction; every other heading is optional. Use the fewest -clear headings that make the confirmed workflow easy to execute. A small router -may finish after its introduction. +H1, a strong introduction, and one `## Process` section. Use the fewest other +clear headings that make the confirmed instructions easy to execute. ## Frontmatter @@ -46,28 +45,31 @@ For a router, directly invoke the called skills and state only coordination unique to their combined outcome. The router leaves their methodologies and instructions authoritative. -## Common Headings +## Process -These headings are available when their inclusion criterion is met. Rename, -combine, nest, or omit them when another structure communicates the behaviour -more directly. +Every skill uses `## Process` for its instructions. Use direct prose or +descriptive H3 headings when order does not matter. When order matters, use +numbered H3 headings with the instructions in paragraphs beneath them. For +branched processes, use unnumbered H3 branch headings and numbered H4 step +headings within each branch. End each ordered step in an observable +postcondition through **design by contract**. -### Prerequisites +## Optional Headings -Use when external conditions must already be true before execution can begin. -State the condition and the safe route when it is absent. Put setup work the -agent can perform in `Steps`. +These H2 headings are available when their inclusion criterion is met. Rename, +combine, or omit them when another structure communicates the behaviour more +directly. -### Steps +### Prerequisites -Use for executable work whose sequence matters. Number dependent actions, -introduce branches or stages only for distinct flows, and end each step in an -observable postcondition through **design by contract**. +Use when external conditions must already be true before execution can begin. +State the condition and the safe route when it is absent. This heading may +precede `## Process`. Put setup work the agent can perform in `Process`. ### Rules -Use for an invariant that constrains multiple steps or the finished result. -Keep a condition used by only one step beside that step. +Use for an invariant that constrains multiple instructions or the finished +result. Keep a condition used by only one step beside that step. ### Handoff @@ -83,5 +85,6 @@ confirmed use case: - `assets/` holds files used in generated output. - `scripts/` holds deterministic, repeated, or fragile operations. -Place each resource pointer beside the step or branch that loads or uses it. +Place each resource pointer beside the instruction or branch that loads or uses +it. Execute every script and keep each meaning in one authoritative location. diff --git a/skills/write-skill/scripts/validate-skill.js b/skills/write-skill/scripts/validate-skill.js index 7ac6f0a..f04478f 100644 --- a/skills/write-skill/scripts/validate-skill.js +++ b/skills/write-skill/scripts/validate-skill.js @@ -183,6 +183,14 @@ function validateBody(body) { if (!introduction) { addError('Follow the H1 with a concise introductory paragraph.'); } + + const processHeadings = lines.filter( + (line) => line.trim() === '## Process', + ); + + if (processHeadings.length !== 1) { + addError('Add exactly one ## Process heading to the skill body.'); + } } function collectFiles(directory, prefix) { From 306bea24059b148b5092edd7ec3b2ee24b9857a7 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 17:28:09 +0100 Subject: [PATCH 31/52] feat(write-skill): add research-led authoring workflow --- CONTEXT.md | 6 +- ...n-skills-with-established-methodologies.md | 3 +- ...-ground-skill-methodologies-in-research.md | 35 +++ .../20260715-agent-skill-authoring-methods.md | 148 +++++++++++++ skills/write-skill/SKILL.md | 202 +++++++----------- skills/write-skill/references/CRAFT.md | 76 +++++++ skills/write-skill/references/SECTIONS.md | 91 +++----- skills/write-skill/references/TESTING.md | 46 ++++ 8 files changed, 427 insertions(+), 180 deletions(-) create mode 100644 docs/adr/0002-ground-skill-methodologies-in-research.md create mode 100644 docs/research/20260715-agent-skill-authoring-methods.md create mode 100644 skills/write-skill/references/CRAFT.md create mode 100644 skills/write-skill/references/TESTING.md diff --git a/CONTEXT.md b/CONTEXT.md index 7ed7a12..7183e2b 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -115,7 +115,7 @@ A recognised term from an established method, principle, theory, or technique, s _Avoid_: Coined term, theme, slogan **Governing methodology**: -The single established methodology that determines a skill's process. Research validates the choice, while the plan and skill use only its canonical name without source attribution. +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**: @@ -143,7 +143,7 @@ A condition that must be true before a skill can begin. Its failure stops the sk _Avoid_: Setup step, pre-flight check **Step**: -A numbered subheading used when actions within a process or branch must occur in order. Its paragraphs describe the action and end in an observable postcondition. +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**: @@ -159,7 +159,7 @@ A transfer or route that becomes available after the skill's process is complete _Avoid_: Next step, final step **Reference**: -Focused supporting documentation linked once beside the condition that requires it and loaded only when that branch is reached. +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**: diff --git a/docs/adr/0001-govern-skills-with-established-methodologies.md b/docs/adr/0001-govern-skills-with-established-methodologies.md index f2d5645..31cd313 100644 --- a/docs/adr/0001-govern-skills-with-established-methodologies.md +++ b/docs/adr/0001-govern-skills-with-established-methodologies.md @@ -1,5 +1,6 @@ --- -status: accepted +status: superseded +superseded-by: './0002-ground-skill-methodologies-in-research.md' --- # Govern skills with established methodologies diff --git a/docs/adr/0002-ground-skill-methodologies-in-research.md b/docs/adr/0002-ground-skill-methodologies-in-research.md new file mode 100644 index 0000000..2ca27e4 --- /dev/null +++ b/docs/adr/0002-ground-skill-methodologies-in-research.md @@ -0,0 +1,35 @@ +--- +status: accepted +supersedes: './0001-govern-skills-with-established-methodologies.md' +--- + +# Ground skill methodologies in research + +## Decision + +Research credible governing methodologies for every Propulsion skill and let the +user choose among the supported options. Use the selected methodology to govern +the skill when one fits; allow the skill to proceed without one when research +reaches saturation without a suitable candidate. Add supporting concepts only +when evidence shows that they govern distinct concerns. + +## Context + +Requiring a methodology gave skills a compact conceptual anchor, but it also +made the presence of a methodology more important than its fit. A weak or +ceremonial choice can obscure the intended behaviour while appearing rigorous. +The alternatives were to preserve the mandatory rule, abandon methodological +grounding, or make research and user choice mandatory while making adoption +evidence-dependent. + +## Ramifications + +Skill authoring delegates methodology and supporting-concept investigations to +the research workflow, then compares its credible alternatives. A selected +methodology appears by canonical name in the runtime skill, while a justified +absence remains visible in the authoring record. Supporting concepts have no +required count. Mechanical validation does not attempt to determine +methodological legitimacy; semantic review and forward testing establish +whether the finished instructions produce the intended behaviour. Reconsider +this decision if methodology-free skills show greater behavioural variance than +evidence-backed alternatives. diff --git a/docs/research/20260715-agent-skill-authoring-methods.md b/docs/research/20260715-agent-skill-authoring-methods.md new file mode 100644 index 0000000..960b5d0 --- /dev/null +++ b/docs/research/20260715-agent-skill-authoring-methods.md @@ -0,0 +1,148 @@ +--- +title: 'Agent skill authoring methods' +createdAt: 2026-07-15 +updatedAt: 2026-07-15 +status: current +--- + +# Agent skill authoring methods + +## Research question and scope + +**Question:** Which governing methodology, supporting concepts, and bundle +structure best produce predictable, context-aware agent skills with compressed +behavioural language and progressive disclosure? + +**Intended use:** Redesign Propulsion's `write-skill` workflow and its authored +skill contract. + +**Scope:** Skill purpose discovery, methodology selection, information +hierarchy, language, structure, and behavioural validation. Sources were +assessed on 2026-07-15. Product-specific invocation metadata and claims about a +universal causal mechanism for leading words are excluded. + +## Conclusion + +**Minimalist instruction** is the strongest governor for `write-skill`. It +organises instructions around action, prior knowledge, error recovery, and the +smallest useful instructional surface rather than treating brevity as an end in +itself. **Use-case modelling**, **Design it twice**, **Separation of concerns**, +**DRY**, progressive disclosure, contracts, and evaluation-driven iteration +support distinct authoring concerns. Research should seek and compare credible +methods without forcing a methodology or supporting-concept count when the +evidence does not justify one. + +## Findings + +### Minimalist instruction governs the authoring workflow + +John Carroll's account of minimalist instruction describes designs that use +learner initiative and prior knowledge and treat error recognition, diagnosis, +and recovery as resources rather than attempting to control every action. That +directly supports compact skills which recruit an agent's existing knowledge +while retaining explicit behavioural bounds and recovery paths. [Carroll, +“Creating Minimalist Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) + +### Use cases recover behaviour before prose is written + +Jacobson and Cockburn define a use case around an actor's goal and the complete +set of successful, challenged, and failure scenarios. They recommend beginning +with a sketch and adding detail when circumstances require it. This supplies the +contract-discovery method without governing the later language and information +hierarchy. [Use-Case Foundation](https://alistaircockburn.com/Use%20Case%20Foundation.pdf) + +### Credible alternatives expose methodological trade-offs + +Ousterhout includes **Design it twice** among the principal practices in _A +Philosophy of Software Design_. Applied here, the concept requires real +methodology alternatives rather than accepting the first plausible match. The +specific rule to continue until multiple credible candidates emerge or research +reaches saturation is an adaptation to this workflow. [Stanford CS 190 lecture +notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) + +### Each section should isolate a coherent concern + +Dijkstra describes separation of concerns as isolating aspects so each is small +enough to reason about yet substantial enough to deserve focused attention. +Applied to a skill, one step or subsection should carry one coherent behavioural +idea and observable outcome without fragmenting supporting sentences into +ceremonial headings. [Dijkstra, EWD +803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) + +### Progressive disclosure is an execution hierarchy + +The Agent Skills specification permits optional `scripts/`, `references/`, and +`assets/` beside the required `SKILL.md`. Anthropic describes skills as using +progressive disclosure so metadata, instructions, and resources enter context +at different times, and recommends keeping core workflow in `SKILL.md` while +moving detailed or variant-specific knowledge into linked files. The inference +for Propulsion is that branch need and decision depth—not reluctance or a fixed +size threshold—should govern extraction. [Agent Skills +specification](https://agentskills.io/specification), [Anthropic skill +architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), +[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Compression requires semantic and empirical checks + +The Pragmatic Programmer defines DRY as keeping each piece of knowledge in one +authoritative representation. This supports removing duplicated meanings while +allowing deliberate reuse of a compact canonical term. Anthropic's authoring +guidance recommends evaluation before and after skill changes, including tests +for triggering and instruction compliance. Together they support sentence-level +no-op review followed by context-isolated forward testing. [The Pragmatic +Programmer, DRY chapter](https://media.pragprog.com/titles/tpp20/dry.pdf), +[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Leading words remain an evidence-tested heuristic + +Kojima et al. show that a short canonical phrase can substantially change model +behaviour in a bounded reasoning setting. It is an inference—not a demonstrated +universal law—that established methodology names reliably recruit equivalent +pretraining across agent tasks. Propulsion should therefore use canonical terms +to avoid restated explanations, then forward-test whether the finished wording +changes behaviour. [Kojima et al., “Large Language Models are Zero-Shot +Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) + +## Conflicts + +The [Matt Pocock +exemplar](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills) +treats predictability as the root virtue and allows skills made entirely from +reference, while Propulsion requires a common H1, introduction, and `## Process` +spine. [Obra's writing-skills +workflow](https://github.com/obra/superpowers/tree/main/skills/writing-skills) +makes baseline-first testing central and carries more process inline; +Anthropic's guidance favours concise core instructions, conditional references, +and evaluation-driven iteration. These are design differences rather than +factual conflicts. Propulsion adopts the fixed outer spine, conditional runtime +depth, and final forward testing confirmed by the user. + +## Limitations + +No primary evidence establishes an optimal leading-word vocabulary, bolding +frequency, body length, or reference granularity across Propulsion's target +models. Those choices require representative forward tests. Ousterhout's public +lecture notes establish **Design it twice** as a published practice but do not +reproduce the book chapter's full argument. + +## Method + +The investigation compared the current Propulsion bundle and vocabulary, Matt +Pocock's local `writing-great-skills` bundle, the public Propulsion, Matt Pocock, +and Obra exemplars, and current Agent Skills guidance. Secondary programming-book +roundups were treated only as discovery aids. Material claims were traced to +original authors, official specifications, first-party documentation, or +published research; competing structures were tested against the confirmed use +cases and context constraints on 2026-07-15. + +## Primary sources + +- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. +- [Use-Case Foundation](https://alistaircockburn.com/Use%20Case%20Foundation.pdf) — Ivar Jacobson and Alistair Cockburn, version 1.1, accessed 2026-07-15; goals, scenarios, extensions, and progressive detail. +- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. +- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. +- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. +- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. +- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. +- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. +- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022, accessed 2026-07-15; behavioural effect of a compact canonical phrase. diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index fec700c..b603890 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: write-skill -description: Creates, reviews, and improves predictable agent skills through approved use cases and established methodologies. Use when authoring or assessing a skill's behaviour, structure, or wording. +description: Creates, reviews, and rewrites predictable agent skills through confirmed behavioural contracts, evidence-backed concepts, and forward testing. Use when authoring or assessing a skill. metadata: invocation: user disable-model-invocation: true @@ -8,127 +8,89 @@ disable-model-invocation: true # Write Skill -**Use-case modelling** turns confirmed needs into skills with predictable -processes and context-sensitive outcomes. +**Minimalist instruction** turns confirmed behaviours into the smallest skill +bundle that reliably teaches them. ## Process -### 1. Select the branch +### 1. Establish the behavioural contract Inspect the request, complete target bundle, discoverable callers, and host -conventions. Select the `Create`, `Review`, or `Improve` branch from the -user's authorised outcome. Before executing a bundled script, establish a -disposable filesystem, inert fixtures, blocked external mutation, and no -production credentials; when that boundary is unavailable, leave the script -unexecuted and record the limitation. The branch, evidence, change boundary, -and script-execution boundary are explicit. - -Follow the selected branch. - -### Create - -#### 1. Confirm the contract - -Invoke `$elicit` to confirm concrete invocations, goals, inputs, outputs, -prerequisites, flows, branches, failures, composition, permissions, -postconditions, and resource needs. During the interview, invoke `$research` -when selecting the methodology or another material question warrants durable -evidence. Recommend one governing methodology and supporting concepts only -for distinct concerns; `$elicit`'s final confirmation approves the complete -contract and authorises writing. - -#### 2. Design the bundle - -Choose a short verb-led name through **ubiquitous language** and an invocation -policy whose context cost matches expected use. Read -[Skill Sections](references/SECTIONS.md), then use **Unix philosophy** and -**YAGNI** to choose the smallest independently useful bundle. The name, -invocation, structure, and resources serve the confirmed use cases. - -#### 3. Write the bundle - -Write the bundle with canonical **leading words** where they govern -behaviour. Apply **progressive disclosure** to conditional knowledge, -**degrees of freedom** to instruction precision, **DRY** to authority, and -**ironic process theory** to steer language toward the intended action. The -complete bundle expresses the confirmed contract through canonical terms; -source provenance remains in the research evidence. - -#### 4. Validate the bundle - -Follow `Validate Create or Improve`. - -### Review - -#### 1. Recover the contract - -Recover the intended contract from the complete bundle, callers, host -conventions, and representative prompts. Invoke `$elicit` only when a -material intent decision remains unresolved. The review scope and available -contract are explicit. - -#### 2. Assess the bundle - -Read [Skill Sections](references/SECTIONS.md), run -[scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled -script, execute each safely isolated script, and acceptance-test the -representative invocations. Assess the governing methodology, supporting -concepts, predictability, composition, structure, language, resources, and -observable postconditions while preserving the bundle and user work unchanged. - -#### 3. Return the findings - -Return concise, prioritised findings. For each, name the governing concept, -cite the evidence and behavioural consequence, and recommend the smallest -effective improvement. Affirm the skill plainly when no material finding -remains. - -### Improve - -#### 1. Characterize the contract - -Complete `Review`, then use **characterization testing** to fix the existing -invocation and behaviour that should survive the change. - -#### 2. Write the confirmed improvement - -Invoke `$elicit` for material changes to intent, behaviour, invocation, -composition, or scope. Apply already-authorised mechanical corrections, then -use the `Create` branch's naming, structure, and language guidance to write -the confirmed change while preserving the characterised contract. - -#### 3. Validate the improvement - -Follow `Validate Create or Improve`. - -### Validate Create or Improve - -#### 1. Compress the bundle - -Apply **lossless compression** until every remaining word changes behaviour, -preserves a condition, or improves navigation. Each meaning has one -authoritative location. - -#### 2. Run mechanical validation - -Run [scripts/validate-skill.js](scripts/validate-skill.js) and execute each -safely isolated bundled script until the mechanical contract passes. Report -any script that the common isolation boundary leaves unexecuted. - -#### 3. Run acceptance testing - -Use **acceptance testing** to replay every confirmed invocation through its -branches, resource pointers, and postconditions. Repeat writing, compression, -and validation until every scenario passes. - -#### 4. Forward-test when warranted - -Forward-test complex or high-risk skills with a fresh agent given only the -finished bundle and a realistic request. Resolve material evidence through -the same loop; let simple skills and thin routers finish without this extra -test. - -#### 5. Report the result - -Report changed files, mechanical results, acceptance scenarios, forward-test -evidence when used, and any remaining uncertainty. +conventions. Invoke `$elicit` and use **use-case modelling** to confirm the +skill's purpose, intended agent behaviour, representative invocations, inputs, +outputs, prerequisites, branches, failures, composition, permissions, +postconditions, and resource needs. Existing and new skills reach the same +explicit behavioural contract. + +### 2. Compare governing methodologies + +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. Never manufacture a weak alternative; +when only one survives, also offer no governing methodology. The user's +selection or evidence-backed absence is explicit. + +### 3. Select supporting concepts + +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; require no minimum or maximum count. Every retained concept earns a +distinct role. + +### 4. Confirm the design + +Present one complete synthesis of the behavioural contract, selected concepts, +structure, resources, scenarios, and observable success conditions. For an +existing skill, include concise evidence-backed findings against that contract. +Obtain explicit confirmation before following the remaining process. + +### 5. Write the bundle + +Create or rewrite through one path. 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. + +### 6. Separate the concerns + +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 is focused without becoming fragmentary. + +### 7. Compress the language + +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, state the +positive target behaviour, and keep each meaning in one authoritative location. +The bundle contains no behavioural no-op or duplicated meaning. + +### 8. Validate the mechanics + +Run [scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled +script, and execute each within a disposable filesystem using inert fixtures, +blocked external mutation, and no production credentials. When that boundary is +unavailable, leave the script unexecuted and report the limitation. The +mechanical contract passes without unsafe execution. + +### 9. Forward-test the behaviour + +Give a fresh agent only the finished bundle and a realistic invocation, then +compare its observable process and result with every confirmed scenario. Test +additional branches and reference-loading conditions in proportion to their +variety and risk. 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. + +### 10. Report the result + +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. diff --git a/skills/write-skill/references/CRAFT.md b/skills/write-skill/references/CRAFT.md new file mode 100644 index 0000000..0fc2a51 --- /dev/null +++ b/skills/write-skill/references/CRAFT.md @@ -0,0 +1,76 @@ +# 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 normal, alternate, and failure scenarios; +- 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 without hiding trade-offs. When +only one survives, compare it with proceeding without a governing methodology. + +## 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. Retain none when the governor and +plain language already determine the behaviour; retain as many 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 it +to a reference when only some branches need it or its detail would obscure the +common path. Write the pointer as a loading condition, not a generic invitation +to read more. Pull must-have material back inline only when a sharper pointer +still produces missed behaviour in forward tests. + +## 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 + +Describe the action the agent should perform. Reserve prohibitions for essential +safety boundaries that cannot be expressed positively, and pair each with the +safe action that satisfies it. The instruction leaves the intended behaviour, +not the failure, most salient. diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md index e40c0a0..bc357d8 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -1,8 +1,7 @@ # Skill Sections -Structure serves behaviour. Every `SKILL.md` has frontmatter, a human-readable -H1, a strong introduction, and one `## Process` section. Use the fewest other -clear headings that make the confirmed instructions easy to execute. +Use this reference when invocation metadata, optional sections, or bundled +resource placement needs more detail than the fixed skill spine. ## Frontmatter @@ -10,14 +9,13 @@ Include the skill's discovery and invocation contract: - `name` matches its directory, uses lowercase letters, digits, and single hyphens, and reads naturally when invoked. -- `description` is one action-oriented line that states both capability and - natural trigger conditions. Put all triggering guidance here because the body - loads only after invocation. +- `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. Use user invocation by default. Use model invocation when composition or broad -reuse justifies the permanent description context. +reuse earns the permanent description context. | Invocation | `disable-model-invocation` | `policy.allow_implicit_invocation` | | ---------- | -------------------------- | ---------------------------------- | @@ -26,65 +24,46 @@ reuse justifies the permanent description context. Add `agents/openai.yaml` with a human-readable `interface.display_name`, a 25–64-character `interface.short_description`, and the matching policy. -`interface.default_prompt` remains optional. - -## H1 - -Start the body with one human-readable H1 that makes the skill immediately -recognisable. It may expand an abbreviated directory name when that improves -clarity. ## Introduction -For a workflow skill, lead with the canonical governing methodology in bold and -state how it governs the capability in one strong sentence or short paragraph. -Explain only the context-specific adaptation and keep source attribution in the -research evidence rather than the skill. - -For a router, directly invoke the called skills and state only coordination -unique to their combined outcome. The router leaves their methodologies and -instructions authoritative. - -## Process - -Every skill uses `## Process` for its instructions. Use direct prose or -descriptive H3 headings when order does not matter. When order matters, use -numbered H3 headings with the instructions in paragraphs beneath them. For -branched processes, use unnumbered H3 branch headings and numbered H4 step -headings within each branch. End each ordered step in an observable -postcondition through **design by contract**. - -## Optional Headings - -These H2 headings are available when their inclusion criterion is met. Rename, -combine, or omit them when another structure communicates the behaviour more -directly. +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. -### Prerequisites +## Process details -Use when external conditions must already be true before execution can begin. -State the condition and the safe route when it is absent. This heading may -precede `## Process`. Put setup work the agent can perform in `Process`. +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. -### Rules +## Optional sections -Use for an invariant that constrains multiple instructions or the finished -result. Keep a condition used by only one step beside that step. +Add an H2 only when its content cannot communicate more clearly beside the +process instruction it governs: -### Handoff +- `## 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. -Use when completion creates a meaningful transfer to the user or another skill. -State the result, evidence, and unresolved uncertainty that cross the boundary. +Rename or combine optional sections when that improves the confirmed behaviour. +Never add them to complete a template. -## Bundled Resources +## Bundled resources -Use **progressive disclosure** and **YAGNI** to add only resources required by a -confirmed use case: +Use **progressive disclosure** as an information hierarchy: -- `references/` holds conditional knowledge loaded into context. -- `assets/` holds files used in generated output. -- `scripts/` holds deterministic, repeated, or fragile operations. +- 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/`. -Place each resource pointer beside the instruction or branch that loads or uses -it. -Execute every script and keep each meaning in one authoritative location. +Add a resource whenever its 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. diff --git a/skills/write-skill/references/TESTING.md b/skills/write-skill/references/TESTING.md new file mode 100644 index 0000000..8df2c13 --- /dev/null +++ b/skills/write-skill/references/TESTING.md @@ -0,0 +1,46 @@ +# Forward Testing + +Use this reference when scenario selection, context isolation, or observable +pass evidence needs more detail than a single representative invocation. + +## Preserve the evaluation boundary + +Give the fresh agent the finished bundle and a realistic user request. Do not +provide the intended answer, design rationale, suspected failure, or prior test +output. Use an inert workspace or read-only artifacts unless the scenario needs +safe local writes. A test demonstrates transferable steering only when hidden +author context cannot supply the result. + +## Select scenarios + +Run at least one common-path invocation for every created or rewritten skill. +Add the smallest scenarios that expose each distinct risk: + +- alternate and failure branches; +- optional reference-loading conditions; +- composition with another skill; +- permission or prerequisite boundaries; +- fragile scripts or deterministic output contracts; and +- wording whose effect depends on a leading word. + +Prefer one scenario that distinguishes several competing behaviours when its +failure remains diagnosable. + +## 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. A plausible final answer does not pass when the skill invoked the +wrong process, loaded irrelevant context, skipped a required branch, or relied +on leaked information. + +## 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 when remaining variance cannot be +reduced without changing the confirmed contract. Report unresolved variance +plainly. From d4ad5be53e03fceaddf7800eff95dbc0d2dade92 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 17:59:41 +0100 Subject: [PATCH 32/52] feat(write-skill): prioritize main success scenarios --- CONTEXT.md | 10 +- ...ill-design-on-the-main-success-scenario.md | 31 ++++ ...0260715-agent-skill-authoring-methods-2.md | 169 ++++++++++++++++++ .../20260715-agent-skill-authoring-methods.md | 3 +- skills/write-skill/SKILL.md | 32 ++-- skills/write-skill/references/CRAFT.md | 12 +- skills/write-skill/references/SECTIONS.md | 10 +- skills/write-skill/references/TESTING.md | 18 +- 8 files changed, 249 insertions(+), 36 deletions(-) create mode 100644 docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md create mode 100644 docs/research/20260715-agent-skill-authoring-methods-2.md diff --git a/CONTEXT.md b/CONTEXT.md index 7183e2b..87ef44f 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -29,9 +29,17 @@ Requirements elicitation adapted to establish discoverable facts, resolve a depe _Avoid_: Interrogation, clarification **Theoretical saturation**: -The point at which further elicitation reveals no new material branches, allowing the complete shared understanding to be presented for confirmation. +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, review, 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**: diff --git a/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md b/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md new file mode 100644 index 0000000..d30611c --- /dev/null +++ b/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md @@ -0,0 +1,31 @@ +--- +status: accepted +--- + +# Centre skill design on the main success scenario + +## Decision + +Design, review, and forward-test each skill around one main success scenario. +Apply YAGNI to speculative branches and retain an exception only when +representative evidence, the primary behaviour, or a necessary safety or +permission boundary requires it. Use progressive disclosure when a rare +retained exception needs depth that would obscure the common path. + +## Context + +Exhaustively exploring possible branches during elicitation produced bloated +skills and diluted the behaviour they were meant to teach. Arbitrary question or +scenario limits could stop useful discovery without distinguishing consequential +behaviour from imagination. The [research +snapshot](../research/20260715-agent-skill-authoring-methods-2.md) supports a +main-scenario backbone with an evidence-and-risk threshold for exceptions. + +## Ramifications + +Authoring interviews stop when the dominant behaviour and its material +exceptions are confirmed rather than when every imaginable path has been +discussed. Reviews prioritise impact on that dominant behaviour, and forward +tests cover the main scenario plus retained exceptions. Agents handle +unmodelled variation contextually, so reconsider this decision if recurring +failures show that the admission threshold omits necessary behaviour. diff --git a/docs/research/20260715-agent-skill-authoring-methods-2.md b/docs/research/20260715-agent-skill-authoring-methods-2.md new file mode 100644 index 0000000..76c412a --- /dev/null +++ b/docs/research/20260715-agent-skill-authoring-methods-2.md @@ -0,0 +1,169 @@ +--- +title: 'Agent skill authoring methods' +createdAt: 2026-07-15 +updatedAt: 2026-07-15 +status: current +supersedes: './20260715-agent-skill-authoring-methods.md' +--- + +# Agent skill authoring methods + +## Research question and scope + +**Question:** Which governing methodology, supporting concepts, and scenario +boundary best produce predictable agent skills without diluting their primary +behaviour through speculative exceptions? + +**Intended use:** Refine Propulsion's `write-skill` workflow and its authored +skill contract. + +**Scope:** Skill purpose discovery, methodology selection, scenario admission, +information hierarchy, language, structure, review, and behavioural validation. +Sources were assessed on 2026-07-15. Product-specific invocation metadata and +claims about a universal causal mechanism for leading words are excluded. + +## Conclusion + +The evidence-informed design conclusion is to retain **minimalist instruction** +as the governor for `write-skill`, use the **main success scenario** as its +behavioural backbone, and apply **YAGNI** to presumptive exceptions. Propulsion +adapts these sources into a three-part admission rule: retain an exception only +when representative evidence, success of the primary behaviour, or a necessary +safety or permission boundary requires it. **Progressive disclosure** keeps rare +retained exceptions available without competing with the common path. **Design +it twice**, **separation of concerns**, and **DRY** continue to govern +methodology choice, structure, and semantic compression. + +## Findings + +### Minimalist instruction governs the authoring workflow + +John Carroll's minimalist instruction leverages learner initiative and prior +knowledge rather than controlling every action through warnings and ordered +steps. It also treats error recognition, diagnosis, and recovery as resources. +That supports a small behavioural surface which recruits an agent's existing +knowledge while retaining necessary bounds. [Carroll, “Creating Minimalist +Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) + +### The main success scenario provides the behavioural backbone + +Jacobson and Cockburn define the basic flow as the normal path to value, also +called the main scenario or happy path. Their use-case guidance permits starting +with a sketch, adding detail as needed, and delivering key flows before less +used or less critical ones. The adaptation for skill authoring is to make that +main scenario the dominant contract rather than treating every conceivable +alternate flow as equally instruction-worthy. [Use-Case +Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) + +### YAGNI filters presumptive exceptions + +Martin Fowler describes YAGNI as the Extreme Programming practice of withholding +presumptive capability until it is needed because speculative support adds +complexity before its requirements are understood. Applied to skills, a +hypothetical branch is presumptive instructional capability: it should not enter +the contract merely because it can be imagined. This is an adaptation, not a +claim that YAGNI itself defines skill design. [Fowler, +“Yagni”](https://martinfowler.com/bliki/Yagni.html) + +### Materiality preserves necessary exceptions + +YAGNI does not justify omitting behaviour already required by the present +contract. A candidate exception remains material when a representative +invocation evidences it, the main behaviour cannot succeed without it, or a +necessary safety or permission boundary requires explicit handling. This +three-part admission rule is an inference combining present need under YAGNI +with the use-case distinction between a basic flow and less critical flows; its +safety and permission condition is a normative Propulsion boundary rather than +a sourced YAGNI rule. [Fowler, +“Yagni”](https://martinfowler.com/bliki/Yagni.html), [Use-Case +Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) + +### Progressive disclosure protects the common path + +The Agent Skills specification permits optional `scripts/`, `references/`, and +`assets/` beside `SKILL.md`. Anthropic describes staged loading and recommends +keeping the core workflow in `SKILL.md` while moving detailed or variant-specific +knowledge into linked resources. A rare exception that passes the materiality +test can therefore remain available without inflating the main instructions. +[Agent Skills specification](https://agentskills.io/specification), [Anthropic +skill architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), +[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Credible alternatives expose methodological trade-offs + +Ousterhout includes **Design it twice** among the principal practices in _A +Philosophy of Software Design_. Propulsion infers from that practice a +requirement to compare credible methodology alternatives rather than accept the +first plausible match. [Stanford CS 190 lecture +notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) + +### Structure and compression retain distinct authorities + +Dijkstra's separation of concerns supports giving each skill section one +coherent behavioural idea. The Pragmatic Programmer's DRY principle supports +one authoritative expression of each meaning. Together they keep the dominant +thread legible while preventing rare retained exceptions or repeated guidance +from competing with it. [Dijkstra, EWD +803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html), +[The Pragmatic Programmer, DRY +chapter](https://media.pragprog.com/titles/tpp20/dry.pdf) + +### Forward testing follows the same scenario boundary + +Anthropic recommends evaluation before and after skill changes, including tests +for triggering and instruction compliance. The scenario-admission inference is +to forward-test the main success scenario first and add a scenario only for a +retained material exception. This tests the contract rather than generating a +new inventory of hypothetical branches during evaluation. [Anthropic authoring +guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Leading words remain an evidence-tested heuristic + +Kojima et al. show that a short canonical phrase can substantially change model +behaviour in a bounded reasoning setting. It remains an inference, not a +universal law, that methodology names reliably recruit equivalent pretraining +across agent tasks; representative forward tests must validate the finished +wording. [Kojima et al., “Large Language Models are Zero-Shot +Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) + +## Conflicts + +Jacobson and Cockburn define a complete use case as including successful, +challenged, and failure paths. Propulsion deliberately applies only its main +success scenario as the authoring backbone, then admits exceptions through a +materiality test; it should not describe this narrower adaptation as exhaustive +use-case modelling. Fowler also limits YAGNI to presumptive capability and does +not use it to reject present requirements or enabling work. The safety, +permission, and primary-behaviour conditions preserve those present needs. + +## Limitations + +No primary evidence validates the three-part material-exception threshold +specifically for agent skills. It is an evidence-informed design inference that +requires forward testing. No primary evidence establishes an optimal leading +word, bolding frequency, body length, or reference granularity across +Propulsion's target models. + +## Method + +The investigation refreshed the prior 2026-07-15 authoring report after observed +elicitation and review behaviour showed that exhaustive scenario discovery +diluted the skill's primary thread. It compared first-party use-case definitions, +Fowler's published account of YAGNI, the current Propulsion bundle, Agent Skills +guidance, and the previously selected methods. Material claims were traced to +original authors, official specifications, first-party documentation, or +published research; adaptations to agent instruction were identified as +inferences. + +## Primary sources + +- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. +- [Use-Case Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) — Ivar Jacobson and Alistair Cockburn, accessed 2026-07-15; basic flow, alternate flows, and incremental detail. +- [Yagni](https://martinfowler.com/bliki/Yagni.html) — Martin Fowler, 2015, accessed 2026-07-15; presumptive capability and evolutionary design. +- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. +- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. +- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. +- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. +- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. +- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. +- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022; behavioural effect of a compact canonical phrase. diff --git a/docs/research/20260715-agent-skill-authoring-methods.md b/docs/research/20260715-agent-skill-authoring-methods.md index 960b5d0..bd3d655 100644 --- a/docs/research/20260715-agent-skill-authoring-methods.md +++ b/docs/research/20260715-agent-skill-authoring-methods.md @@ -2,7 +2,8 @@ title: 'Agent skill authoring methods' createdAt: 2026-07-15 updatedAt: 2026-07-15 -status: current +status: superseded +supersededBy: './20260715-agent-skill-authoring-methods-2.md' --- # Agent skill authoring methods diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index b603890..533ee1d 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -16,11 +16,13 @@ bundle that reliably teaches them. ### 1. Establish the behavioural contract Inspect the request, complete target bundle, discoverable callers, and host -conventions. Invoke `$elicit` and use **use-case modelling** to confirm the -skill's purpose, intended agent behaviour, representative invocations, inputs, -outputs, prerequisites, branches, failures, composition, permissions, -postconditions, and resource needs. Existing and new skills reach the same -explicit behavioural contract. +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. ### 2. Compare governing methodologies @@ -42,9 +44,11 @@ distinct role. ### 4. Confirm the design Present one complete synthesis of the behavioural contract, selected concepts, -structure, resources, scenarios, and observable success conditions. For an -existing skill, include concise evidence-backed findings against that contract. -Obtain explicit confirmation before following the remaining process. +structure, resources, main success scenario, material exceptions, and observable +success conditions. For an existing skill, include concise evidence-backed +findings prioritised by impact on the dominant behaviour and limited by the same +exception threshold. Obtain explicit confirmation before following the +remaining process. ### 5. Write the bundle @@ -82,12 +86,12 @@ mechanical contract passes without unsafe execution. ### 9. Forward-test the behaviour -Give a fresh agent only the finished bundle and a realistic invocation, then -compare its observable process and result with every confirmed scenario. Test -additional branches and reference-loading conditions in proportion to their -variety and risk. 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. +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. ### 10. Report the result diff --git a/skills/write-skill/references/CRAFT.md b/skills/write-skill/references/CRAFT.md index 0fc2a51..2e510af 100644 --- a/skills/write-skill/references/CRAFT.md +++ b/skills/write-skill/references/CRAFT.md @@ -10,7 +10,7 @@ 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 normal, alternate, and failure scenarios; +- its fit across the main success scenario and retained material exceptions; - the local adaptations it would require; and - the evidence supporting its published meaning. @@ -47,11 +47,11 @@ content. ## Disclose depth -Keep knowledge inline when every invocation needs it to act correctly. Move it -to a reference when only some branches need it or its detail would obscure the -common path. Write the pointer as a loading condition, not a generic invitation -to read more. Pull must-have material back inline only when a sharper pointer -still produces missed behaviour in forward tests. +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 the pointer as a loading condition, not a generic invitation to read more. +Pull must-have material back inline only when a sharper pointer still produces +missed behaviour in forward tests. ## Remove no-ops diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md index bc357d8..688466c 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -62,8 +62,8 @@ Use **progressive disclosure** as an information hierarchy: - Put files consumed or copied into generated output in `assets/`. - Put deterministic, repeated, or fragile operations in `scripts/`. -Add a resource whenever its 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. +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. diff --git a/skills/write-skill/references/TESTING.md b/skills/write-skill/references/TESTING.md index 8df2c13..ce629d4 100644 --- a/skills/write-skill/references/TESTING.md +++ b/skills/write-skill/references/TESTING.md @@ -1,7 +1,7 @@ # Forward Testing Use this reference when scenario selection, context isolation, or observable -pass evidence needs more detail than a single representative invocation. +pass evidence needs more detail than the main success scenario. ## Preserve the evaluation boundary @@ -13,18 +13,18 @@ author context cannot supply the result. ## Select scenarios -Run at least one common-path invocation for every created or rewritten skill. -Add the smallest scenarios that expose each distinct risk: +Run the main success scenario for every created or rewritten skill. Add the +smallest scenario for a retained material exception when it distinguishes: -- alternate and failure branches; -- optional reference-loading conditions; -- composition with another skill; -- permission or prerequisite boundaries; -- fragile scripts or deterministic output contracts; and +- 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. +failure remains diagnosable. The scenario set contains only confirmed behaviour +or material risk rather than hypothetical combinations. ## Define evidence From 2e935281a8a76a4483817bc871d290be3947a96c Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 19:22:07 +0100 Subject: [PATCH 33/52] feat(write-skill): enforce confirmed authoring scope --- CONTEXT.md | 4 +- ...0260715-agent-skill-authoring-methods-2.md | 3 +- ...0260715-agent-skill-authoring-methods-3.md | 274 ++++++++++++++++++ skills/write-skill/SKILL.md | 42 +-- skills/write-skill/agents/openai.yaml | 2 +- skills/write-skill/references/CRAFT.md | 25 +- skills/write-skill/references/SECTIONS.md | 6 +- skills/write-skill/references/TESTING.md | 22 +- skills/write-skill/scripts/validate-skill.js | 42 ++- 9 files changed, 369 insertions(+), 51 deletions(-) create mode 100644 docs/research/20260715-agent-skill-authoring-methods-3.md diff --git a/CONTEXT.md b/CONTEXT.md index 87ef44f..3f01065 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -33,7 +33,7 @@ The point at which further elicitation within the agreed scope reveals no new ma _Avoid_: Question limit, exhaustive questioning **Main success scenario**: -The representative invocation path that delivers a skill's intended outcome and remains dominant during design, review, and forward testing. +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**: @@ -43,7 +43,7 @@ _Avoid_: Edge case, hypothetical branch ### Skill anatomy **Authoring workflow**: -A skill that guides an agent through creating, reviewing, or improving another skill with an explicit process. It makes execution predictable without prescribing the authored skill's outcome. +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**: diff --git a/docs/research/20260715-agent-skill-authoring-methods-2.md b/docs/research/20260715-agent-skill-authoring-methods-2.md index 76c412a..84fc1dc 100644 --- a/docs/research/20260715-agent-skill-authoring-methods-2.md +++ b/docs/research/20260715-agent-skill-authoring-methods-2.md @@ -2,8 +2,9 @@ title: 'Agent skill authoring methods' createdAt: 2026-07-15 updatedAt: 2026-07-15 -status: current +status: superseded supersedes: './20260715-agent-skill-authoring-methods.md' +supersededBy: './20260715-agent-skill-authoring-methods-3.md' --- # Agent skill authoring methods diff --git a/docs/research/20260715-agent-skill-authoring-methods-3.md b/docs/research/20260715-agent-skill-authoring-methods-3.md new file mode 100644 index 0000000..03f68b3 --- /dev/null +++ b/docs/research/20260715-agent-skill-authoring-methods-3.md @@ -0,0 +1,274 @@ +--- +title: 'Agent skill authoring methods' +createdAt: 2026-07-15 +updatedAt: 2026-07-15 +status: current +supersedes: './20260715-agent-skill-authoring-methods-2.md' +--- + +# Agent skill authoring methods + +## Research question and scope + +**Question:** Which governing methodology, supporting concepts, and scenario +boundary best produce predictable agent skills without diluting their primary +behaviour through speculative exceptions, and can ironic process theory support +a requirement for positive behavioural instructions during compression? + +**Intended use:** Refine Propulsion's `write-skill` workflow and the skills it +creates or updates. The workflow may assess an existing bundle as evidence for +an update, but standalone skill review is outside this report's intended scope. + +**Scope:** Skill purpose discovery, methodology selection, scenario admission, +information hierarchy, language, structure, update-oriented assessment, and +behavioural validation. Human thought-suppression research, original +language-model negation studies, and first-party model guidance were assessed on +2026-07-15. Product-specific invocation metadata, standalone review outputs, and +claims that human mental-control mechanisms explain transformer behaviour are +excluded. + +## Conclusion + +The evidence-informed design conclusion is to retain **minimalist instruction** +as the governor for `write-skill`, use the **main success scenario** as its +behavioural backbone, and apply **YAGNI** to presumptive exceptions. Propulsion +adapts these sources into a three-part admission rule: retain an exception only +when representative evidence, success of the primary behaviour, or a necessary +safety or permission boundary requires it. **Progressive disclosure** keeps rare +retained exceptions available without competing with the common path. **Design +it twice**, **separation of concerns**, and **DRY** continue to govern +methodology choice, structure, and semantic compression. + +During compression, express an executable target affirmatively when that wording +preserves the contract. Retain a negative prohibition when safety, permission, +or precision makes the prohibition material, and pair it with the intended +alternative when one exists. **Ironic process theory** is credible evidence +about human mental control and a useful analogy for this preference; it is not +evidence of a transformer mechanism and cannot by itself justify an agent-skill +rule. The rule is instead a bounded engineering adaptation supported by direct, +but non-universal, evidence that language models can mishandle negation, +first-party prompting guidance, and representative forward tests. + +`write-skill` creates a new skill or updates an existing one. Assessment of an +existing skill serves that update path rather than becoming a standalone review +deliverable. This is a normative Propulsion scope decision, not an empirical +finding from the cited literature. + +The confirmed behavioural contract remains the fixed scope and decision +authority for methodology and supporting-concept research. Sources determine how +the skill teaches that behaviour; source-discovered possibilities do not become +new product requirements. This is a normative workflow boundary reinforced by a +forward test in which method research otherwise expanded a concise summary skill +with unrequested empty states, ambiguity rules, reversals, and compliance scope. +The confirmed design remains closed during drafting for the same reason: wording +and structure may improve its expression, while new behaviour returns to design +confirmation before entering the bundle. + +## Findings + +### Minimalist instruction governs the authoring workflow + +John Carroll's minimalist instruction leverages learner initiative and prior +knowledge rather than controlling every action through warnings and ordered +steps. It also treats error recognition, diagnosis, and recovery as resources. +That supports a small behavioural surface which recruits an agent's existing +knowledge while retaining necessary bounds. [Carroll, “Creating Minimalist +Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) + +### The main success scenario provides the behavioural backbone + +Jacobson and Cockburn define the basic flow as the normal path to value, also +called the main scenario or happy path. Their use-case guidance permits starting +with a sketch, adding detail as needed, and delivering key flows before less +used or less critical ones. The adaptation for skill authoring is to make that +main scenario the dominant contract rather than treating every conceivable +alternate flow as equally instruction-worthy. [Use-Case +Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) + +### YAGNI filters presumptive exceptions + +Martin Fowler describes YAGNI as the Extreme Programming practice of withholding +presumptive capability until it is needed because speculative support adds +complexity before its requirements are understood. Applied to skills, a +hypothetical branch is presumptive instructional capability: it should not enter +the contract merely because it can be imagined. This is an adaptation, not a +claim that YAGNI itself defines skill design. [Fowler, +“Yagni”](https://martinfowler.com/bliki/Yagni.html) + +### Materiality preserves necessary exceptions + +YAGNI does not justify omitting behaviour already required by the present +contract. A candidate exception remains material when a representative +invocation evidences it, the main behaviour cannot succeed without it, or a +necessary safety or permission boundary requires explicit handling. This +three-part admission rule is an inference combining present need under YAGNI +with the use-case distinction between a basic flow and less critical flows; its +safety and permission condition is a normative Propulsion boundary rather than +a sourced YAGNI rule. [Fowler, +“Yagni”](https://martinfowler.com/bliki/Yagni.html), [Use-Case +Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) + +### Progressive disclosure protects the common path + +The Agent Skills specification permits optional `scripts/`, `references/`, and +`assets/` beside `SKILL.md`. Anthropic describes staged loading and recommends +keeping the core workflow in `SKILL.md` while moving detailed or +variant-specific knowledge into linked resources. A rare exception that passes +the materiality test can therefore remain available without inflating the main +instructions. [Agent Skills specification](https://agentskills.io/specification), +[Anthropic skill +architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), +[Anthropic authoring +guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Ironic process theory is human evidence, not a model mechanism + +Wegner's theory proposes two human mental-control processes: a capacity-demanding +operator seeks content consistent with the intended state, while a less +demanding monitor searches for signs of failure; under reduced capacity, the +monitor can increase sensitivity to the unwanted content. The original +white-bear experiments found incomplete suppression and a later rebound, while +a specific replacement thought reduced that rebound. A 31-study meta-analysis +found rebound effects regardless of cognitive load, but immediate enhancement +during suppression only under load. This makes ironic process theory a credible, +qualified concept about human thought suppression rather than a general claim +that every negative instruction backfires. [Wegner, “Ironic Processes of Mental +Control”](https://doi.org/10.1037/0033-295X.101.1.34), [Wegner et al., +“Paradoxical Effects of Thought +Suppression”](https://doi.org/10.1037/0022-3514.53.1.5), [Wang, Hagger, and +Chatzisarantis, “Ironic Effects of Thought Suppression: A +Meta-Analysis”](https://doi.org/10.1177/1745691619898795) + +Applying that human theory to a language model would require an unsupported +assumption that transformer inference contains the theory's operator, monitor, +and capacity dynamics. Propulsion therefore uses the theory only as an analogy +that makes the positive-target preference memorable; it does not cite the theory +as the cause of model failures. This boundary is an inference from the mismatch +between the theory's stated human mechanism and the architecture under +instruction. + +### Model evidence supports testing positive targets, not banning negation + +Jang, Ye, and Seo tested nine NLP tasks across pretrained, instruction-tuned, +few-shot, and fine-tuned language models and found materially worse performance +on negated prompts, including an inverse scaling pattern in the tested model +families. Truong et al. likewise found insensitivity to negation and failures of +negation semantics and reasoning across GPT-Neo, GPT-3, and InstructGPT. These +are direct model findings, independent of ironic process theory, but they test +bounded benchmark transformations rather than compressed agent-skill +instructions or current models. [Jang, Ye, and Seo, “Can Large Language Models +Truly Follow your +Instructions?”](https://openreview.net/forum?id=89qDzjrWHLs), [Truong et al., +“Language models are not +naysayers”](https://aclanthology.org/2023.starsem-1.10/) + +Anthropic's current prompting guidance tells authors to specify what Claude +should do instead of only what it should not do, while the same guidance still +uses negative constraints where they precisely define boundaries. That supports +affirmative targets as a model-specific engineering practice, not a universal +causal law. Propulsion adapts the combined evidence into a compression rule: +prefer the positive executable behaviour, preserve material prohibitions, and +forward-test the exact wording. [Anthropic prompting best +practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) + +### Credible alternatives expose methodological trade-offs + +Ousterhout includes **Design it twice** among the principal practices in _A +Philosophy of Software Design_. Propulsion infers from that practice a +requirement to compare credible methodology alternatives rather than accept the +first plausible match. [Stanford CS 190 lecture +notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) + +### Structure and compression retain distinct authorities + +Dijkstra's separation of concerns supports giving each skill section one +coherent behavioural idea. The Pragmatic Programmer's DRY principle supports +one authoritative expression of each meaning. Together they keep the dominant +thread legible while preventing rare retained exceptions or repeated guidance +from competing with it. [Dijkstra, EWD +803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html), +[The Pragmatic Programmer, DRY +chapter](https://media.pragprog.com/titles/tpp20/dry.pdf) + +### Forward testing follows the same scenario boundary + +Anthropic recommends evaluation before and after skill changes, including tests +for triggering and instruction compliance. The scenario-admission inference is +to forward-test the main success scenario first and add a scenario only for a +retained material exception. Positive and negative variants should be compared +when polarity could change the contract. This tests the finished wording rather +than treating either human psychology or a benchmark result as universally +predictive. [Anthropic authoring +guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) + +### Leading words remain an evidence-tested heuristic + +Kojima et al. show that a short canonical phrase can substantially change model +behaviour in a bounded reasoning setting. It remains an inference, not a +universal law, that methodology names reliably recruit equivalent pretraining +across agent tasks; representative forward tests must validate the finished +wording. [Kojima et al., “Large Language Models are Zero-Shot +Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) + +## Conflicts + +Jacobson and Cockburn define a complete use case as including successful, +challenged, and failure paths. Propulsion deliberately applies only its main +success scenario as the authoring backbone, then admits exceptions through a +materiality test; it should not describe this narrower adaptation as exhaustive +use-case modelling. Fowler also limits YAGNI to presumptive capability and does +not use it to reject present requirements or enabling work. The safety, +permission, and primary-behaviour conditions preserve those present needs. + +Ironic process theory predicts a human counterintentional effect especially +when mental capacity is reduced, but it supplies no transformer mechanism. The +model studies show negation failures without establishing Wegner's cause, while +Anthropic's own examples retain negative constraints when a prohibition is the +precise requirement. Positive phrasing is therefore a preference for an +explicit executable target, not a ban on `not`, `never`, or `avoid`. + +## Limitations + +No primary evidence validates the three-part material-exception threshold or a +positive-instruction requirement specifically for agent skills. The direct +model studies cover older model families and bounded negation benchmarks; they +do not establish the effect for current Propulsion hosts, long skill bundles, +tool-using agents, safety constraints, or semantically equivalent positive and +negative rewrites. First-party prompting guidance reports recommended practice +rather than a reproducible causal experiment. No primary evidence establishes +an optimal leading word, bolding frequency, body length, or reference +granularity across Propulsion's target models. + +## Method + +The investigation refreshed the prior 2026-07-15 snapshot after the proposed +compression rule was linked to ironic process theory and the intended +`write-skill` scope was narrowed to creation and updates. It citation-chained +from Wegner's original experiment to his theory and a later meta-analysis, +then sought original language-model negation studies and current first-party +prompting guidance. Falsification focused on whether the human mechanism had +been demonstrated in transformers, whether immediate human effects occurred +without cognitive load, and whether direct model evidence justified removing +material negative constraints. It did not. Material claims were traced to +original publications, original empirical syntheses, official specifications, +or first-party documentation; every transfer to skill authoring is labelled as +an adaptation or inference. + +## Primary sources + +- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. +- [Use-Case Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) — Ivar Jacobson and Alistair Cockburn, accessed 2026-07-15; basic flow, alternate flows, and incremental detail. +- [Yagni](https://martinfowler.com/bliki/Yagni.html) — Martin Fowler, 2015, accessed 2026-07-15; presumptive capability and evolutionary design. +- [Ironic Processes of Mental Control](https://doi.org/10.1037/0033-295X.101.1.34) — Daniel M. Wegner, _Psychological Review_, 1994, accessed 2026-07-15; original human mental-control theory. +- [Paradoxical Effects of Thought Suppression](https://doi.org/10.1037/0022-3514.53.1.5) — Daniel M. Wegner et al., _Journal of Personality and Social Psychology_, 1987, accessed 2026-07-15; original white-bear experiments. +- [Ironic Effects of Thought Suppression: A Meta-Analysis](https://doi.org/10.1177/1745691619898795) — Deming Wang, Martin S. Hagger, and Nikos L. D. Chatzisarantis, _Perspectives on Psychological Science_, 2020, accessed 2026-07-15; 31-study synthesis of load, immediate enhancement, and rebound. +- [Can Large Language Models Truly Follow your Instructions?](https://openreview.net/forum?id=89qDzjrWHLs) — Joel Jang, Seonghyeon Ye, and Minjoon Seo, NeurIPS 2022 ML Safety Workshop, accessed 2026-07-15; original negated-prompt experiments. +- [Language models are not naysayers](https://aclanthology.org/2023.starsem-1.10/) — Thinh Hung Truong et al., \*SEM 2023, accessed 2026-07-15; original language-model negation evaluation. +- [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) — Anthropic, accessed 2026-07-15; current first-party positive-instruction guidance and counterexamples retaining precise negative constraints. +- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. +- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. +- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. +- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. +- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. +- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. +- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022; behavioural effect of a compact canonical phrase. diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 533ee1d..2c1fe80 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: write-skill -description: Creates, reviews, and rewrites predictable agent skills through confirmed behavioural contracts, evidence-backed concepts, and forward testing. Use when authoring or assessing a 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. metadata: invocation: user disable-model-invocation: true @@ -26,34 +26,36 @@ material exceptions. ### 2. Compare governing methodologies +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. Never manufacture a weak alternative; -when only one survives, also offer no governing methodology. The user's -selection or evidence-backed absence is explicit. +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. ### 3. Select supporting concepts 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; require no minimum or maximum count. Every retained concept earns a +decide; let the evidence determine the count. Every retained concept earns a distinct role. ### 4. Confirm the design Present one complete synthesis of the behavioural contract, selected concepts, structure, resources, main success scenario, material exceptions, and observable -success conditions. For an existing skill, include concise evidence-backed -findings prioritised by impact on the dominant behaviour and limited by the same -exception threshold. Obtain explicit confirmation before following the -remaining process. +success conditions. Obtain explicit confirmation before following the remaining +process. ### 5. Write the bundle -Create or rewrite through one path. Give every `SKILL.md` frontmatter, one H1, a -concise introduction, and exactly one `## Process`; place a selected governing +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, @@ -66,23 +68,27 @@ 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 is focused without becoming fragmentary. +section remains focused and substantial. ### 7. Compress the language 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, state the -positive target behaviour, and keep each meaning in one authoritative location. -The bundle contains no behavioural no-op or duplicated meaning. +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. ### 8. Validate the mechanics Run [scripts/validate-skill.js](scripts/validate-skill.js), inspect every bundled script, and execute each within a disposable filesystem using inert fixtures, -blocked external mutation, and no production credentials. When that boundary is -unavailable, leave the script unexecuted and report the limitation. The -mechanical contract passes without unsafe execution. +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. ### 9. Forward-test the behaviour diff --git a/skills/write-skill/agents/openai.yaml b/skills/write-skill/agents/openai.yaml index b9abe40..2223e0f 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, review, and improve agent skills' + short_description: 'Create and update predictable agent skills' policy: allow_implicit_invocation: false diff --git a/skills/write-skill/references/CRAFT.md b/skills/write-skill/references/CRAFT.md index 2e510af..9aa73ae 100644 --- a/skills/write-skill/references/CRAFT.md +++ b/skills/write-skill/references/CRAFT.md @@ -15,16 +15,16 @@ familiarity. Use **design it twice** to compare credible candidates through: - 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 without hiding trade-offs. When -only one survives, compare it with proceeding without a governing methodology. +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. Retain none when the governor and -plain language already determine the behaviour; retain as many as distinct -concerns require. +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 @@ -49,9 +49,9 @@ content. 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 the pointer as a loading condition, not a generic invitation to read more. -Pull must-have material back inline only when a sharper pointer still produces -missed behaviour in forward tests. +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 @@ -70,7 +70,8 @@ authorities. ## State positive behaviour -Describe the action the agent should perform. Reserve prohibitions for essential -safety boundaries that cannot be expressed positively, and pair each with the -safe action that satisfies it. The instruction leaves the intended behaviour, -not the failure, most salient. +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 688466c..55003a8 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -41,8 +41,8 @@ behavioural idea; each ordered step ends in an observable postcondition. ## Optional sections -Add an H2 only when its content cannot communicate more clearly beside the -process instruction it governs: +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 @@ -51,7 +51,7 @@ process instruction it governs: uncertainty. Rename or combine optional sections when that improves the confirmed behaviour. -Never add them to complete a template. +Every optional section earns its place through clearer execution. ## Bundled resources diff --git a/skills/write-skill/references/TESTING.md b/skills/write-skill/references/TESTING.md index ce629d4..3e78691 100644 --- a/skills/write-skill/references/TESTING.md +++ b/skills/write-skill/references/TESTING.md @@ -5,11 +5,12 @@ 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. Do not -provide the intended answer, design rationale, suspected failure, or prior test -output. Use an inert workspace or read-only artifacts unless the scenario needs -safe local writes. A test demonstrates transferable steering only when hidden -author context cannot supply the result. +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 @@ -30,9 +31,9 @@ or material risk rather than hypothetical combinations. Translate the confirmed contract into observable pass conditions before reading the result. Inspect the agent's actions, resource reads, decisions, output, and -postconditions. A plausible final answer does not pass when the skill invoked the -wrong process, loaded irrelevant context, skipped a required branch, or relied -on leaked information. +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 @@ -41,6 +42,5 @@ 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 when remaining variance cannot be -reduced without changing the confirmed contract. Report unresolved variance -plainly. +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/validate-skill.js b/skills/write-skill/scripts/validate-skill.js index f04478f..0878316 100644 --- a/skills/write-skill/scripts/validate-skill.js +++ b/skills/write-skill/scripts/validate-skill.js @@ -161,8 +161,40 @@ function validateOpenaiYaml(skillPath, frontmatter) { 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); + } + } + + 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(); @@ -171,6 +203,12 @@ function validateBody(body) { return; } + const h1Headings = headings.filter((line) => /^#\s+\S/.test(line)); + + if (h1Headings.length !== 1) { + addError('Add exactly one H1 heading to the skill body.'); + } + const firstH2Index = lines.findIndex((line) => /^##\s+\S/.test(line.trim()), ); @@ -184,9 +222,7 @@ function validateBody(body) { addError('Follow the H1 with a concise introductory paragraph.'); } - const processHeadings = lines.filter( - (line) => line.trim() === '## Process', - ); + const processHeadings = headings.filter((line) => line === '## Process'); if (processHeadings.length !== 1) { addError('Add exactly one ## Process heading to the skill body.'); From 4f204e994ec1d5141daa3607dde6f2b3c6db258e Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 19:23:20 +0100 Subject: [PATCH 34/52] Skills --- SKILLS_PLAN.md | 666 ------------------------------------------------- bun.lock | 100 ++++---- package.json | 6 +- 3 files changed, 53 insertions(+), 719 deletions(-) delete mode 100644 SKILLS_PLAN.md diff --git a/SKILLS_PLAN.md b/SKILLS_PLAN.md deleted file mode 100644 index 75618c0..0000000 --- a/SKILLS_PLAN.md +++ /dev/null @@ -1,666 +0,0 @@ -# Propulsion Skills Plan - -This plan defines the fixed v1 Propulsion skill suite. It is the high-level -handoff for implementing each skill independently, not a copy of the finished -skill instructions. - -## Purpose - -Propulsion gives coding agents short, predictable workflows grounded in -well-known methods. Each skill stabilises the process while leaving -context-sensitive outcomes open. - -The v1 suite contains exactly these twelve skills: - -1. **write-skill** -2. **elicit** -3. **maintain-context** -4. **commit** -5. **tdd** -6. **code-review** -7. **elicit-with-context** -8. **pr** -9. **implement** -10. **debug** -11. **research** -12. **review-architecture** - -## Suite Principles - -### Methodology hierarchy - -Every skill has one **governing methodology** that determines its process. -Add a **supporting concept** only when it governs a distinct concern without -competing with that methodology. - -Research validates each choice during design. Plans and skills use canonical -methodology names without author, book, or source attribution. The research -skill is the exception at output level because its reports cite their claims. - -### Behavioural language - -Use familiar terms as leading words to recruit the agent's existing knowledge. -Apply lossless compression until every remaining word or sentence changes -behaviour, preserves a condition, or improves navigation. Keep language plain, -tight, and context-aware rather than explaining concepts the agent already -knows. - -### Predictable composition - -Every skill remains directly useful on its own. A **router skill** contains only -coordination unique to its combined outcome; called skills remain authoritative -and the router neither repeats nor overrides them. - -### Invocation - -User invocation is the default. Permit model invocation only when a skill is a -composed dependency or a broadly reusable workflow whose context cost is -justified. - -| User-invoked | Model-invoked | -| ------------------- | ---------------- | -| write-skill | elicit | -| elicit-with-context | maintain-context | -| pr | commit | -| implement | tdd | -| debug | code-review | -| review-architecture | research | - -Model-invoked skills remain directly invokable by the user. - -### Resources - -Keep common-path behaviour in SKILL.md. Add a reference, asset, or script only -when a confirmed use case requires it: - -- references hold conditional guidance; -- assets hold reusable output material; -- scripts hold deterministic, repeated, or fragile operations. - -## Skill Catalogue - -| Skill | Outcome | Composition | -| ------------------- | ---------------------------------------------------------- | ---------------------------------------------------- | -| write-skill | Create, review, and improve predictable skills | elicit; research when durable evidence is warranted | -| commit | Create coherent conventional commits from uncommitted work | None | -| pr | Publish a ready GitHub pull request | commit | -| elicit | Resolve requirements to confirmed shared understanding | None | -| maintain-context | Keep project language and decisions current | None | -| elicit-with-context | Elicit while maintaining durable context | elicit, maintain-context | -| implement | Deliver a verified implementation through reviewed slices | tdd, code-review | -| tdd | Build observable behaviour through red-green-refactor | None | -| code-review | Report validated requirements and code-health findings | None | -| debug | Reproduce, isolate, repair, and verify a code issue | tdd when applicable | -| research | Persist primary-source findings in a cited report | Background agent when available | -| review-architecture | Produce an interactive report of high-value redesigns | research when durable external evidence is warranted | - -## Standard Skill Brief - -Every implementation handoff below records: - -- proposed name; -- intended outcome; -- use cases; -- boundaries and exclusions; -- governing methodology; -- supporting concepts; -- invocation and composition; -- high-level workflow; -- implementation success criteria; -- open research or design questions. - -## Skill Briefs - -### write-skill - -**Proposed name:** write-skill - -**Intended outcome:** Guide the user through creating, reviewing, or improving a -skill whose process is predictable, whose outcome remains context-sensitive, -and whose language is behaviourally dense. - -**Use cases:** Create a new skill from a need; review an existing skill; improve -an existing skill without unintentionally changing its contract. - -**Boundaries and exclusions:** It authors skill bundles, not the domain work the -new skill will later perform. It does not select a governing methodology without -the user's approval or retain source attribution in the finished skill. It -executes bundled scripts only within a boundary that blocks external mutation -and production credentials. - -**Governing methodology:** Use-case modelling. - -**Supporting concepts:** Ubiquitous language, Unix philosophy, leading words, -progressive disclosure, degrees of freedom, ironic process theory, YAGNI, DRY, -design by contract, lossless compression, characterization testing, and -acceptance testing. - -**Invocation and composition:** User-invoked. Invoke **elicit** to resolve the -skill's concrete need and use cases. Invoke **research** when methodology -selection or another material question warrants a durable evidence record; -perform only bounded source verification for smaller factual checks. - -**High-level workflow:** - -1. Establish whether the user is creating, reviewing, or improving a skill. -2. Elicit goals, callers, inputs, preconditions, flows, branches, failure paths, - composition, permissions, outputs, and postconditions. -3. Research candidate governing methodologies and supporting concepts when - needed, recommend the strongest fit, and obtain the user's approval. -4. Choose the name, invocation policy, bundle shape, and necessary resources. -5. Write the bundle from the confirmed use cases and concepts. -6. Compress and semantically test every use case until the skill is concise, - complete, and predictable. - -**Implementation success criteria:** A finished skill handles every confirmed -use case, names one approved governing methodology, uses supporting concepts -only for distinct concerns, contains no repeated authority, and passes -mechanical and semantic validation. - -**Open questions:** None. - -### commit - -**Proposed name:** commit - -**Intended outcome:** Inspect uncommitted work and create one or more coherent -conventional commits without losing or conflating changes. - -**Use cases:** Commit one coherent working-tree change at the user's request; -separate mixed concerns into multiple commits; provide the authorised commit -operation used by **pr**. - -**Boundaries and exclusions:** It does not push, open a pull request, discard -changes, or force unrelated work into one commit. - -**Governing methodology:** Conventional Commits. - -**Supporting concepts:** Atomic commits and interactive staging. - -**Invocation and composition:** Model-invoked and directly user-invokable. It -acts only from an explicit user request or authorised caller, has no skill -dependencies, and is called by **pr**. - -**High-level workflow:** - -1. Inspect tracked, staged, unstaged, and untracked changes plus repository - instructions and recent commit conventions. -2. Group changes by coherent intent and identify anything that should remain - uncommitted. -3. Use file- or hunk-level staging to create each atomic change. -4. Write an accurate conventional commit message and verify the resulting - commit before continuing to another concern. - -**Implementation success criteria:** Every created commit is coherent, -conventional, and traceable to the inspected diff; excluded work remains -untouched; mixed changes are not hidden inside a misleading commit. - -**Open questions:** None. - -### pr - -**Proposed name:** pr - -**Intended outcome:** Publish the current GitHub branch as a concise, -ready-for-review pull request. - -**Use cases:** Commit eligible local work, push the branch, and create a pull -request; create a draft only when explicitly requested. - -**Boundaries and exclusions:** GitHub repositories only. Use the configured -default branch unless the user explicitly supplies another base. Stop clearly -when the branch, remote, authentication, or diff prerequisites are not met. - -**Governing methodology:** GitHub flow. - -**Supporting concepts:** Conventional Commits and BLUF. - -**Invocation and composition:** User-invoked. Invoke **commit** for uncommitted -work and leave its staging and atomicity guidance authoritative. - -**High-level workflow:** - -1. Resolve the GitHub remote, current branch, requested or default base branch, - authentication, and repository pull-request instructions. -2. Invoke **commit** when eligible uncommitted changes exist. -3. Inspect the complete branch diff and commit history from the base branch's - merge base. -4. Push the current branch and create a ready pull request, or a draft when - explicitly requested. -5. Use a conventional title and honour a required repository template; - otherwise write one short paragraph explaining what changed and why. - -**Implementation success criteria:** The remote branch exists, the pull request -targets the correct base, its title and body accurately describe the complete -diff, and the resulting URL is returned. - -**Open questions:** None. - -### elicit - -**Proposed name:** elicit - -**Intended outcome:** Turn unresolved requirements into confirmed shared -understanding by closing every material branch one decision at a time. - -**Use cases:** Resolve requirements, constraints, trade-offs, boundaries, -dependencies, terminology, and success conditions before downstream action. - -**Boundaries and exclusions:** It does not begin downstream implementation -before confirmation. It remains unconfirmed when the user pauses, cancels, or -redirects the interview. - -**Governing methodology:** Requirements elicitation. - -**Supporting concepts:** Decision trees, Socratic questioning, falsification, -and theoretical saturation. - -**Invocation and composition:** Model-invoked and directly user-invokable. It is -called by **write-skill** and **elicit-with-context**. - -**High-level workflow:** - -1. Inspect the environment until discoverable facts for the current branch are - known. -2. Build and order the material decision tree. -3. Ask exactly one highest-impact resolved-prerequisite question at a time, - recommending the strongest answer and meaningful alternatives. -4. Test each answer through scenarios, counterexamples, and edge cases. -5. Repeat until theoretical saturation, then present one concise synthesis for - explicit confirmation. - -**Implementation success criteria:** Material branches, constraints, and -success conditions are either confirmed or explicitly unresolved; downstream -work begins only after the user's final confirmation. - -**Open questions:** None. - -### maintain-context - -**Proposed name:** maintain-context - -**Intended outcome:** Keep the codebase's ubiquitous language and consequential -architecture decisions accurate as understanding changes. - -**Use cases:** Resolve project terminology; update the single root CONTEXT.md; -create, supersede, and link concise ADRs. - -**Boundaries and exclusions:** Record project-specific language rather than -general programming definitions. Create an ADR only when changing the decision -would be costly, the choice would surprise a future reader, and viable -alternatives created a genuine trade-off. - -**Governing methodology:** Ubiquitous language. - -**Supporting concepts:** Architecture Decision Records, single source of truth, -progressive disclosure, and inverted pyramid. - -**Invocation and composition:** Model-invoked and directly user-invokable. It is -called by **elicit-with-context**. - -**High-level workflow:** - -1. Compare conversation language with CONTEXT.md and relevant code evidence. -2. Challenge ambiguous or conflicting terms and persist each confirmed term - immediately. -3. Test accepted decisions against the ADR gates. -4. Write brief sequential ADRs only for qualifying decisions and preserve - superseded history in both directions. -5. Re-read changed artifacts for consistency and report unresolved - contradictions. - -**Implementation success criteria:** The root glossary reflects confirmed -language as it resolves; ADRs are brief, accepted, sequential, and historically -linked; inferred or unresolved claims are not persisted. - -**Open questions:** None. - -### elicit-with-context - -**Proposed name:** elicit-with-context - -**Intended outcome:** Elicit confirmed shared understanding while keeping -project language and decisions current. - -**Use cases:** Deliberate interviews whose confirmed terms and qualifying -decisions should become durable project context. - -**Boundaries and exclusions:** It is a router and repeats none of the called -skills' process, terminology rules, or persistence mechanics. - -**Governing methodology:** Inherited requirements elicitation. - -**Supporting concepts:** Inherited from **elicit** and **maintain-context**; -none are restated by the router. - -**Invocation and composition:** User-invoked. Invoke **elicit**, applying -**maintain-context** throughout. - -**High-level workflow:** Route the interview through **elicit** and -**maintain-context**. Treat **elicit**'s final confirmation as the acceptance -boundary for qualifying ADRs, then return the elicitation state, context -changes, and unresolved language or decisions. - -**Implementation success criteria:** The router contains only its composition -and shared acceptance boundary; called skills remain the sole authority for -their own behaviour. - -**Open questions:** None. - -### implement - -**Proposed name:** implement - -**Intended outcome:** Deliver a clear software request through the smallest -verified end-to-end slices and close the review-remediation loop. - -**Use cases:** Implement features, bug fixes, refactors, documentation, or -configuration after the desired outcome is sufficiently clear. - -**Boundaries and exclusions:** It does not duplicate TDD or code-review -instructions, add speculative scope, or commit and publish work without a -separate request. - -**Governing methodology:** Tracer bullets. - -**Supporting concepts:** Feedback loops and YAGNI. - -**Invocation and composition:** User-invoked. Invoke **tdd** for applicable -observable behaviour changes and **code-review** after implementation. - -**High-level workflow:** - -1. Confirm the requested outcome, authorised scope, repository rules, and - verification evidence. -2. Deliver the smallest end-to-end slice; use **tdd** when applicable and the - smallest direct verified change otherwise. -3. Repeat until the requested behaviour is complete. -4. Invoke **code-review**, remediate in-scope findings, and repeat review and - verification until clean. -5. Run the repository's prescribed final checks and report exact evidence. - -**Implementation success criteria:** Every requested behaviour is implemented, -relevant verification passes or has an exact blocker, and the latest review has -no unresolved in-scope finding. - -**Open questions:** None. - -### tdd - -**Proposed name:** tdd - -**Intended outcome:** Build observable behaviour one test at a time through -durable red-green-refactor cycles. - -**Use cases:** Features and bug fixes that an existing runnable test suite can -exercise through a stable public seam. - -**Boundaries and exclusions:** Do not create a test harness merely to make TDD -applicable. Documentation, configuration-only changes, and -behaviour-preserving refactors remain outside unless they also change observable -behaviour. - -**Governing methodology:** Test-driven development through red-green-refactor. - -**Supporting concepts:** Classicist TDD, Test Desiderata, and -Arrange-Act-Assert. - -**Invocation and composition:** Model-invoked and directly user-invokable. It is -called by **implement** and **debug**. - -**High-level workflow:** - -1. Establish a known baseline and select one smallest observable behaviour. -2. Test through a stable public seam, using real internal collaborators and - doubles mainly at uncontrollable boundaries. -3. Observe the expected red failure, implement only enough for green, then - refactor while green. -4. Repeat one behaviour at a time and finish with the complete relevant suite. - -**Implementation success criteria:** Every cycle demonstrates meaningful red -and green evidence; retained tests satisfy the Test Desiderata and remain -sensitive to behaviour rather than implementation structure. - -**Open questions:** None. - -### code-review - -**Proposed name:** code-review - -**Intended outcome:** Return prioritised, evidence-validated findings for a -scoped code change without modifying it. - -**Use cases:** Review uncommitted work, a branch, pull request, revision range, -or a caller-supplied implementation. - -**Boundaries and exclusions:** Read-only. Report only issues introduced by or -materially relevant to the scoped change; omit personal preferences, unsupported -speculation, and unrelated pre-existing debt. - -**Governing methodology:** Google code review centred on code health. - -**Supporting concepts:** Requirements traceability, code smells, Test -Desiderata, falsification, and risk-based prioritisation. - -**Invocation and composition:** Model-invoked and directly user-invokable. It is -called by **implement**. - -**High-level workflow:** - -1. Pin the exact diff and recover the best available requirements source. -2. Inspect repository instructions, changed files, relevant surrounding code, - tests, and verification. -3. Perform separate requirements and code-health passes so neither suppresses - the other. -4. Try to disprove every candidate finding with code evidence and targeted - non-mutating checks. -5. Report only actionable findings with priority, evidence, consequence, and - the smallest effective correction. - -**Implementation success criteria:** The report states its scope and -requirements source, every finding is evidenced and actionable, both review -axes are explicit, and a clean review says so plainly. - -**Open questions:** None. - -### debug - -**Proposed name:** debug - -**Intended outcome:** Own the full debugging workflow from reproducible failure -through verified repair. - -**Use cases:** Diagnose and fix incorrect behaviour, failing tests, runtime -errors, regressions, performance faults, or integration issues. Stop before -mutation only when the user explicitly requests diagnosis alone. - -**Boundaries and exclusions:** Do not guess and patch symptoms, change multiple -variables without an experiment, or expand beyond the demonstrated cause. - -**Governing methodology:** Scientific method. - -**Supporting concepts:** Minimal reproducible example, hypothesis testing, -binary search, delta debugging, root-cause analysis, feedback loops, and -regression testing. - -**Invocation and composition:** User-invoked. Invoke **tdd** for the regression -test and repair when applicable. - -**High-level workflow:** - -1. Reproduce the issue and record the expected and observed behaviour. -2. Gather evidence, state falsifiable hypotheses, and run the cheapest - discriminating experiment. -3. Narrow the failing input, change, component, or boundary until the root cause - is established. -4. Add a regression test and apply the smallest causal correction. -5. Verify the original reproduction, relevant regression coverage, and wider - checks. - -**Implementation success criteria:** The failure is reproducible, the root cause -is supported by experiments, the fix addresses that cause, and verification -proves both repair and regression protection. - -**Open questions:** None. - -### research - -**Proposed name:** research - -**Intended outcome:** Investigate a scoped question against high-trust primary -evidence and persist concise, cited findings in the repository. - -**Use cases:** Research a user-requested topic; gather documentation, API, -source-code, standard, publication, or first-party data evidence; provide -durable reading legwork to another skill. - -**Boundaries and exclusions:** Do not trigger for every factual lookup. Secondary -sources are discovery aids whose material claims must be traced to primary -sources. Whenever the skill is invoked, it produces a durable report. - -**Governing methodology:** Evidence synthesis. - -**Supporting concepts:** Source criticism, citation chaining, triangulation, -falsification, reproducibility, and provenance. - -**Invocation and composition:** Model-invoked and directly user-invokable. Spawn -a background agent when the host supports delegation; otherwise perform the -same workflow inline. Other skills invoke it only when the evidence warrants a -durable record. - -**High-level workflow:** - -1. Define the research question, scope, currency needs, and source hierarchy. -2. Give a background agent the question, repository context, primary-source - standard, and report contract while the caller continues independent work. -3. Discover, appraise, compare, and synthesize primary evidence; use secondary - writing only to locate original sources. -4. Write docs/research/YYYYMMDD-{research-title}.md from - assets/research-report-template.md with claim-level citations, method, - conflicts, limitations, and source list. -5. Return only the report path and concise concrete findings to the caller, - which validates the conclusions and citations without loading the raw search - trail. - -The template uses createdAt, updatedAt, and status frontmatter, plus relative -supersedes or supersededBy links only when applicable. Its body contains the -research question and scope, conclusion, cited findings, method, limitations, -conflicts, and primary-source list. - -**Implementation success criteria:** The report maps material claims to primary -sources, exposes uncertainty and conflicts, and is reproducible from its -recorded method. A substantive refresh creates a linked superseding snapshot; -a minor correction preserves createdAt and changes updatedAt without rewriting -history. - -**Open questions:** None. - -### review-architecture - -**Proposed name:** review-architecture - -**Intended outcome:** Analyse a codebase and produce a concise interactive HTML -report of the highest-value architecture redesigns. - -**Use cases:** Review a whole project or explicit scope; expose weak module -boundaries, leaked implementation, shallow interfaces, harmful coupling, and -missing seams; propose framework-aware improvements. - -**Boundaries and exclusions:** Read-only. It recommends a small set of -high-value changes rather than exhaustively cataloguing debt or forcing one -framework-specific implementation pattern. - -**Governing methodology:** Information hiding. - -**Supporting concepts:** Deep modules, design it twice, cohesion and coupling, -single responsibility principle, dependency inversion, seams, ports and -adapters, ATAM, architecture fitness functions, strangler fig pattern, -progressive disclosure, and information visualisation. - -**Invocation and composition:** User-invoked. Invoke **research** only when -external framework, language, or architecture evidence warrants a durable -report. - -**High-level workflow:** - -1. Inspect code, context, decisions, dependency direction, framework - conventions, runtime boundaries, and existing verification. -2. Map cohesive capabilities, public contracts, hidden implementations, - adapters, seams, coupling, and quality-attribute drivers. -3. Generate alternative boundaries through design it twice, then evaluate - benefits, risks, trade-offs, effort, and migration paths. -4. Keep only the highest-value recommendations and define architecture fitness - evidence for each. -5. Generate a single-file interactive report at - docs/architecture/YYYYMMDD-{scope}-architecture-review.html using - references/report-design.md for tone, hierarchy, accessibility, diagrams, - interaction patterns, and visual QA. - -Each recommendation explains the evidenced problem, affected modules and -contracts, target design, framework fit, quality improvements, costs and risks, -incremental migration, dependencies, and fitness checks. The initial view is -short and plain; diagrams, filters, and expandable evidence disclose complexity -only when requested. - -**Implementation success criteria:** A human can understand and compare the -prioritised recommendations without reading a wall of technical prose; every -recommendation is evidence-backed, framework-aware, trade-off explicit, -incrementally actionable, and visually verified. - -**Open questions:** None. - -## Composition Map - -| Caller | Called skill | Condition | -| ------------------- | ---------------- | --------------------------------------------------------------- | -| write-skill | elicit | Resolve the skill need and use cases | -| write-skill | research | Methodology or another material question needs durable evidence | -| elicit-with-context | elicit | Run the interview | -| elicit-with-context | maintain-context | Maintain language and decisions throughout | -| pr | commit | Eligible uncommitted work exists | -| implement | tdd | An applicable observable behaviour change has a runnable suite | -| implement | code-review | The implementation is ready for independent assessment | -| debug | tdd | The repair can be driven by a regression test | -| review-architecture | research | External evidence warrants a durable report | - -## Suggested Implementation Order - -1. **write-skill** -2. **elicit** -3. **maintain-context** -4. **commit** -5. **tdd** -6. **code-review** -7. **elicit-with-context** -8. **pr** -9. **implement** -10. **debug** -11. **research** -12. **review-architecture** - -The order establishes the authoring workflow first, then independently useful -dependencies, routers, and larger specialised workflows. - -## Suite Acceptance Criteria - -The v1 suite is complete when: - -- all twelve bundles exist under skills/ with the proposed canonical names; -- every skill has one governing methodology and only necessary supporting - concepts; -- descriptions state both capability and invocation conditions; -- invocation metadata matches the agreed user/model map in every supported - client; -- every skill is directly usable and every router contains only unique - coordination; -- callers reference dependencies without repeating or overriding them; -- common-path instructions stay in SKILL.md and every additional resource earns - its place through a confirmed use case; -- research owns assets/research-report-template.md and review-architecture owns - references/report-design.md; -- finished skill text names methodologies without author, book, or source - attribution; -- semantic dry runs exercise normal, branch, failure, and composition paths; -- mechanical validation and every bundle script pass; -- repository context, skill names, and composition agree; and -- bun run checks passes after each implemented skill. diff --git a/bun.lock b/bun.lock index 24e4053..050f596 100644 --- a/bun.lock +++ b/bun.lock @@ -5,106 +5,106 @@ "": { "name": "propulsion", "devDependencies": { - "oxfmt": "^0.44.0", - "oxlint": "^1.62.0", - "oxlint-tsgolint": "^0.20.0", + "oxfmt": "^0.59.0", + "oxlint": "^1.74.0", + "oxlint-tsgolint": "^0.24.0", }, }, }, "packages": { - "@oxfmt/binding-android-arm-eabi": ["@oxfmt/binding-android-arm-eabi@0.44.0", "", { "os": "android", "cpu": "arm" }, "sha512-5UvghMd9SA/yvKTWCAxMAPXS1d2i054UeOf4iFjZjfayTwCINcC3oaSXjtbZfCaEpxgJod7XiOjTtby5yEv/BQ=="], + "@oxfmt/binding-android-arm-eabi": ["@oxfmt/binding-android-arm-eabi@0.59.0", "", { "os": "android", "cpu": "arm" }, "sha512-bNTnfbuG7sAwb2PakMNaDukx5kXeW9duXOBeWtTOiLz3fXz3q2DlWguufPZ+c2IHEVrRXHD+M4aUgEWm841LDA=="], - "@oxfmt/binding-android-arm64": ["@oxfmt/binding-android-arm64@0.44.0", "", { "os": "android", "cpu": "arm64" }, "sha512-IVudM1BWfvrYO++Khtzr8q9n5Rxu7msUvoFMqzGJVdX7HfUXUDHwaH2zHZNB58svx2J56pmCUzophyaPFkcG/A=="], + "@oxfmt/binding-android-arm64": ["@oxfmt/binding-android-arm64@0.59.0", "", { "os": "android", "cpu": "arm64" }, "sha512-R/Sn7z52QtdAKNqQLLY0EK7hVMjXiz3XUlvoCFCm/60jgIzAnQtiqLKBCFaBkimCQL5rs2ezPMcicpjCsrl54Q=="], - "@oxfmt/binding-darwin-arm64": ["@oxfmt/binding-darwin-arm64@0.44.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-eWCLAIKAHfx88EqEP1Ga2yz7qVcqDU5lemn4xck+07bH182hDdprOHjbogyk0In1Djys3T0/pO2JepFnRJ41Mg=="], + "@oxfmt/binding-darwin-arm64": ["@oxfmt/binding-darwin-arm64@0.59.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-vm/ynUqE4HjC0ZIEjmXv1UJu1/GngccQ+T+TJudTMxUxm6r+GQTg1TO3E5jJfI71pBaXxSzs1+vWHIwuilGHhw=="], - "@oxfmt/binding-darwin-x64": ["@oxfmt/binding-darwin-x64@0.44.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-eHTBznHLM49++dwz07MblQ2cOXyIgeedmE3Wgy4ptUESj38/qYZyRi1MPwC9olQJWssMeY6WI3UZ7YmU5ggvyQ=="], + "@oxfmt/binding-darwin-x64": ["@oxfmt/binding-darwin-x64@0.59.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-uTtYDpLN/obfKVWGpgEc8BqYlLZBQTPz2uYEvLRy3HPZxjZ34wiFzukUBU2bf64JuCYZI//GTV1EOMmWlPjf/w=="], - "@oxfmt/binding-freebsd-x64": ["@oxfmt/binding-freebsd-x64@0.44.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-jLMmbj0u0Ft43QpkUVr/0v1ZfQCGWAvU+WznEHcN3wZC/q6ox7XeSJtk9P36CCpiDSUf3sGnzbIuG1KdEMEDJQ=="], + "@oxfmt/binding-freebsd-x64": ["@oxfmt/binding-freebsd-x64@0.59.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-e2UnxL/ifStSPy8ffBCDbdy595SYsGy+U1pur4G65TuMmWxAMBzYGG7atZo/3mp515p8rZdsflxVD/E1FAdPLQ=="], - "@oxfmt/binding-linux-arm-gnueabihf": ["@oxfmt/binding-linux-arm-gnueabihf@0.44.0", "", { "os": "linux", "cpu": "arm" }, "sha512-n+A/u/ByK1qV8FVGOwyaSpw5NPNl0qlZfgTBqHeGIqr8Qzq1tyWZ4lAaxPoe5mZqE3w88vn3+jZtMxriHPE7tg=="], + "@oxfmt/binding-linux-arm-gnueabihf": ["@oxfmt/binding-linux-arm-gnueabihf@0.59.0", "", { "os": "linux", "cpu": "arm" }, "sha512-LtdeZ1l0urxte3VNi3g8cocZwv1xGM1NKHSgF/fJEEVhyQmlgGh7WFWKFd/pNuO7djfvPNtNO1+MS+FEWkgVSA=="], - "@oxfmt/binding-linux-arm-musleabihf": ["@oxfmt/binding-linux-arm-musleabihf@0.44.0", "", { "os": "linux", "cpu": "arm" }, "sha512-5eax+FkxyCqAi3Rw0mrZFr7+KTt/XweFsbALR+B5ljWBLBl8nHe4ADrUnb1gLEfQCJLl+Ca5FIVD4xEt95AwIw=="], + "@oxfmt/binding-linux-arm-musleabihf": ["@oxfmt/binding-linux-arm-musleabihf@0.59.0", "", { "os": "linux", "cpu": "arm" }, "sha512-dBTciSsj9GTMl7p+h2gMSI0hoPn2ijfc/dUsbnWsP0RbwgPl2r0C/5zkMb3Pb+gGj17LH7f1o4qLo9aes/pAvA=="], - "@oxfmt/binding-linux-arm64-gnu": ["@oxfmt/binding-linux-arm64-gnu@0.44.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-58l8JaHxSGOmOMOG2CIrNsnkRJAj0YcHQCmvNACniOa/vd1iRHhlPajczegzS5jwMENlqgreyiTR9iNlke8qCw=="], + "@oxfmt/binding-linux-arm64-gnu": ["@oxfmt/binding-linux-arm64-gnu@0.59.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-tXVdJ/JINsNWdponPHN0OuKHtC+HdpyoS9sd6IDPNiiEYsRki8b7tefRZ1iMnRkdbyT4SEbguWsr6o+5awvbPQ=="], - "@oxfmt/binding-linux-arm64-musl": ["@oxfmt/binding-linux-arm64-musl@0.44.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-AlObQIXyVRZ96LbtVljtFq0JqH5B92NU+BQeDFrXWBUWlCKAM0wF5GLfIhCLT5kQ3Sl+U0YjRJ7Alqj5hGQaCg=="], + "@oxfmt/binding-linux-arm64-musl": ["@oxfmt/binding-linux-arm64-musl@0.59.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-RRTq38i2zT5fnw6XGHjvT6w2mh6x/G3m6AZcAZ56OTDTT/lsOeYnG3SVjwmH40z5kPqF+lf+o35e6m6PpKy9Dw=="], - "@oxfmt/binding-linux-ppc64-gnu": ["@oxfmt/binding-linux-ppc64-gnu@0.44.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-YcFE8/q/BbrCiIiM5piwbkA6GwJc5QqhMQp2yDrqQ2fuVkZ7CInb1aIijZ/k8EXc72qXMSwKpVlBv1w/MsGO/A=="], + "@oxfmt/binding-linux-ppc64-gnu": ["@oxfmt/binding-linux-ppc64-gnu@0.59.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-lD3k7glAJSaXW0D6xzu8VOZbYbosvy+0ktOVkfLEoQF5HJlMSxTQ2KNW0JO+08ccP/1ElOKktVEMI0fqRbVB4w=="], - "@oxfmt/binding-linux-riscv64-gnu": ["@oxfmt/binding-linux-riscv64-gnu@0.44.0", "", { "os": "linux", "cpu": "none" }, "sha512-eOdzs6RqkRzuqNHUX5C8ISN5xfGh4xDww8OEd9YAmc3OWN8oAe5bmlIqQ+rrHLpv58/0BuU48bxkhnIGjA/ATQ=="], + "@oxfmt/binding-linux-riscv64-gnu": ["@oxfmt/binding-linux-riscv64-gnu@0.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-WH5ZP1RbuHKBO/yfPRQKpNO/ijHcEDNbnmC4VPf/Bcd3+mbMAZpRiJWRa1PL5bREdIZZHo343mk3sqlc9x7Usw=="], - "@oxfmt/binding-linux-riscv64-musl": ["@oxfmt/binding-linux-riscv64-musl@0.44.0", "", { "os": "linux", "cpu": "none" }, "sha512-YBgNTxntD/QvlFUfgvh8bEdwOhXiquX8gaofZJAwYa/Xp1S1DQrFVZEeck7GFktr24DztsSp8N8WtWCBwxs0Hw=="], + "@oxfmt/binding-linux-riscv64-musl": ["@oxfmt/binding-linux-riscv64-musl@0.59.0", "", { "os": "linux", "cpu": "none" }, "sha512-743wOiaI9RZY4QVGkWkfGRavD5ZJUJ6gscFjVrVu1dP8AZh9jM+a6v3NhlR+OIzHdS6DhLM96w+gcVskskz7rw=="], - "@oxfmt/binding-linux-s390x-gnu": ["@oxfmt/binding-linux-s390x-gnu@0.44.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-GLIh1R6WHWshl/i4QQDNgj0WtT25aRO4HNUWEoitxiywyRdhTFmFEYT2rXlcl9U6/26vhmOqG5cRlMLG3ocaIA=="], + "@oxfmt/binding-linux-s390x-gnu": ["@oxfmt/binding-linux-s390x-gnu@0.59.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-xjRXQsRnrRZCcCkIEnbd2lmsQNobtwwkJxdy2bWXhZ1lIN0ouZwsBXRsoovW3yATuziAYwr9HMiQuR/Cc75NIw=="], - "@oxfmt/binding-linux-x64-gnu": ["@oxfmt/binding-linux-x64-gnu@0.44.0", "", { "os": "linux", "cpu": "x64" }, "sha512-gZOpgTlOsLcLfAF9qgpTr7FIIFSKnQN3hDf/0JvQ4CIwMY7h+eilNjxq/CorqvYcEOu+LRt1W4ZS7KccEHLOdA=="], + "@oxfmt/binding-linux-x64-gnu": ["@oxfmt/binding-linux-x64-gnu@0.59.0", "", { "os": "linux", "cpu": "x64" }, "sha512-4hNjqq/Rbr9B+StY9zMMAfm72+mtM4v80xYL5Qkb59Qd72g2vJMI0iFlPj3kf6miMsie/yJ7rt4urJT292HBgA=="], - "@oxfmt/binding-linux-x64-musl": ["@oxfmt/binding-linux-x64-musl@0.44.0", "", { "os": "linux", "cpu": "x64" }, "sha512-1CyS9JTB+pCUFYFI6pkQGGZaT/AY5gnhHVrQQLhFba6idP9AzVYm1xbdWfywoldTYvjxQJV6x4SuduCIfP3W+A=="], + "@oxfmt/binding-linux-x64-musl": ["@oxfmt/binding-linux-x64-musl@0.59.0", "", { "os": "linux", "cpu": "x64" }, "sha512-NH579iN8EVQYsWowUB8B5vFchcylJtwPVJ7NmUAqEQHNLfhPbDT3K56KrECNAkUN4QpF4qiMgN2vsfZwVvjm7g=="], - "@oxfmt/binding-openharmony-arm64": ["@oxfmt/binding-openharmony-arm64@0.44.0", "", { "os": "none", "cpu": "arm64" }, "sha512-bmEv70Ak6jLr1xotCbF5TxIKjsmQaiX+jFRtnGtfA03tJPf6VG3cKh96S21boAt3JZc+Vjx8PYcDuLj39vM2Pw=="], + "@oxfmt/binding-openharmony-arm64": ["@oxfmt/binding-openharmony-arm64@0.59.0", "", { "os": "none", "cpu": "arm64" }, "sha512-mzZy3Z5Aj1D75Aq9FVlmoRQH5ei8Ga4o/NZmlXkKyeZ5EmPrUXRR7c6BMBteV1ZuZ/356UYDuLRLjAMxTDTiBA=="], - "@oxfmt/binding-win32-arm64-msvc": ["@oxfmt/binding-win32-arm64-msvc@0.44.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-yWzB+oCpSnP/dmw85eFLAT5o35Ve5pkGS2uF/UCISpIwDqf1xa7OpmtomiqY/Vzg8VyvMbuf6vroF2khF/+1Vg=="], + "@oxfmt/binding-win32-arm64-msvc": ["@oxfmt/binding-win32-arm64-msvc@0.59.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-0CpDJ1gE3jN1Gk6xms1Ie6LPfPcOtY4FAtoOmVLHQoAf8DvO2wd0DW2dIX2f7YTp5dxrr0ND8JeUEjm3DP3k5g=="], - "@oxfmt/binding-win32-ia32-msvc": ["@oxfmt/binding-win32-ia32-msvc@0.44.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-TcWpo18xEIE3AmIG2kpr3kz5IEhQgnx0lazl2+8L+3eTopOAUevQcmlr4nhguImNWz0OMeOZrYZOhJNCf16nlQ=="], + "@oxfmt/binding-win32-ia32-msvc": ["@oxfmt/binding-win32-ia32-msvc@0.59.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-zwdKBu3pt87uW0bRcywZb0oGMS7C6n87qogwRYFUgmk44T90ZzYlPjtlFYXs/DnBFrgNCvlHwCuWKfVWLeE7kw=="], - "@oxfmt/binding-win32-x64-msvc": ["@oxfmt/binding-win32-x64-msvc@0.44.0", "", { "os": "win32", "cpu": "x64" }, "sha512-oj8aLkPJZppIM4CMQNsyir9ybM1Xw/CfGPTSsTnzpVGyljgfbdP0EVUlURiGM0BDrmw5psQ6ArmGCcUY/yABaQ=="], + "@oxfmt/binding-win32-x64-msvc": ["@oxfmt/binding-win32-x64-msvc@0.59.0", "", { "os": "win32", "cpu": "x64" }, "sha512-dUUbZkKgWrmAeI/puzv4bxN8lzcYaFnQVwFTFtwO2Gp8M7lZGSE2qJjC58g518+1bltJ8mizjYwD0BGHym0l/w=="], - "@oxlint-tsgolint/darwin-arm64": ["@oxlint-tsgolint/darwin-arm64@0.20.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-KKQcIHZHMxqpHUA1VXIbOG6chNCFkUWbQy6M+AFVtPKkA/3xAeJkJ3njoV66bfzwPHRcWQO+kcj5XqtbkjakoA=="], + "@oxlint-tsgolint/darwin-arm64": ["@oxlint-tsgolint/darwin-arm64@0.24.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-C2uMmwK5Bc4ri4ysZ6sA8Rcu+A5zBQTp6ml2u0CLLbRZp4kMFPV3yWk8B5DK9Aw7y9bbjogIm75tUwGLFzlsYQ=="], - "@oxlint-tsgolint/darwin-x64": ["@oxlint-tsgolint/darwin-x64@0.20.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-7HeVMuclGfG+NLZi2ybY0T4fMI7/XxO/208rJk+zEIloKkVnlh11Wd241JMGwgNFXn+MLJbOqOfojDb2Dt4L1g=="], + "@oxlint-tsgolint/darwin-x64": ["@oxlint-tsgolint/darwin-x64@0.24.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-Wgvt/1lRbDxmoNqWQKKcL+UIiqLmdJ+EWLpQa1qzoNVAfNB0PJpa82/8dH1twT/3rSs4zrP5TXPWl4juB71WuQ=="], - "@oxlint-tsgolint/linux-arm64": ["@oxlint-tsgolint/linux-arm64@0.20.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-zxhUwz+WSxE6oWlZLK2z2ps9yC6ebmgoYmjAl0Oa48+GqkZ56NVgo+wb8DURNv6xrggzHStQxqQxe3mK51HZag=="], + "@oxlint-tsgolint/linux-arm64": ["@oxlint-tsgolint/linux-arm64@0.24.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-PB1rxII7KV83+ASY4sSkXtqvpij6ME66+QCRL49uksi/ofs2Rf/UVboYr095n0Rkbl2wgvlsHGl6DHC361jQUQ=="], - "@oxlint-tsgolint/linux-x64": ["@oxlint-tsgolint/linux-x64@0.20.0", "", { "os": "linux", "cpu": "x64" }, "sha512-/1l6FnahC9im8PK+Ekkx/V3yetO/PzZnJegE2FXcv/iXEhbeVxP/ouiTYcUQu9shT1FWJCSNti1VJHH+21Y1dg=="], + "@oxlint-tsgolint/linux-x64": ["@oxlint-tsgolint/linux-x64@0.24.0", "", { "os": "linux", "cpu": "x64" }, "sha512-xcz3CxKmjTQLREtE/UShh+ruWmm9nAb7UM9zKcD65BStiuYgOakAKkPHl4YS5DztpVcDrE0+HqbOolTlRKYWmw=="], - "@oxlint-tsgolint/win32-arm64": ["@oxlint-tsgolint/win32-arm64@0.20.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-oPZ5Yz8sVdo7P/5q+i3IKeix31eFZ55JAPa1+RGPoe9PoaYVsdMvR6Jvib6YtrqoJnFPlg3fjEjlEPL8VBKYJA=="], + "@oxlint-tsgolint/win32-arm64": ["@oxlint-tsgolint/win32-arm64@0.24.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-A2i6ZGBec3i20S7RaxkgHc6r3HYtD5Mn7j/mb22NkTz14u0JuudvTu6JggAnbGMcv8+dBKQI//EasxSPJLD8pw=="], - "@oxlint-tsgolint/win32-x64": ["@oxlint-tsgolint/win32-x64@0.20.0", "", { "os": "win32", "cpu": "x64" }, "sha512-4stx8RHj3SP9vQyRF/yZbz5igtPvYMEUR8CUoha4BVNZihi39DpCR8qkU7lpjB5Ga1DRMo2pHaA4bdTOMaY4mw=="], + "@oxlint-tsgolint/win32-x64": ["@oxlint-tsgolint/win32-x64@0.24.0", "", { "os": "win32", "cpu": "x64" }, "sha512-0ZbGd9qRB6zs82moekaKdEvncRANq49EAwfNX62JpTS46feXUhKAuoyVDvZMj6Rywejylrmmu79Wo6faYCo4Ew=="], - "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.62.0", "", { "os": "android", "cpu": "arm" }, "sha512-pKsthNECyvJh8lPTICz6VcwVy2jOqdhhsp1rlxCkhgZR47aKvXPmaRWQDv+zlXpRae4qm1MaaTnutkaOk5aofg=="], + "@oxlint/binding-android-arm-eabi": ["@oxlint/binding-android-arm-eabi@1.74.0", "", { "os": "android", "cpu": "arm" }, "sha512-+gHd12muVI9ZLBaWLPkHt3Fj7jihFjgQ1MGtBaRL8vWrWrI0P7dLUty/cHrHS0oqPYIRgQUJsPu2CExQuMcwNw=="], - "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.62.0", "", { "os": "android", "cpu": "arm64" }, "sha512-b1AUNViByvgmR2xJDubvLIr+dSuu3uraG7bsAoKo+xrpspPvu6RIn6Fhr2JUhobfep3jwUTy18Huco6GkwdvGQ=="], + "@oxlint/binding-android-arm64": ["@oxlint/binding-android-arm64@1.74.0", "", { "os": "android", "cpu": "arm64" }, "sha512-xjKdoMB+H+RCOByv/7l7nfIGW9mlOisqYdcyC75UqYuQecLpReAeEYUf2CNeDEI3KtmUgxpRw/+c63y4AeF/Bw=="], - "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.62.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-iG+Tvf70UJ6otfwFYIHk36Sjq9cpPP5YLxkoggANNRtzgi3Tj3g8q6Ybqi6AtkU3+yg9QwF7bDCkCS6bbL4PCg=="], + "@oxlint/binding-darwin-arm64": ["@oxlint/binding-darwin-arm64@1.74.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-iUK7wvc6sejMKsC+Pt67mntoF5weFcyEunhZfLJceU6gL419mexz5wBkSx/EnkFBExMLNtOi9fnDSc5xfK0IzQ=="], - "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.62.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-oOWI6YPPr5AJUx+yIDlxmuUbQjS5gZX3OH3QisawYvsZgLiQVvZtR0rPBcJTxLWqt2ClrWg0DlSrlUiG5SQNHg=="], + "@oxlint/binding-darwin-x64": ["@oxlint/binding-darwin-x64@1.74.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-ggKc/tn5SJ1u2yG2izC6VKODfYKV8MQ2AicJlNzOjuyrC29udvOef6/JzK2r32xqCnBDLFouR1VCkjzEI0/N9Q=="], - "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.62.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-dLP33T7VLCmLVv4cvjkVX+rmkcwNk2UfxmsZPNur/7BQHoQR60zJ7XLiRvNUawlzn0u8ngCa3itjEG73MAMa/w=="], + "@oxlint/binding-freebsd-x64": ["@oxlint/binding-freebsd-x64@1.74.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-u++dH/43jy9hTLbneaWlS0gla/Bp1JdwJ2zgevCl8nDFUh6qRCGMxcL0f0lb7By3A9p/LfFr+7cG4HU1hG856g=="], - "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.62.0", "", { "os": "linux", "cpu": "arm" }, "sha512-fl//LWNks6qo9chNY60UDYyIwtp7a5cEx4Y/rHPjaarhuwqx6jtbzEpD5V5AqmdL4a6Y5D8zeXg5HF2Cr0QmSQ=="], + "@oxlint/binding-linux-arm-gnueabihf": ["@oxlint/binding-linux-arm-gnueabihf@1.74.0", "", { "os": "linux", "cpu": "arm" }, "sha512-Sj1zmtFDVTPeIbIz4ZfcXAbFHqCmKCXdCUlAJzvTF7I20NTH1RDpoF2PhkqNODutJzVhJYmm3oz0GwgY+tvE2g=="], - "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.62.0", "", { "os": "linux", "cpu": "arm" }, "sha512-i5vkAuxvueTODV3J2dL61/TXewDHhMFKvtD156cIsk7GsdfiAu7zW7kY0NJXhKeFHeiMZIh7eFNjkPYH6J47HQ=="], + "@oxlint/binding-linux-arm-musleabihf": ["@oxlint/binding-linux-arm-musleabihf@1.74.0", "", { "os": "linux", "cpu": "arm" }, "sha512-//PKyQb/tQXcHArx2f7z+oVI/eMS2Jpv+edNuAtOrgIhWdGcpHxogveAxzmF2rpH1AIHp4Hq04RF/rgJdiICnQ=="], - "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.62.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-QwN19LLuIGuOjEflSeJkZmOTfBdBMlTmW8xbMf8TZhjd//cxVNYQPq75q7oKZBJc6hRx3gY7sX0Egc8cEIFZYg=="], + "@oxlint/binding-linux-arm64-gnu": ["@oxlint/binding-linux-arm64-gnu@1.74.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-/k1Me+aX2tjuH10K62mLS0y8cLkJBHX6Ce0xPK+eWeel4bSdEGZ8dv4+hYMzg0GrSmjwy4yAYsDPeEeKBft/2w=="], - "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.62.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-8eCy3FCDuWUM5hWujAv6heMvfZPbcCOU3SdQUAkixZLu5bSzOkNfirJiLGoQFO943xceOKkiQRMQNzH++jM3WA=="], + "@oxlint/binding-linux-arm64-musl": ["@oxlint/binding-linux-arm64-musl@1.74.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-3tFSjBxc5D8/zvjEuLvOqcA8ZXKD0+6NuaVO/edeamNc49MoAsbfaC9s1UiwODwgF6slGaF8yJA2TPkukd77tg=="], - "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.62.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-NjQ7K7tpTPDe9J+yq8p/s/J0E7lRCkK2uDBDqvT4XIT6f4Z0tlnr59OBg/WcrmVHER1AbrcfyxhGTXgcG8ytWg=="], + "@oxlint/binding-linux-ppc64-gnu": ["@oxlint/binding-linux-ppc64-gnu@1.74.0", "", { "os": "linux", "cpu": "ppc64" }, "sha512-9QggtPkSPXOCTu8Szis7auOK/sC7KdQaN+/TujP7YVVhzCAOhgdRfgv8uEz0r2tk5xdgus5rLYUrCDoZNtiRUw=="], - "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.62.0", "", { "os": "linux", "cpu": "none" }, "sha512-oKZed9gmSwze29dEt3/Wnsv6l/Ygw/FUst+8Kfpv2SGeS/glEoTGZAMQw37SVyzFV76UTHJN2snGgxK2t2+8ow=="], + "@oxlint/binding-linux-riscv64-gnu": ["@oxlint/binding-linux-riscv64-gnu@1.74.0", "", { "os": "linux", "cpu": "none" }, "sha512-VM5VPUJ4DJIWiK+AZn8FScUqMr6OFrCAYybMYjEEi7W13ParI64MByiXTkKMqZpBmvQ9zxl9Ebq2VUOiZRJYUg=="], - "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.62.0", "", { "os": "linux", "cpu": "none" }, "sha512-gBjBxQ+9lGpAYq+ELqw0w8QXsBnkZclFc7GRX2r0LnEVn3ZTEqeIKpKcGjucmp76Q53bvJD0i4qBWBhcfhSfGA=="], + "@oxlint/binding-linux-riscv64-musl": ["@oxlint/binding-linux-riscv64-musl@1.74.0", "", { "os": "linux", "cpu": "none" }, "sha512-SaDY1gh9rOA592J54g+gu5hkOFFQBZsMmIYHs+NRHG+Uq0OxtuuCXMWQ3vu1830Eugv5uMXyjG+bv2Z9y4IXjw=="], - "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.62.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-Ew2Kxs9EQ9/mbAIJ2hvocMC0wsOu6YKzStI2eFBDt+Td5O8seVC/oxgRIHqCcl5sf5ratA1nozQBAuv7tphkHg=="], + "@oxlint/binding-linux-s390x-gnu": ["@oxlint/binding-linux-s390x-gnu@1.74.0", "", { "os": "linux", "cpu": "s390x" }, "sha512-ZATQeHZCyr6MbDveg0obD5sxLHFOghtOdC5jwVwYlvFWqtFOxctgFEG6Ef/64hYvZrWyhyCckB10AelqLopeDA=="], - "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.62.0", "", { "os": "linux", "cpu": "x64" }, "sha512-5z25jcAA0gfKyVwz71A0VXgaPlocPoTAxhlv/hgoK6tlCrfoNuw7haWbDHvGMfjXhdic4EqVXGRv5XsTqFnbRQ=="], + "@oxlint/binding-linux-x64-gnu": ["@oxlint/binding-linux-x64-gnu@1.74.0", "", { "os": "linux", "cpu": "x64" }, "sha512-+aIvJyrdeD7LwCQ2WYLMUWNmnbeDRSPb40aBYtPjD9+PTqUwgJnk+HK5yLfSMeqXrMrDhE9uTmtt2y50tvjhHw=="], - "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.62.0", "", { "os": "linux", "cpu": "x64" }, "sha512-IWpHmMB6ZDllPvqWDkG6AmXrN7JF5e/c4g/0PuURsmlK+vHoYZPB70rr4u1bn3I4LsKCSpqqfveyx6UCOC8wdg=="], + "@oxlint/binding-linux-x64-musl": ["@oxlint/binding-linux-x64-musl@1.74.0", "", { "os": "linux", "cpu": "x64" }, "sha512-XyktaR8lhK2qWiCK0Tk8oYD+/cgn+oHA6ddRnxSSXUKkkojkV78CmShZUxQF+yrBFs0SuW+JBOPG6hecyc/iZg=="], - "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.62.0", "", { "os": "none", "cpu": "arm64" }, "sha512-fjlSxxrD5pA594vkyikCS9MnPRjQawW6/BLgyTYkO+73wwPlYjkcZ7LSd974l0Q2zkHQmu4DPvJFLYA7o8xrxQ=="], + "@oxlint/binding-openharmony-arm64": ["@oxlint/binding-openharmony-arm64@1.74.0", "", { "os": "none", "cpu": "arm64" }, "sha512-mzbjrPl4neaVUiJ1fUiEUxTGaSZBoiKtaoB6jmIpz9S+VOA2vDYmJpihQ82w6178V5jxziclTg8Cgj5yF6tTDg=="], - "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.62.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-EiFXr8loNS0Ul3Gu80+9nr1T8jRmnKocqmHHg16tj5ZqTgUXyb97l2rrspVHdDluyFn9JfR4PoJFdNzw4paHww=="], + "@oxlint/binding-win32-arm64-msvc": ["@oxlint/binding-win32-arm64-msvc@1.74.0", "", { "os": "win32", "cpu": "arm64" }, "sha512-vUAe9okpS2Oa5+lX67lqHMuNUvfkleRKwrUDJ/WJBsgmddvZ1mrsh2HVmuFDRzqFELhaJhFaCNOuR6a7L3rtIA=="], - "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.62.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-IgOFvL73li1bFgab+hThXYA0N2Xms2kV2MvZN95cebV+fmrZ9AVui1JSxfeeqRLo3CpPxKZlzhyq4G0cnaAvIw=="], + "@oxlint/binding-win32-ia32-msvc": ["@oxlint/binding-win32-ia32-msvc@1.74.0", "", { "os": "win32", "cpu": "ia32" }, "sha512-yyXXJyYYSXL4I8K8jAWjJs+J3fa9gH2JmEbo4f5adm+1tNC9itseicBNuwK7BDHvqQ5J534s+yDULu89vYL2ZQ=="], - "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.62.0", "", { "os": "win32", "cpu": "x64" }, "sha512-6hMpyDWQ2zGA1OXFKBrdYMUveUCO8UJhkO6JdwZPd78xIdHZNhjx+pib+4fC2Cljuhjyl0QwA2F3df/bs4Bp6A=="], + "@oxlint/binding-win32-x64-msvc": ["@oxlint/binding-win32-x64-msvc@1.74.0", "", { "os": "win32", "cpu": "x64" }, "sha512-VTC9IYTIMrVUk/i6Ms1ohzzDKZFkWn0KU2OBbPBzgmVZ2V30165T/zK4LztTr0Xgp9fZ1qQZ1rsZAu/rEmySlA=="], - "oxfmt": ["oxfmt@0.44.0", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.44.0", "@oxfmt/binding-android-arm64": "0.44.0", "@oxfmt/binding-darwin-arm64": "0.44.0", "@oxfmt/binding-darwin-x64": "0.44.0", "@oxfmt/binding-freebsd-x64": "0.44.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.44.0", "@oxfmt/binding-linux-arm-musleabihf": "0.44.0", "@oxfmt/binding-linux-arm64-gnu": "0.44.0", "@oxfmt/binding-linux-arm64-musl": "0.44.0", "@oxfmt/binding-linux-ppc64-gnu": "0.44.0", "@oxfmt/binding-linux-riscv64-gnu": "0.44.0", "@oxfmt/binding-linux-riscv64-musl": "0.44.0", "@oxfmt/binding-linux-s390x-gnu": "0.44.0", "@oxfmt/binding-linux-x64-gnu": "0.44.0", "@oxfmt/binding-linux-x64-musl": "0.44.0", "@oxfmt/binding-openharmony-arm64": "0.44.0", "@oxfmt/binding-win32-arm64-msvc": "0.44.0", "@oxfmt/binding-win32-ia32-msvc": "0.44.0", "@oxfmt/binding-win32-x64-msvc": "0.44.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-lnncqvHewyRvaqdrnntVIrZV2tEddz8lbvPsQzG/zlkfvgZkwy0HP1p/2u1aCDToeg1jb9zBpbJdfkV73Itw+w=="], + "oxfmt": ["oxfmt@0.59.0", "", { "dependencies": { "tinypool": "2.1.0" }, "optionalDependencies": { "@oxfmt/binding-android-arm-eabi": "0.59.0", "@oxfmt/binding-android-arm64": "0.59.0", "@oxfmt/binding-darwin-arm64": "0.59.0", "@oxfmt/binding-darwin-x64": "0.59.0", "@oxfmt/binding-freebsd-x64": "0.59.0", "@oxfmt/binding-linux-arm-gnueabihf": "0.59.0", "@oxfmt/binding-linux-arm-musleabihf": "0.59.0", "@oxfmt/binding-linux-arm64-gnu": "0.59.0", "@oxfmt/binding-linux-arm64-musl": "0.59.0", "@oxfmt/binding-linux-ppc64-gnu": "0.59.0", "@oxfmt/binding-linux-riscv64-gnu": "0.59.0", "@oxfmt/binding-linux-riscv64-musl": "0.59.0", "@oxfmt/binding-linux-s390x-gnu": "0.59.0", "@oxfmt/binding-linux-x64-gnu": "0.59.0", "@oxfmt/binding-linux-x64-musl": "0.59.0", "@oxfmt/binding-openharmony-arm64": "0.59.0", "@oxfmt/binding-win32-arm64-msvc": "0.59.0", "@oxfmt/binding-win32-ia32-msvc": "0.59.0", "@oxfmt/binding-win32-x64-msvc": "0.59.0" }, "peerDependencies": { "svelte": "^5.0.0", "vite-plus": "*" }, "optionalPeers": ["svelte", "vite-plus"], "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-Xqk6cPZS1yMvVa7OAuenaDZUsgMDutvvbZ9/L5gSvAfW64+WN4HVhgipLj5rVERbYQt8fLs9TopyZ1rU1XEG/w=="], - "oxlint": ["oxlint@1.62.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.62.0", "@oxlint/binding-android-arm64": "1.62.0", "@oxlint/binding-darwin-arm64": "1.62.0", "@oxlint/binding-darwin-x64": "1.62.0", "@oxlint/binding-freebsd-x64": "1.62.0", "@oxlint/binding-linux-arm-gnueabihf": "1.62.0", "@oxlint/binding-linux-arm-musleabihf": "1.62.0", "@oxlint/binding-linux-arm64-gnu": "1.62.0", "@oxlint/binding-linux-arm64-musl": "1.62.0", "@oxlint/binding-linux-ppc64-gnu": "1.62.0", "@oxlint/binding-linux-riscv64-gnu": "1.62.0", "@oxlint/binding-linux-riscv64-musl": "1.62.0", "@oxlint/binding-linux-s390x-gnu": "1.62.0", "@oxlint/binding-linux-x64-gnu": "1.62.0", "@oxlint/binding-linux-x64-musl": "1.62.0", "@oxlint/binding-openharmony-arm64": "1.62.0", "@oxlint/binding-win32-arm64-msvc": "1.62.0", "@oxlint/binding-win32-ia32-msvc": "1.62.0", "@oxlint/binding-win32-x64-msvc": "1.62.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.18.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-1uFkg6HakjsGIpW9wNdeW4/2LOHW9MEkoWjZUTUfQtIHyLIZPYt00w3Sg+H3lH+206FgBPHBbW5dVE5l2ExECQ=="], + "oxlint": ["oxlint@1.74.0", "", { "optionalDependencies": { "@oxlint/binding-android-arm-eabi": "1.74.0", "@oxlint/binding-android-arm64": "1.74.0", "@oxlint/binding-darwin-arm64": "1.74.0", "@oxlint/binding-darwin-x64": "1.74.0", "@oxlint/binding-freebsd-x64": "1.74.0", "@oxlint/binding-linux-arm-gnueabihf": "1.74.0", "@oxlint/binding-linux-arm-musleabihf": "1.74.0", "@oxlint/binding-linux-arm64-gnu": "1.74.0", "@oxlint/binding-linux-arm64-musl": "1.74.0", "@oxlint/binding-linux-ppc64-gnu": "1.74.0", "@oxlint/binding-linux-riscv64-gnu": "1.74.0", "@oxlint/binding-linux-riscv64-musl": "1.74.0", "@oxlint/binding-linux-s390x-gnu": "1.74.0", "@oxlint/binding-linux-x64-gnu": "1.74.0", "@oxlint/binding-linux-x64-musl": "1.74.0", "@oxlint/binding-openharmony-arm64": "1.74.0", "@oxlint/binding-win32-arm64-msvc": "1.74.0", "@oxlint/binding-win32-ia32-msvc": "1.74.0", "@oxlint/binding-win32-x64-msvc": "1.74.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.24.0", "vite-plus": "*" }, "optionalPeers": ["oxlint-tsgolint", "vite-plus"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-odGl2s2x5IOJoj3A0v1k0PGBXVFBZeZ2+AK/+K2MJur7Ghi3bkyX5NuLUWHKqa4js1wjep3hJeuTQJOlr+4+dA=="], - "oxlint-tsgolint": ["oxlint-tsgolint@0.20.0", "", { "optionalDependencies": { "@oxlint-tsgolint/darwin-arm64": "0.20.0", "@oxlint-tsgolint/darwin-x64": "0.20.0", "@oxlint-tsgolint/linux-arm64": "0.20.0", "@oxlint-tsgolint/linux-x64": "0.20.0", "@oxlint-tsgolint/win32-arm64": "0.20.0", "@oxlint-tsgolint/win32-x64": "0.20.0" }, "bin": { "tsgolint": "bin/tsgolint.js" } }, "sha512-/Uc9TQyN1l8w9QNvXtVHYtz+SzDJHKpb5X0UnHodl0BVzijUPk0LPlDOHAvogd1UI+iy9ZSF6gQxEqfzUxCULQ=="], + "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=="], "tinypool": ["tinypool@2.1.0", "", {}, "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw=="], } diff --git a/package.json b/package.json index b727e7a..55f6f9c 100644 --- a/package.json +++ b/package.json @@ -9,9 +9,9 @@ "validate:skills": "bun scripts/validate-skills.js" }, "devDependencies": { - "oxfmt": "^0.44.0", - "oxlint": "^1.62.0", - "oxlint-tsgolint": "^0.20.0" + "oxfmt": "^0.59.0", + "oxlint": "^1.74.0", + "oxlint-tsgolint": "^0.24.0" }, "packageManager": "bun@1.3.11" } From 56ed25ba21a16860eccd38b42cfdb4a876f46ece Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 19:56:04 +0100 Subject: [PATCH 35/52] docs: remove research and decision records --- ...n-skills-with-established-methodologies.md | 35 --- ...-ground-skill-methodologies-in-research.md | 35 --- ...ill-design-on-the-main-success-scenario.md | 31 -- .../20260714-architecture-review-method.md | 231 --------------- .../research/20260714-debugging-techniques.md | 248 ---------------- ...0260715-agent-skill-authoring-methods-2.md | 170 ----------- ...0260715-agent-skill-authoring-methods-3.md | 274 ------------------ .../20260715-agent-skill-authoring-methods.md | 149 ---------- .../20260715-product-definition-method.md | 144 --------- 9 files changed, 1317 deletions(-) delete mode 100644 docs/adr/0001-govern-skills-with-established-methodologies.md delete mode 100644 docs/adr/0002-ground-skill-methodologies-in-research.md delete mode 100644 docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md delete mode 100644 docs/research/20260714-architecture-review-method.md delete mode 100644 docs/research/20260714-debugging-techniques.md delete mode 100644 docs/research/20260715-agent-skill-authoring-methods-2.md delete mode 100644 docs/research/20260715-agent-skill-authoring-methods-3.md delete mode 100644 docs/research/20260715-agent-skill-authoring-methods.md delete mode 100644 docs/research/20260715-product-definition-method.md diff --git a/docs/adr/0001-govern-skills-with-established-methodologies.md b/docs/adr/0001-govern-skills-with-established-methodologies.md deleted file mode 100644 index 31cd313..0000000 --- a/docs/adr/0001-govern-skills-with-established-methodologies.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -status: superseded -superseded-by: './0002-ground-skill-methodologies-in-research.md' ---- - -# Govern skills with established methodologies - -## Decision - -Give every Propulsion skill one established governing methodology and add named -supporting concepts only for distinct concerns. Use canonical terms without -source attribution in finished skill text, and keep router skills limited to -unique coordination while called skills remain authoritative. - -## Context - -Propulsion needs predictable agent behaviour without large instructions that -repeat knowledge the agent already has. Detailed bespoke procedures consume -context and drift between skills, while loose prompts do not stabilise the -process. Established methodology names provide a compact shared vocabulary, but -their fit must be researched and confirmed rather than selected for familiarity -alone. Composition also creates a choice between repeating dependency guidance -inside routers and preserving one authority for each behaviour. - -## Ramifications - -Skill design now includes eliciting concrete use cases, selecting and approving -the governing methodology, and compressing the resulting workflow until every -remaining statement affects behaviour. Supporting concepts and resources must -earn their place through distinct needs. Routers stay small and changes to a -called skill propagate without duplicated instructions becoming stale. Source -provenance remains design evidence or a research-report concern rather than -finished skill prose. Reconsider this decision if canonical terminology no -longer produces sufficiently reliable agent behaviour without fuller local -explanation. diff --git a/docs/adr/0002-ground-skill-methodologies-in-research.md b/docs/adr/0002-ground-skill-methodologies-in-research.md deleted file mode 100644 index 2ca27e4..0000000 --- a/docs/adr/0002-ground-skill-methodologies-in-research.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -status: accepted -supersedes: './0001-govern-skills-with-established-methodologies.md' ---- - -# Ground skill methodologies in research - -## Decision - -Research credible governing methodologies for every Propulsion skill and let the -user choose among the supported options. Use the selected methodology to govern -the skill when one fits; allow the skill to proceed without one when research -reaches saturation without a suitable candidate. Add supporting concepts only -when evidence shows that they govern distinct concerns. - -## Context - -Requiring a methodology gave skills a compact conceptual anchor, but it also -made the presence of a methodology more important than its fit. A weak or -ceremonial choice can obscure the intended behaviour while appearing rigorous. -The alternatives were to preserve the mandatory rule, abandon methodological -grounding, or make research and user choice mandatory while making adoption -evidence-dependent. - -## Ramifications - -Skill authoring delegates methodology and supporting-concept investigations to -the research workflow, then compares its credible alternatives. A selected -methodology appears by canonical name in the runtime skill, while a justified -absence remains visible in the authoring record. Supporting concepts have no -required count. Mechanical validation does not attempt to determine -methodological legitimacy; semantic review and forward testing establish -whether the finished instructions produce the intended behaviour. Reconsider -this decision if methodology-free skills show greater behavioural variance than -evidence-backed alternatives. diff --git a/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md b/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md deleted file mode 100644 index d30611c..0000000 --- a/docs/adr/0003-centre-skill-design-on-the-main-success-scenario.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -status: accepted ---- - -# Centre skill design on the main success scenario - -## Decision - -Design, review, and forward-test each skill around one main success scenario. -Apply YAGNI to speculative branches and retain an exception only when -representative evidence, the primary behaviour, or a necessary safety or -permission boundary requires it. Use progressive disclosure when a rare -retained exception needs depth that would obscure the common path. - -## Context - -Exhaustively exploring possible branches during elicitation produced bloated -skills and diluted the behaviour they were meant to teach. Arbitrary question or -scenario limits could stop useful discovery without distinguishing consequential -behaviour from imagination. The [research -snapshot](../research/20260715-agent-skill-authoring-methods-2.md) supports a -main-scenario backbone with an evidence-and-risk threshold for exceptions. - -## Ramifications - -Authoring interviews stop when the dominant behaviour and its material -exceptions are confirmed rather than when every imaginable path has been -discussed. Reviews prioritise impact on that dominant behaviour, and forward -tests cover the main scenario plus retained exceptions. Agents handle -unmodelled variation contextually, so reconsider this decision if recurring -failures show that the admission threshold omits necessary behaviour. diff --git a/docs/research/20260714-architecture-review-method.md b/docs/research/20260714-architecture-review-method.md deleted file mode 100644 index e76baf2..0000000 --- a/docs/research/20260714-architecture-review-method.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: 'Architecture review method and interactive report design' -createdAt: 2026-07-14 -updatedAt: 2026-07-15 -status: current ---- - -# Architecture review method and interactive report design - -## Research question and scope - -**Question:** Which established methods should govern Propulsion's -`review-architecture` skill, how should it select high-value redesigns from a -codebase, and what interaction and accessibility criteria should govern its -self-contained HTML report? - -**Intended use:** Support the confirmed `review-architecture` skill and its -progressively disclosed analysis and report-design references. - -**Scope:** Static repository inspection, context-aware modular redesign, -quality-attribute trade-offs, incremental migration, architecture fitness -evidence, information visualisation, and accessible HTML. A formal stakeholder -ATAM workshop, implementation of recommendations, framework-specific design -rules, and proof of business priority from source code alone are excluded. - -## Conclusion - -**Information hiding** is the strongest governing methodology. It gives the -review a concrete unit of analysis: difficult or change-prone design decisions -should be hidden behind cohesive module contracts. **Deep modules** operationalise -the desired result, while **design it twice** prevents the first plausible -decomposition from becoming the recommendation by default. - -Use a lightweight adaptation of **ATAM** to rank candidates against evidenced -quality-attribute scenarios and expose risks and trade-offs. The review should -inspect all in-scope architecture and report every redesign whose benefit, -reach, feasibility, and confidence justify action without imposing a minimum or -maximum count. Every retained recommendation should include an incremental -migration path and an observable fitness check. - -Two references are justified: - -- `references/architecture-analysis.md` should hold the conditional diagnostic, - alternative-design, ranking, migration, and fitness guidance; -- `references/report-design.md` should hold the stable HTML information - architecture, visual language, interaction, accessibility, and visual-QA - contract. - -The common inspection-to-report sequence belongs in `SKILL.md`. A reusable -HTML asset or generator script is not yet justified: the report structure is -stable, but its diagrams and evidence are codebase-specific, and the existing -plan explicitly assigns `report-design.md` to this skill. - -## Findings - -### Information hiding supplies the governing decomposition criterion - -Parnas rejects decomposition by processing order and instead starts from -difficult or likely-to-change design decisions, assigning modules that hide -those decisions from one another -([Parnas, 1972](https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf)). -This directly matches the intended review targets: leaked implementation, -shallow interfaces, weak boundaries, and harmful change propagation. - -Ousterhout's Stanford notes make the same criterion operational: a module has -an interface and implementation; information leakage occurs when other modules -depend on implementation knowledge; and bringing leaked knowledge together can -produce a simpler, deeper interface -([modular design notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter18/lecture.php%3Ftopic%3DmodularDesign)). -His course review explicitly includes deep and shallow classes, information -hiding, dependencies, and design it twice as linked design ideas -([course review](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter20/lecture.php?topic=bookReview)). - -**Inference:** the review should map capabilities and contracts rather than -equating modules with directories, files, classes, or services. For each -candidate boundary it should identify the knowledge or design decision being -hidden, the consumers that should depend on the contract, and the details that -should move behind it. A candidate is weaker when it merely adds a layer, -renames folders, or redistributes code without reducing exposed knowledge or -change propagation. - -### Quality scenarios turn general preferences into prioritised redesigns - -ATAM translates business context into quality-attribute scenarios described by -a stimulus and desired response, prioritises them by mission importance and -perceived risk, traces the highest-priority scenarios through architectural -approaches, and identifies risks, sensitivity points, and trade-off points -([SEI report](https://www.sei.cmu.edu/documents/629/2000_005_001_13706.pdf)). -For modifiability, it measures response through affected components, -connectors, interfaces, and change effort. - -The skill cannot run a formal stakeholder workshop from repository evidence -alone. It can still apply the useful core: - -1. recover explicit quality drivers from product context, decisions, - operational configuration, tests, incidents, and repeated change patterns; -2. express relevant drivers as concrete change or runtime scenarios; -3. trace each scenario through modules, contracts, data, and runtime boundaries; -4. label inferred drivers and uncertain priorities rather than presenting them - as stakeholder-confirmed facts; -5. compare at least two materially different boundaries for every serious - candidate before selecting a target design; -6. rank candidates by evidenced quality impact, architectural reach or - recurrence, migration feasibility and risk, and confidence in the evidence. - -This preserves ATAM's trade-off discipline without pretending a static review -has stakeholder authority it does not possess. Recommendation count should be -determined only by the qualifying evidence, including zero findings; ties should -favour higher confidence and an independently deliverable first slice. - -### Supporting principles are diagnostics and conditional patterns - -The supporting concepts should not become an architecture-pattern checklist. -Their useful roles are distinct: - -- **Cohesion and coupling** test whether knowledge that changes together is - gathered behind one contract and whether consumers know more than that - contract requires. **Single responsibility principle** sharpens the same - question around actors or reasons for change - ([Martin's formulation](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html)). -- **Dependency inversion** is relevant when policy depends directly on a - volatile mechanism. **Ports and adapters** is a candidate only when a - purposeful application conversation needs multiple technologies, isolated - tests, or an inside/outside boundary; Cockburn explicitly defines ports by - purposeful conversations and adapters by technology translation - ([original article](https://alistair.cockburn.us/hexagonal-architecture)). -- **Seams** identify places where behaviour can be verified or a dependency - replaced during migration. They are evidence of incremental feasibility, not - a reason to introduce an interface everywhere. -- **Strangler fig** is appropriate when a high-risk existing boundary must be - replaced gradually rather than through a big-bang rewrite - ([Fowler's updated description](https://martinfowler.com/bliki/StranglerFigApplication.html)). -- **Architecture fitness functions** turn a claimed improvement into objective, - repeatable feedback. They may be structural dependency checks, contract or - scenario tests, performance thresholds, security checks, or operational - signals; the measure must correspond to the quality claim - ([Thoughtworks](https://www.thoughtworks.com/en-gb/insights/articles/fitness-function-driven-development)). - -**Inference:** every recommendation should say why its selected pattern fits -this codebase and name a credible alternative it rejected. A recommendation -that invokes a fashionable pattern without evidence of the problem it solves -should be discarded. - -### The report should support comparison before deep reading - -Shneiderman's visual information-seeking method begins with an overview, then -zooming and filtering, then details on demand -([1996 paper](https://www.cs.umd.edu/~ben/papers/Shneiderman1996eyes.pdf)). -This fits the report's decision task: a reader first needs the ranked overview, -then comparison by impact, effort, risk, confidence, or affected capability, -then evidence and migration detail for one recommendation. - -The initial view should therefore contain the review scope, evidence confidence, -current-system overview, and compact recommendation cards. Each card should -make the problem, target boundary, expected improvement, cost, risk, and first -slice comparable without expansion. Details should disclose the evidence, -affected contracts, rejected alternative, migration stages, dependencies, -fitness checks, and source locations. Diagrams should communicate boundary and -dependency changes; prose should remain the fallback when a diagram is not the -clearest representation. - -The confirmed project constraint is one generated HTML file, not offline or -dependency-free operation. It may load current CDN scripts and styles such as -Tailwind and Mermaid when they improve the report, without a graceful-degradation -or long-term compatibility requirement. Visual QA must verify those dependencies -at generation time. WCAG 2.2 requires keyboard operation for all functionality, -and W3C guidance also calls for visible focus, adequate contrast, consistent -interactive styles, and information that does not rely on colour alone -([WCAG 2.2](https://www.w3.org/TR/WCAG22/), -[WAI design guidance](https://w3c.github.io/wai-website/tips/designing/)). - -Visual QA should verify the generated artifact at desktop and narrow viewport -sizes, exercise every control by keyboard, inspect default and expanded states, -check overflow and print output, and confirm that diagrams and evidence remain -understandable without colour. Source links and paths should resolve where the -runtime permits; missing tools should be reported as an explicit verification -limitation rather than silently skipped. - -## Conflicts - -- Single responsibility, dependency inversion, ports and adapters, and the - strangler fig pattern can all improve a design, but applying them as universal - rules can add shallow interfaces and indirection. Information hiding remains - authoritative; the patterns are conditional candidate designs. -- A codebase may evidence technical quality drivers but not their true business - priority. The report must distinguish explicit context from reviewer - inference and lower confidence accordingly. -- Quantitative architecture metrics can create false precision. Ranking should - be an explained comparison supported by source evidence, not an opaque score - whose arithmetic substitutes for judgment. - -## Limitations - -- The primary source for deep modules and design it twice is split between a - commercial book and the author's Stanford course notes. The notes confirm the - concepts and their relationship but do not reproduce the book's full - treatment. -- Forward testing generated and structurally validated an interactive - architecture report, including its filters and unavailable-browser branch. - Actual browser rendering and the optional CDN dependency path remain - unverified because the available browser blocked the local report URL. -- Framework-specific constraints change over time. The eventual skill should - invoke `research` only when a recommendation materially depends on external - framework, language, platform, or architecture evidence that deserves a - durable cited record. - -## Method - -On 2026-07-14, the investigation inspected `SKILLS_PLAN.md`, `CONTEXT.md`, the -target bundle, the authoring contract, the skill-section rules, and the current -research template. It then followed concepts in the plan to original papers, -authors' publications, official institutional reports, and W3C standards. -Evidence was compared across module decomposition, alternative design, -quality-attribute evaluation, migration, continuous verification, information -visualisation, and accessibility. The proposed workflow was falsified against -three risks: pattern-driven overdesign, false stakeholder certainty, and an -interactive report that hides rather than clarifies evidence. - -## Primary sources - -- [On the Criteria To Be Used in Decomposing Systems into Modules](https://www.cs.umd.edu/class/spring2003/cmsc838p/Design/criteria.pdf) — David L. Parnas, Communications of the ACM 15(12), 1972; information-hiding decomposition. -- [Modular Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter18/lecture.php%3Ftopic%3DmodularDesign) — John Ousterhout, Stanford CS 190 lecture notes, 2018; deep interfaces and information leakage. -- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter20/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190 lecture notes, 2020; deep modules and design it twice. -- [ATAM: Method for Architecture Evaluation](https://www.sei.cmu.edu/documents/629/2000_005_001_13706.pdf) — Kazman, Klein, and Clements, CMU/SEI-2000-TR-004, 2000; quality scenarios, risk, and trade-offs. -- [Hexagonal Architecture](https://alistair.cockburn.us/hexagonal-architecture) — Alistair Cockburn, original 2005 article; purpose-led ports and technology adapters. -- [The Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html) — Robert C. Martin, 2014; actors, reasons for change, cohesion, and coupling. -- [Strangler Fig](https://martinfowler.com/bliki/StranglerFigApplication.html) — Martin Fowler, updated 2024; gradual legacy replacement. -- [Fitness function-driven development](https://www.thoughtworks.com/en-gb/insights/articles/fitness-function-driven-development) — Paula Paul and Rosemary Wang, Thoughtworks, 2019; objective architectural feedback. -- [The Eyes Have It](https://www.cs.umd.edu/~ben/papers/Shneiderman1996eyes.pdf) — Ben Shneiderman, IEEE Symposium on Visual Languages, 1996; overview, filtering, and details on demand. -- [Web Content Accessibility Guidelines 2.2](https://www.w3.org/TR/WCAG22/) — W3C Recommendation, 2023; interaction and presentation accessibility requirements. -- [Designing for Web Accessibility](https://w3c.github.io/wai-website/tips/designing/) — W3C Web Accessibility Initiative, accessed 2026-07-14; practical focus, contrast, colour, and interaction guidance. diff --git a/docs/research/20260714-debugging-techniques.md b/docs/research/20260714-debugging-techniques.md deleted file mode 100644 index f21f5c5..0000000 --- a/docs/research/20260714-debugging-techniques.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -title: 'Concrete debugging techniques for coding agents' -createdAt: 2026-07-14 -updatedAt: 2026-07-14 -status: current ---- - -# Concrete debugging techniques for coding agents - -## Research question and scope - -**Question:** Which proven, concrete debugging techniques should Propulsion's -user-invoked `debug` skill expose to help coding agents establish a repeatable -failing signal, isolate a root cause, and verify a repair; and should their -detail live in a progressively disclosed reference rather than `SKILL.md`? - -**Intended use:** Inform a review recommendation only. This report does not -authorise a change to the skill. - -**Scope:** Issue-agnostic techniques for tests, HTTP, CLI, browser, captured -event replay, flaky and concurrent failures, performance, bisection, -instrumentation, causal tracing, and regression verification. Language-specific -debugger commands and generic troubleshooting catalogues are excluded. Stable -classic techniques use original publications; tool examples use official -documentation current on 2026-07-14. Matt Pocock's local `diagnosing-bugs` skill -and obra's `systematic-debugging` skill are design comparators, not evidence of -effectiveness. - -## Conclusion - -The current [`debug` skill](../../skills/debug/SKILL.md) has the right governing -loop and already covers failing tests, benchmarks, traces, probes, minimal -reproductions, binary search, delta debugging, causal repair, and layered -verification. It needs more concrete guidance only where an agent must choose -_how_ to create the signal or discriminating experiment. The material gaps are: - -- an executable signal quality gate that asserts the exact symptom rather than - merely exercising the path; -- capture-and-replay, differential, property/fuzz, flaky/concurrent, - performance, and boundary-tracing selection branches; -- the artefact each branch must retain so another run can reproduce the result. - -One compact `references/TECHNIQUES.md` is justified. The repository's own -[resource rule](../../skills/write-skill/references/SECTIONS.md) assigns -conditional knowledge to `references/` and requires its pointer beside the -branch that uses it; the [suite plan](../../SKILLS_PLAN.md) keeps common-path -behaviour in `SKILL.md`. Keep the scientific loop and no-signal stop condition -in `SKILL.md`, add one conditional pointer when the failing signal or next -experiment is not obvious, and make the reference a decision guide rather than -an encyclopaedia. Source attribution should remain here, not in the eventual -skill. - -## Findings - -### A failing signal needs an oracle, not just an invocation - -The current skill names useful signal forms but does not say what makes one -diagnostically sharp. An HTTP command, CLI invocation, or browser script can run -successfully while missing the reported bug. For example, curl does not treat -HTTP error statuses as command failure by default; `--fail-with-body` changes the -exit status for most 4xx/5xx responses while preserving the body, and the curl -manual records authentication exceptions. A robust HTTP probe therefore needs -explicit assertions for the relevant status, headers, or body, not only a curl -exit code ([curl manual](https://curl.se/docs/manpage.html#--fail-with-body)). -Playwright likewise separates driving the page from asserting the expected -condition, and its web assertions wait for the condition -([Playwright assertions](https://playwright.dev/docs/test-assertions)). - -**Inference:** the common quality gate should require one already-run, -agent-runnable command or probe that (1) reaches the relevant path, (2) asserts -the user's exact symptom, (3) runs quickly enough for the debugging loop, and -(4) is deterministic or reports a measured reproduction rate. Record the -command, fixture or captured input, expected verdict, observed verdict, and any -seed, environment, or schedule needed for replay. This changes agent behaviour; -the labels “HTTP”, “CLI”, and “browser” alone do not. - -### Signal techniques should be selected by symptom and seam - -The reference should offer this compact selection guidance: - -| Condition | Technique and minimum observable signal | Material addition | -| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -| A stable test seam reaches the fault | Focused failing test or minimal harness; assert the exact behaviour and preserve the fixture | Mostly present; clarify the oracle quality gate | -| The fault is at an HTTP boundary | Script one request and assert status plus the relevant body/header; preserve request payload and response | Concrete instantiation of “targeted probe” | -| The fault is a CLI contract | Run a fixture input and assert exit status, stdout, and/or stderr against the expected result; record relevant flags and environment | Concrete instantiation of “targeted probe” | -| The fault requires real browser behaviour | Headless browser script asserting the relevant DOM, console, request, or response outcome | Concrete instantiation; browser assertions are distinct from navigation | -| Only a production request or event exposes the fault | Capture the smallest safe request/event artefact and replay it at the nearest stable seam | New branch; useful when local construction loses the trigger | -| The bad input is unknown or combinatorial | Property/fuzz loop with an explicit invariant; preserve the seed/failing artefact and minimise it before diagnosis | New branch; complements rather than replaces an observed-bug reproduction | -| The failure is intermittent | Repeat the exact trigger, report attempts and failure rate, then control time, randomness, order, load, or scheduling one variable at a time | New branch; turns “not deterministic” into a measurable signal | -| The fault is concurrent | Prefer a deterministic/systematic scheduler or recorded schedule when available; use stress only to amplify and capture a failure | New branch; stress alone is not reliable isolation | -| The fault is performance | Establish a controlled baseline and failing threshold, repeat measurements, then profile the failing workload before changing code | Makes the current “benchmark” signal operational | - -These are supported as technique families, not mandates for particular tools. -Playwright documents strict request/payload matching for recorded HAR replay, -which demonstrates how a captured network interaction can become a repeatable -fixture ([Playwright HAR replay](https://playwright.dev/docs/mock#mocking-with-har-files)). -LLVM's current libFuzzer documentation requires a fast, narrow, deterministic -target, writes the failure-inducing input to disk, supports crash minimisation, -and can replay saved inputs as regression tests -([libFuzzer target and corpus guidance](https://llvm.org/docs/LibFuzzer.html)). -The original QuickCheck publication supports generated inputs checked against -executable properties, but also records pitfalls; property/fuzz loops therefore -belong only where a meaningful invariant or failure oracle exists -([Claessen and Hughes, 2000](https://research.chalmers.se/en/publication/237427)). - -For concurrency, repeated stress can raise the chance of observing a bug but -does not make the schedule reproducible. The CHESS publication reports that -ordinary stress has unpredictable coverage, while systematic schedule control -can reproduce the erroneous interleaving -([Musuvathi, Qadeer, and Ball, 2008](https://www.usenix.org/legacy/event/osdi08/tech/full_papers/musuvathi/musuvathi_html/index.html)). -An empirical study of 201 flaky-test fixes found asynchronous waiting, -concurrency, and test-order dependency to be its dominant categories; this -supports deliberately varying timing and order, recording environmental state, -and replacing guessed delays with explicit conditions after the cause is known -([Luo et al., 2014](https://huang.isis.vanderbilt.edu/cs8395/paper/flakytest.pdf)). -Its Apache-heavy sample is evidence for those branches, not universal incidence -rates. -For performance, the exact benchmark tool is contextual, but controlled warmup, -repetition, and reported variance are concrete safeguards against treating one -noisy timing as a cause -([Google Benchmark user guide](https://github.com/google/benchmark/blob/main/docs/user_guide.md#runtime-and-reporting-considerations)). - -### Isolation needs a small set of distinct experiment patterns - -The current skill already names minimal reproducible examples, binary search, -and delta debugging. Delta debugging is strongly applicable: the original -publication automatically reduced a 95-action browser failure to three actions -and 896 lines of HTML to one failure-inducing line, while explicitly requiring -an automated test outcome -([Zeller and Hildebrandt, 2002](https://www.st.cs.uni-saarland.de/papers/tse2002/)). - -Three additional patterns materially improve technique selection: - -1. **Automated bisection:** when known-good and known-bad states exist, drive a - stable predicate across commits, versions, inputs, datasets, or configurations. - Git's official `bisect run` contract demonstrates the critical requirement: - the script must classify good, bad, and untestable states by exit status - ([Git bisect](https://git-scm.com/docs/git-bisect)). -2. **Differential testing:** run the same input through two comparable - implementations, versions, or configurations and inspect the smallest output - difference. McKeeman's original account reports this as useful when an oracle - is expensive, but warns that legitimate unspecified differences create false - positives - ([McKeeman, 1998](https://www.cs.tufts.edu/comp/150FP/archive/bill-mckeeman/DifferentailTesting.pdf)). -3. **Boundary and backward causal tracing:** instrument only the boundaries that - discriminate current hypotheses, correlate a request across components, and - trace the first bad value or invariant violation backwards to the earliest - divergence. OpenTelemetry explains that propagated context correlates signals - across process boundaries - ([context propagation](https://opentelemetry.io/docs/concepts/context-propagation/)); - the original Dapper report supports distributed traces for understanding - behaviour and performance in complex services - ([Sigelman et al., 2010](https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/)). - -The reference should say when to choose each pattern and what result confirms or -rejects a hypothesis. It should not repeat the skill's existing instruction to -change one variable at a time. - -### Verification is already adequate; add only artefact cleanup and replay detail - -The current skill already requires the original reproduction, focused -regression coverage, nearby checks, wider repository checks, and separation of -pre-existing failures. That is stronger than either comparator's verification -summary and needs no second technique catalogue. - -The reference can add two conditional details: convert a minimised failing -artefact into regression protection at the strongest stable seam, and remove or -clearly retain temporary instrumentation and throwaway harnesses. A saved fuzz -input being replayable as a regression test is one concrete example -([libFuzzer](https://llvm.org/docs/LibFuzzer.html)); it does not imply every -debugging artefact belongs permanently in the test suite. The existing `$tdd` -composition remains authoritative for red-green-refactor behaviour. - -### The comparators support discoverability, not effectiveness claims - -Matt Pocock's local -`/Users/adam/Developer/matt-pocock-skills/skills/engineering/diagnosing-bugs/SKILL.md` -provides a useful ordered list of concrete signal constructors and operational -qualities such as exact symptom, speed, determinism, and agent-runnability. -Obra's -[systematic-debugging bundle](https://github.com/obra/superpowers/tree/main/skills/systematic-debugging) -uses a short main workflow plus conditional supporting references, including -backward root-cause tracing. These are good design precedents for a compact -selection reference. - -Neither comparator supplies controlled evidence for its claimed productivity -or success rates. Those claims were excluded from this report. The recommended -techniques instead trace to the publications and official documentation above. - -## Conflicts - -- Matt's comparator recommends repeated stress and injected sleeps for - nondeterministic bugs. CHESS shows that stress coverage is unpredictable for - concurrency defects. Repetition and perturbation should be described as - amplification and evidence capture, with controlled schedule replay preferred - when available—not as proof of cause. -- Differential results are candidates, not automatically bugs: comparable - systems may legitimately differ where behaviour is unspecified. -- curl's failure options do not fully classify application correctness and have - documented HTTP authentication exceptions. An HTTP debugging script needs an - explicit symptom oracle. -- Retries can reveal a flaky failure rate, but a passing retry is not repair - verification. Playwright explicitly categorises fail-then-pass as “flaky” - ([Playwright retries](https://playwright.dev/docs/test-retries)). - -## Limitations - -- Technique effectiveness depends on a valid oracle. No general method turns an - ambiguous expected behaviour into a reliable failing signal. -- Systematic schedulers, profilers, tracing, browser automation, and fuzzers are - ecosystem-dependent. The skill should name the technique and let repository - context select the tool. -- Performance measurements remain environment-sensitive even with warmup and - repetition; a local regression threshold may not represent production. -- Production captures can contain secrets or personal data. Any eventual - reference should require minimisation and safe handling under repository and - user permissions. -- The recommendation has not yet been acceptance-tested against a drafted - `TECHNIQUES.md`; that belongs to the authoring decision if the user approves - the change. - -## Method - -On 2026-07-14, the investigation inspected the current `debug` bundle, its plan, -the host's skill-section rules, and the two user-supplied comparators. Source -discovery then followed claims to original publications and current official -tool/project documentation. Evidence was triangulated across signal -construction, input reduction, bisection, differential testing, concurrency, -measurement, tracing, and replay. Comparator claims lacking primary support -were excluded. Conflicts were tested by looking for conditions under which a -technique fails—especially missing oracles, legitimate differential outputs, -noisy benchmarks, and nondeterministic schedules. - -## Primary sources - -- [Simplifying and Isolating Failure-Inducing Input](https://www.st.cs.uni-saarland.de/papers/tse2002/) — Zeller and Hildebrandt, IEEE TSE 28(2), 2002; delta debugging and automated minimisation. -- [Differential Testing for Software](https://www.cs.tufts.edu/comp/150FP/archive/bill-mckeeman/DifferentailTesting.pdf) — McKeeman, Digital Technical Journal 10(1), 1998; comparable-system oracles and limitations. -- [CHESS: A Systematic Testing Tool for Concurrent Software](https://www.usenix.org/legacy/event/osdi08/tech/full_papers/musuvathi/musuvathi_html/index.html) — Musuvathi, Qadeer, and Ball, OSDI 2008; deterministic schedule exploration and replay. -- [An Empirical Analysis of Flaky Tests](https://huang.isis.vanderbilt.edu/cs8395/paper/flakytest.pdf) — Luo et al., FSE 2014; manifestation and repair patterns for nondeterministic tests in an Apache-project sample. -- [QuickCheck: A Lightweight Tool for Random Testing of Haskell Programs](https://research.chalmers.se/en/publication/237427) — Claessen and Hughes, ICFP 2000; property-based generated testing and pitfalls. -- [Dapper, a Large-Scale Distributed Systems Tracing Infrastructure](https://research.google/pubs/dapper-a-large-scale-distributed-systems-tracing-infrastructure/) — Sigelman et al., Google, 2010; cross-component behavioural and performance tracing. -- [Git bisect documentation](https://git-scm.com/docs/git-bisect) — Git project, current documentation accessed 2026-07-14; automated good/bad predicates. -- [curl manual](https://curl.se/docs/manpage.html) — curl project, current manual accessed 2026-07-14; HTTP scripting, exit behaviour, and limitations. -- [Playwright assertions, HAR replay, and retries](https://playwright.dev/docs/test-assertions) — Microsoft Playwright project, current documentation accessed 2026-07-14; browser oracles, captured-network replay, and flaky classification. -- [libFuzzer documentation](https://llvm.org/docs/LibFuzzer.html) — LLVM project, current documentation accessed 2026-07-14; narrow deterministic fuzz targets, saved reproducers, minimisation, and regression replay. -- [Google Benchmark user guide](https://github.com/google/benchmark/blob/main/docs/user_guide.md) — Google Benchmark project, current documentation accessed 2026-07-14; warmup, repetition, and variance reporting. -- [OpenTelemetry context propagation](https://opentelemetry.io/docs/concepts/context-propagation/) — OpenTelemetry project, current documentation accessed 2026-07-14; cross-boundary signal correlation. -- [Skill Sections](../../skills/write-skill/references/SECTIONS.md) and [Propulsion Skills Plan](../../SKILLS_PLAN.md) — repository authorities accessed 2026-07-14; progressive disclosure and resource placement. diff --git a/docs/research/20260715-agent-skill-authoring-methods-2.md b/docs/research/20260715-agent-skill-authoring-methods-2.md deleted file mode 100644 index 84fc1dc..0000000 --- a/docs/research/20260715-agent-skill-authoring-methods-2.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: 'Agent skill authoring methods' -createdAt: 2026-07-15 -updatedAt: 2026-07-15 -status: superseded -supersedes: './20260715-agent-skill-authoring-methods.md' -supersededBy: './20260715-agent-skill-authoring-methods-3.md' ---- - -# Agent skill authoring methods - -## Research question and scope - -**Question:** Which governing methodology, supporting concepts, and scenario -boundary best produce predictable agent skills without diluting their primary -behaviour through speculative exceptions? - -**Intended use:** Refine Propulsion's `write-skill` workflow and its authored -skill contract. - -**Scope:** Skill purpose discovery, methodology selection, scenario admission, -information hierarchy, language, structure, review, and behavioural validation. -Sources were assessed on 2026-07-15. Product-specific invocation metadata and -claims about a universal causal mechanism for leading words are excluded. - -## Conclusion - -The evidence-informed design conclusion is to retain **minimalist instruction** -as the governor for `write-skill`, use the **main success scenario** as its -behavioural backbone, and apply **YAGNI** to presumptive exceptions. Propulsion -adapts these sources into a three-part admission rule: retain an exception only -when representative evidence, success of the primary behaviour, or a necessary -safety or permission boundary requires it. **Progressive disclosure** keeps rare -retained exceptions available without competing with the common path. **Design -it twice**, **separation of concerns**, and **DRY** continue to govern -methodology choice, structure, and semantic compression. - -## Findings - -### Minimalist instruction governs the authoring workflow - -John Carroll's minimalist instruction leverages learner initiative and prior -knowledge rather than controlling every action through warnings and ordered -steps. It also treats error recognition, diagnosis, and recovery as resources. -That supports a small behavioural surface which recruits an agent's existing -knowledge while retaining necessary bounds. [Carroll, “Creating Minimalist -Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) - -### The main success scenario provides the behavioural backbone - -Jacobson and Cockburn define the basic flow as the normal path to value, also -called the main scenario or happy path. Their use-case guidance permits starting -with a sketch, adding detail as needed, and delivering key flows before less -used or less critical ones. The adaptation for skill authoring is to make that -main scenario the dominant contract rather than treating every conceivable -alternate flow as equally instruction-worthy. [Use-Case -Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) - -### YAGNI filters presumptive exceptions - -Martin Fowler describes YAGNI as the Extreme Programming practice of withholding -presumptive capability until it is needed because speculative support adds -complexity before its requirements are understood. Applied to skills, a -hypothetical branch is presumptive instructional capability: it should not enter -the contract merely because it can be imagined. This is an adaptation, not a -claim that YAGNI itself defines skill design. [Fowler, -“Yagni”](https://martinfowler.com/bliki/Yagni.html) - -### Materiality preserves necessary exceptions - -YAGNI does not justify omitting behaviour already required by the present -contract. A candidate exception remains material when a representative -invocation evidences it, the main behaviour cannot succeed without it, or a -necessary safety or permission boundary requires explicit handling. This -three-part admission rule is an inference combining present need under YAGNI -with the use-case distinction between a basic flow and less critical flows; its -safety and permission condition is a normative Propulsion boundary rather than -a sourced YAGNI rule. [Fowler, -“Yagni”](https://martinfowler.com/bliki/Yagni.html), [Use-Case -Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) - -### Progressive disclosure protects the common path - -The Agent Skills specification permits optional `scripts/`, `references/`, and -`assets/` beside `SKILL.md`. Anthropic describes staged loading and recommends -keeping the core workflow in `SKILL.md` while moving detailed or variant-specific -knowledge into linked resources. A rare exception that passes the materiality -test can therefore remain available without inflating the main instructions. -[Agent Skills specification](https://agentskills.io/specification), [Anthropic -skill architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), -[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Credible alternatives expose methodological trade-offs - -Ousterhout includes **Design it twice** among the principal practices in _A -Philosophy of Software Design_. Propulsion infers from that practice a -requirement to compare credible methodology alternatives rather than accept the -first plausible match. [Stanford CS 190 lecture -notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) - -### Structure and compression retain distinct authorities - -Dijkstra's separation of concerns supports giving each skill section one -coherent behavioural idea. The Pragmatic Programmer's DRY principle supports -one authoritative expression of each meaning. Together they keep the dominant -thread legible while preventing rare retained exceptions or repeated guidance -from competing with it. [Dijkstra, EWD -803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html), -[The Pragmatic Programmer, DRY -chapter](https://media.pragprog.com/titles/tpp20/dry.pdf) - -### Forward testing follows the same scenario boundary - -Anthropic recommends evaluation before and after skill changes, including tests -for triggering and instruction compliance. The scenario-admission inference is -to forward-test the main success scenario first and add a scenario only for a -retained material exception. This tests the contract rather than generating a -new inventory of hypothetical branches during evaluation. [Anthropic authoring -guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Leading words remain an evidence-tested heuristic - -Kojima et al. show that a short canonical phrase can substantially change model -behaviour in a bounded reasoning setting. It remains an inference, not a -universal law, that methodology names reliably recruit equivalent pretraining -across agent tasks; representative forward tests must validate the finished -wording. [Kojima et al., “Large Language Models are Zero-Shot -Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) - -## Conflicts - -Jacobson and Cockburn define a complete use case as including successful, -challenged, and failure paths. Propulsion deliberately applies only its main -success scenario as the authoring backbone, then admits exceptions through a -materiality test; it should not describe this narrower adaptation as exhaustive -use-case modelling. Fowler also limits YAGNI to presumptive capability and does -not use it to reject present requirements or enabling work. The safety, -permission, and primary-behaviour conditions preserve those present needs. - -## Limitations - -No primary evidence validates the three-part material-exception threshold -specifically for agent skills. It is an evidence-informed design inference that -requires forward testing. No primary evidence establishes an optimal leading -word, bolding frequency, body length, or reference granularity across -Propulsion's target models. - -## Method - -The investigation refreshed the prior 2026-07-15 authoring report after observed -elicitation and review behaviour showed that exhaustive scenario discovery -diluted the skill's primary thread. It compared first-party use-case definitions, -Fowler's published account of YAGNI, the current Propulsion bundle, Agent Skills -guidance, and the previously selected methods. Material claims were traced to -original authors, official specifications, first-party documentation, or -published research; adaptations to agent instruction were identified as -inferences. - -## Primary sources - -- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. -- [Use-Case Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) — Ivar Jacobson and Alistair Cockburn, accessed 2026-07-15; basic flow, alternate flows, and incremental detail. -- [Yagni](https://martinfowler.com/bliki/Yagni.html) — Martin Fowler, 2015, accessed 2026-07-15; presumptive capability and evolutionary design. -- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. -- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. -- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. -- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. -- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. -- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. -- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022; behavioural effect of a compact canonical phrase. diff --git a/docs/research/20260715-agent-skill-authoring-methods-3.md b/docs/research/20260715-agent-skill-authoring-methods-3.md deleted file mode 100644 index 03f68b3..0000000 --- a/docs/research/20260715-agent-skill-authoring-methods-3.md +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: 'Agent skill authoring methods' -createdAt: 2026-07-15 -updatedAt: 2026-07-15 -status: current -supersedes: './20260715-agent-skill-authoring-methods-2.md' ---- - -# Agent skill authoring methods - -## Research question and scope - -**Question:** Which governing methodology, supporting concepts, and scenario -boundary best produce predictable agent skills without diluting their primary -behaviour through speculative exceptions, and can ironic process theory support -a requirement for positive behavioural instructions during compression? - -**Intended use:** Refine Propulsion's `write-skill` workflow and the skills it -creates or updates. The workflow may assess an existing bundle as evidence for -an update, but standalone skill review is outside this report's intended scope. - -**Scope:** Skill purpose discovery, methodology selection, scenario admission, -information hierarchy, language, structure, update-oriented assessment, and -behavioural validation. Human thought-suppression research, original -language-model negation studies, and first-party model guidance were assessed on -2026-07-15. Product-specific invocation metadata, standalone review outputs, and -claims that human mental-control mechanisms explain transformer behaviour are -excluded. - -## Conclusion - -The evidence-informed design conclusion is to retain **minimalist instruction** -as the governor for `write-skill`, use the **main success scenario** as its -behavioural backbone, and apply **YAGNI** to presumptive exceptions. Propulsion -adapts these sources into a three-part admission rule: retain an exception only -when representative evidence, success of the primary behaviour, or a necessary -safety or permission boundary requires it. **Progressive disclosure** keeps rare -retained exceptions available without competing with the common path. **Design -it twice**, **separation of concerns**, and **DRY** continue to govern -methodology choice, structure, and semantic compression. - -During compression, express an executable target affirmatively when that wording -preserves the contract. Retain a negative prohibition when safety, permission, -or precision makes the prohibition material, and pair it with the intended -alternative when one exists. **Ironic process theory** is credible evidence -about human mental control and a useful analogy for this preference; it is not -evidence of a transformer mechanism and cannot by itself justify an agent-skill -rule. The rule is instead a bounded engineering adaptation supported by direct, -but non-universal, evidence that language models can mishandle negation, -first-party prompting guidance, and representative forward tests. - -`write-skill` creates a new skill or updates an existing one. Assessment of an -existing skill serves that update path rather than becoming a standalone review -deliverable. This is a normative Propulsion scope decision, not an empirical -finding from the cited literature. - -The confirmed behavioural contract remains the fixed scope and decision -authority for methodology and supporting-concept research. Sources determine how -the skill teaches that behaviour; source-discovered possibilities do not become -new product requirements. This is a normative workflow boundary reinforced by a -forward test in which method research otherwise expanded a concise summary skill -with unrequested empty states, ambiguity rules, reversals, and compliance scope. -The confirmed design remains closed during drafting for the same reason: wording -and structure may improve its expression, while new behaviour returns to design -confirmation before entering the bundle. - -## Findings - -### Minimalist instruction governs the authoring workflow - -John Carroll's minimalist instruction leverages learner initiative and prior -knowledge rather than controlling every action through warnings and ordered -steps. It also treats error recognition, diagnosis, and recovery as resources. -That supports a small behavioural surface which recruits an agent's existing -knowledge while retaining necessary bounds. [Carroll, “Creating Minimalist -Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) - -### The main success scenario provides the behavioural backbone - -Jacobson and Cockburn define the basic flow as the normal path to value, also -called the main scenario or happy path. Their use-case guidance permits starting -with a sketch, adding detail as needed, and delivering key flows before less -used or less critical ones. The adaptation for skill authoring is to make that -main scenario the dominant contract rather than treating every conceivable -alternate flow as equally instruction-worthy. [Use-Case -Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) - -### YAGNI filters presumptive exceptions - -Martin Fowler describes YAGNI as the Extreme Programming practice of withholding -presumptive capability until it is needed because speculative support adds -complexity before its requirements are understood. Applied to skills, a -hypothetical branch is presumptive instructional capability: it should not enter -the contract merely because it can be imagined. This is an adaptation, not a -claim that YAGNI itself defines skill design. [Fowler, -“Yagni”](https://martinfowler.com/bliki/Yagni.html) - -### Materiality preserves necessary exceptions - -YAGNI does not justify omitting behaviour already required by the present -contract. A candidate exception remains material when a representative -invocation evidences it, the main behaviour cannot succeed without it, or a -necessary safety or permission boundary requires explicit handling. This -three-part admission rule is an inference combining present need under YAGNI -with the use-case distinction between a basic flow and less critical flows; its -safety and permission condition is a normative Propulsion boundary rather than -a sourced YAGNI rule. [Fowler, -“Yagni”](https://martinfowler.com/bliki/Yagni.html), [Use-Case -Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) - -### Progressive disclosure protects the common path - -The Agent Skills specification permits optional `scripts/`, `references/`, and -`assets/` beside `SKILL.md`. Anthropic describes staged loading and recommends -keeping the core workflow in `SKILL.md` while moving detailed or -variant-specific knowledge into linked resources. A rare exception that passes -the materiality test can therefore remain available without inflating the main -instructions. [Agent Skills specification](https://agentskills.io/specification), -[Anthropic skill -architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), -[Anthropic authoring -guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Ironic process theory is human evidence, not a model mechanism - -Wegner's theory proposes two human mental-control processes: a capacity-demanding -operator seeks content consistent with the intended state, while a less -demanding monitor searches for signs of failure; under reduced capacity, the -monitor can increase sensitivity to the unwanted content. The original -white-bear experiments found incomplete suppression and a later rebound, while -a specific replacement thought reduced that rebound. A 31-study meta-analysis -found rebound effects regardless of cognitive load, but immediate enhancement -during suppression only under load. This makes ironic process theory a credible, -qualified concept about human thought suppression rather than a general claim -that every negative instruction backfires. [Wegner, “Ironic Processes of Mental -Control”](https://doi.org/10.1037/0033-295X.101.1.34), [Wegner et al., -“Paradoxical Effects of Thought -Suppression”](https://doi.org/10.1037/0022-3514.53.1.5), [Wang, Hagger, and -Chatzisarantis, “Ironic Effects of Thought Suppression: A -Meta-Analysis”](https://doi.org/10.1177/1745691619898795) - -Applying that human theory to a language model would require an unsupported -assumption that transformer inference contains the theory's operator, monitor, -and capacity dynamics. Propulsion therefore uses the theory only as an analogy -that makes the positive-target preference memorable; it does not cite the theory -as the cause of model failures. This boundary is an inference from the mismatch -between the theory's stated human mechanism and the architecture under -instruction. - -### Model evidence supports testing positive targets, not banning negation - -Jang, Ye, and Seo tested nine NLP tasks across pretrained, instruction-tuned, -few-shot, and fine-tuned language models and found materially worse performance -on negated prompts, including an inverse scaling pattern in the tested model -families. Truong et al. likewise found insensitivity to negation and failures of -negation semantics and reasoning across GPT-Neo, GPT-3, and InstructGPT. These -are direct model findings, independent of ironic process theory, but they test -bounded benchmark transformations rather than compressed agent-skill -instructions or current models. [Jang, Ye, and Seo, “Can Large Language Models -Truly Follow your -Instructions?”](https://openreview.net/forum?id=89qDzjrWHLs), [Truong et al., -“Language models are not -naysayers”](https://aclanthology.org/2023.starsem-1.10/) - -Anthropic's current prompting guidance tells authors to specify what Claude -should do instead of only what it should not do, while the same guidance still -uses negative constraints where they precisely define boundaries. That supports -affirmative targets as a model-specific engineering practice, not a universal -causal law. Propulsion adapts the combined evidence into a compression rule: -prefer the positive executable behaviour, preserve material prohibitions, and -forward-test the exact wording. [Anthropic prompting best -practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) - -### Credible alternatives expose methodological trade-offs - -Ousterhout includes **Design it twice** among the principal practices in _A -Philosophy of Software Design_. Propulsion infers from that practice a -requirement to compare credible methodology alternatives rather than accept the -first plausible match. [Stanford CS 190 lecture -notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) - -### Structure and compression retain distinct authorities - -Dijkstra's separation of concerns supports giving each skill section one -coherent behavioural idea. The Pragmatic Programmer's DRY principle supports -one authoritative expression of each meaning. Together they keep the dominant -thread legible while preventing rare retained exceptions or repeated guidance -from competing with it. [Dijkstra, EWD -803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html), -[The Pragmatic Programmer, DRY -chapter](https://media.pragprog.com/titles/tpp20/dry.pdf) - -### Forward testing follows the same scenario boundary - -Anthropic recommends evaluation before and after skill changes, including tests -for triggering and instruction compliance. The scenario-admission inference is -to forward-test the main success scenario first and add a scenario only for a -retained material exception. Positive and negative variants should be compared -when polarity could change the contract. This tests the finished wording rather -than treating either human psychology or a benchmark result as universally -predictive. [Anthropic authoring -guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Leading words remain an evidence-tested heuristic - -Kojima et al. show that a short canonical phrase can substantially change model -behaviour in a bounded reasoning setting. It remains an inference, not a -universal law, that methodology names reliably recruit equivalent pretraining -across agent tasks; representative forward tests must validate the finished -wording. [Kojima et al., “Large Language Models are Zero-Shot -Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) - -## Conflicts - -Jacobson and Cockburn define a complete use case as including successful, -challenged, and failure paths. Propulsion deliberately applies only its main -success scenario as the authoring backbone, then admits exceptions through a -materiality test; it should not describe this narrower adaptation as exhaustive -use-case modelling. Fowler also limits YAGNI to presumptive capability and does -not use it to reject present requirements or enabling work. The safety, -permission, and primary-behaviour conditions preserve those present needs. - -Ironic process theory predicts a human counterintentional effect especially -when mental capacity is reduced, but it supplies no transformer mechanism. The -model studies show negation failures without establishing Wegner's cause, while -Anthropic's own examples retain negative constraints when a prohibition is the -precise requirement. Positive phrasing is therefore a preference for an -explicit executable target, not a ban on `not`, `never`, or `avoid`. - -## Limitations - -No primary evidence validates the three-part material-exception threshold or a -positive-instruction requirement specifically for agent skills. The direct -model studies cover older model families and bounded negation benchmarks; they -do not establish the effect for current Propulsion hosts, long skill bundles, -tool-using agents, safety constraints, or semantically equivalent positive and -negative rewrites. First-party prompting guidance reports recommended practice -rather than a reproducible causal experiment. No primary evidence establishes -an optimal leading word, bolding frequency, body length, or reference -granularity across Propulsion's target models. - -## Method - -The investigation refreshed the prior 2026-07-15 snapshot after the proposed -compression rule was linked to ironic process theory and the intended -`write-skill` scope was narrowed to creation and updates. It citation-chained -from Wegner's original experiment to his theory and a later meta-analysis, -then sought original language-model negation studies and current first-party -prompting guidance. Falsification focused on whether the human mechanism had -been demonstrated in transformers, whether immediate human effects occurred -without cognitive load, and whether direct model evidence justified removing -material negative constraints. It did not. Material claims were traced to -original publications, original empirical syntheses, official specifications, -or first-party documentation; every transfer to skill authoring is labelled as -an adaptation or inference. - -## Primary sources - -- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. -- [Use-Case Foundation](https://www.ivarjacobson.com/publications/use-case-foundation) — Ivar Jacobson and Alistair Cockburn, accessed 2026-07-15; basic flow, alternate flows, and incremental detail. -- [Yagni](https://martinfowler.com/bliki/Yagni.html) — Martin Fowler, 2015, accessed 2026-07-15; presumptive capability and evolutionary design. -- [Ironic Processes of Mental Control](https://doi.org/10.1037/0033-295X.101.1.34) — Daniel M. Wegner, _Psychological Review_, 1994, accessed 2026-07-15; original human mental-control theory. -- [Paradoxical Effects of Thought Suppression](https://doi.org/10.1037/0022-3514.53.1.5) — Daniel M. Wegner et al., _Journal of Personality and Social Psychology_, 1987, accessed 2026-07-15; original white-bear experiments. -- [Ironic Effects of Thought Suppression: A Meta-Analysis](https://doi.org/10.1177/1745691619898795) — Deming Wang, Martin S. Hagger, and Nikos L. D. Chatzisarantis, _Perspectives on Psychological Science_, 2020, accessed 2026-07-15; 31-study synthesis of load, immediate enhancement, and rebound. -- [Can Large Language Models Truly Follow your Instructions?](https://openreview.net/forum?id=89qDzjrWHLs) — Joel Jang, Seonghyeon Ye, and Minjoon Seo, NeurIPS 2022 ML Safety Workshop, accessed 2026-07-15; original negated-prompt experiments. -- [Language models are not naysayers](https://aclanthology.org/2023.starsem-1.10/) — Thinh Hung Truong et al., \*SEM 2023, accessed 2026-07-15; original language-model negation evaluation. -- [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) — Anthropic, accessed 2026-07-15; current first-party positive-instruction guidance and counterexamples retaining precise negative constraints. -- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. -- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. -- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. -- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. -- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. -- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. -- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022; behavioural effect of a compact canonical phrase. diff --git a/docs/research/20260715-agent-skill-authoring-methods.md b/docs/research/20260715-agent-skill-authoring-methods.md deleted file mode 100644 index bd3d655..0000000 --- a/docs/research/20260715-agent-skill-authoring-methods.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: 'Agent skill authoring methods' -createdAt: 2026-07-15 -updatedAt: 2026-07-15 -status: superseded -supersededBy: './20260715-agent-skill-authoring-methods-2.md' ---- - -# Agent skill authoring methods - -## Research question and scope - -**Question:** Which governing methodology, supporting concepts, and bundle -structure best produce predictable, context-aware agent skills with compressed -behavioural language and progressive disclosure? - -**Intended use:** Redesign Propulsion's `write-skill` workflow and its authored -skill contract. - -**Scope:** Skill purpose discovery, methodology selection, information -hierarchy, language, structure, and behavioural validation. Sources were -assessed on 2026-07-15. Product-specific invocation metadata and claims about a -universal causal mechanism for leading words are excluded. - -## Conclusion - -**Minimalist instruction** is the strongest governor for `write-skill`. It -organises instructions around action, prior knowledge, error recovery, and the -smallest useful instructional surface rather than treating brevity as an end in -itself. **Use-case modelling**, **Design it twice**, **Separation of concerns**, -**DRY**, progressive disclosure, contracts, and evaluation-driven iteration -support distinct authoring concerns. Research should seek and compare credible -methods without forcing a methodology or supporting-concept count when the -evidence does not justify one. - -## Findings - -### Minimalist instruction governs the authoring workflow - -John Carroll's account of minimalist instruction describes designs that use -learner initiative and prior knowledge and treat error recognition, diagnosis, -and recovery as resources rather than attempting to control every action. That -directly supports compact skills which recruit an agent's existing knowledge -while retaining explicit behavioural bounds and recovery paths. [Carroll, -“Creating Minimalist Instruction”](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) - -### Use cases recover behaviour before prose is written - -Jacobson and Cockburn define a use case around an actor's goal and the complete -set of successful, challenged, and failure scenarios. They recommend beginning -with a sketch and adding detail when circumstances require it. This supplies the -contract-discovery method without governing the later language and information -hierarchy. [Use-Case Foundation](https://alistaircockburn.com/Use%20Case%20Foundation.pdf) - -### Credible alternatives expose methodological trade-offs - -Ousterhout includes **Design it twice** among the principal practices in _A -Philosophy of Software Design_. Applied here, the concept requires real -methodology alternatives rather than accepting the first plausible match. The -specific rule to continue until multiple credible candidates emerge or research -reaches saturation is an adaptation to this workflow. [Stanford CS 190 lecture -notes](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) - -### Each section should isolate a coherent concern - -Dijkstra describes separation of concerns as isolating aspects so each is small -enough to reason about yet substantial enough to deserve focused attention. -Applied to a skill, one step or subsection should carry one coherent behavioural -idea and observable outcome without fragmenting supporting sentences into -ceremonial headings. [Dijkstra, EWD -803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) - -### Progressive disclosure is an execution hierarchy - -The Agent Skills specification permits optional `scripts/`, `references/`, and -`assets/` beside the required `SKILL.md`. Anthropic describes skills as using -progressive disclosure so metadata, instructions, and resources enter context -at different times, and recommends keeping core workflow in `SKILL.md` while -moving detailed or variant-specific knowledge into linked files. The inference -for Propulsion is that branch need and decision depth—not reluctance or a fixed -size threshold—should govern extraction. [Agent Skills -specification](https://agentskills.io/specification), [Anthropic skill -architecture](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), -[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Compression requires semantic and empirical checks - -The Pragmatic Programmer defines DRY as keeping each piece of knowledge in one -authoritative representation. This supports removing duplicated meanings while -allowing deliberate reuse of a compact canonical term. Anthropic's authoring -guidance recommends evaluation before and after skill changes, including tests -for triggering and instruction compliance. Together they support sentence-level -no-op review followed by context-isolated forward testing. [The Pragmatic -Programmer, DRY chapter](https://media.pragprog.com/titles/tpp20/dry.pdf), -[Anthropic authoring guidance](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) - -### Leading words remain an evidence-tested heuristic - -Kojima et al. show that a short canonical phrase can substantially change model -behaviour in a bounded reasoning setting. It is an inference—not a demonstrated -universal law—that established methodology names reliably recruit equivalent -pretraining across agent tasks. Propulsion should therefore use canonical terms -to avoid restated explanations, then forward-test whether the finished wording -changes behaviour. [Kojima et al., “Large Language Models are Zero-Shot -Reasoners”](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) - -## Conflicts - -The [Matt Pocock -exemplar](https://github.com/mattpocock/skills/tree/main/skills/productivity/writing-great-skills) -treats predictability as the root virtue and allows skills made entirely from -reference, while Propulsion requires a common H1, introduction, and `## Process` -spine. [Obra's writing-skills -workflow](https://github.com/obra/superpowers/tree/main/skills/writing-skills) -makes baseline-first testing central and carries more process inline; -Anthropic's guidance favours concise core instructions, conditional references, -and evaluation-driven iteration. These are design differences rather than -factual conflicts. Propulsion adopts the fixed outer spine, conditional runtime -depth, and final forward testing confirmed by the user. - -## Limitations - -No primary evidence establishes an optimal leading-word vocabulary, bolding -frequency, body length, or reference granularity across Propulsion's target -models. Those choices require representative forward tests. Ousterhout's public -lecture notes establish **Design it twice** as a published practice but do not -reproduce the book chapter's full argument. - -## Method - -The investigation compared the current Propulsion bundle and vocabulary, Matt -Pocock's local `writing-great-skills` bundle, the public Propulsion, Matt Pocock, -and Obra exemplars, and current Agent Skills guidance. Secondary programming-book -roundups were treated only as discovery aids. Material claims were traced to -original authors, official specifications, first-party documentation, or -published research; competing structures were tested against the confirmed use -cases and context constraints on 2026-07-15. - -## Primary sources - -- [Creating Minimalist Instruction](https://scholarworks.iu.edu/journals/index.php/ijdl/article/view/12887) — John M. Carroll, 2014, accessed 2026-07-15; minimalist instructional design. -- [Use-Case Foundation](https://alistaircockburn.com/Use%20Case%20Foundation.pdf) — Ivar Jacobson and Alistair Cockburn, version 1.1, accessed 2026-07-15; goals, scenarios, extensions, and progressive detail. -- [Discussion of A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/cs190-winter21/lecture.php?topic=bookReview) — John Ousterhout, Stanford CS 190, 2021, accessed 2026-07-15; Design it twice. -- [EWD 803](https://www.cs.utexas.edu/~EWD/transcriptions/EWD08xx/EWD803/EWD803.html) — Edsger W. Dijkstra, accessed 2026-07-15; separation of concerns. -- [Agent Skills specification](https://agentskills.io/specification) — Agent Skills, accessed 2026-07-15; bundle and resource contract. -- [Equipping agents for the real world with Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) — Anthropic, accessed 2026-07-15; progressive-disclosure architecture. -- [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) — Anthropic, accessed 2026-07-15; concise instructions and evaluation. -- [The Pragmatic Programmer: DRY](https://media.pragprog.com/titles/tpp20/dry.pdf) — David Thomas and Andrew Hunt, accessed 2026-07-15; single authoritative representations. -- [Large Language Models are Zero-Shot Reasoners](https://papers.neurips.cc/paper_files/paper/2022/hash/8bb0d291acd4acf06ef112099c16f326-Abstract-Conference.html) — Kojima et al., NeurIPS 2022, accessed 2026-07-15; behavioural effect of a compact canonical phrase. diff --git a/docs/research/20260715-product-definition-method.md b/docs/research/20260715-product-definition-method.md deleted file mode 100644 index af6d4e5..0000000 --- a/docs/research/20260715-product-definition-method.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -title: 'Product definition method' -createdAt: 2026-07-15 -updatedAt: 2026-07-15 -status: current ---- - -# Product definition method - -## Research question and scope - -**Question:** Which established methods should govern a skill that elicits and -documents a new or existing product's purpose, users, needs, differentiation, -strategic features, goals, evidence, and uncertainty without becoming a -roadmap or implementation plan? - -**Intended use:** Support the confirmed `define-product` skill, its reusable -`PRODUCT.md` template, and its conditional discovery reference. - -**Scope:** User-led discovery, static repository evidence, product vision and -strategy, value propositions, strategic feature traceability, and early product -risk. Customer interviews, experiments, roadmap sequencing, feature-level -requirements, delivery planning, and architecture design are excluded. - -## Conclusion - -The **Product Vision Board** is the strongest governing methodology because it -captures an enduring vision and a compact product strategy through target -groups, needs, standout capabilities, and business goals. It applies to new -products and material changes to existing ones while explicitly keeping a -detailed backlog outside the strategy. - -Use three supporting techniques for distinct gaps: the **Value Proposition -Canvas** when user needs and product value are vague; **Impact Mapping** to -trace feature concepts from goals through actors and behaviour change; and the -four product risks to expose uncertainty about value, usability, feasibility, -and viability. Repository archaeology supplies evidence of an existing -product's current behaviour but cannot establish product intent without user -confirmation. - -A reusable `PRODUCT.md` asset and a conditional technique reference are -justified. The asset stabilises the repeated output contract; the reference -keeps branch-specific discovery prompts out of the main skill and avoids -duplicating the elicitation and research dependencies. - -## Findings - -### Product Vision Board defines the durable product strategy - -Roman Pichler's Product Vision Board separates the product's overarching -purpose from the strategy chosen to realise it. Its strategy fields cover the -target market and users, their main needs, three to five standout capabilities, -and business goals. Pichler explicitly places detailed features in the product -backlog and describes the board as applicable to both new products and changes -to existing ones -([Product Vision Board](https://www.romanpichler.com/blog/the-product-vision-board/)). - -**Inference:** `PRODUCT.md` should preserve those stable strategic meanings but -may add current-state evidence, boundaries, risks, and open questions required -by this skill's confirmed use cases. Strategic features should remain -coarse-grained and differentiated rather than becoming an exhaustive feature -inventory. - -### Value Proposition Canvas supplies conditional user-value prompts - -Strategyzer's Value Proposition Canvas distinguishes a customer's jobs, pains, -and gains from the products, pain relievers, and gain creators designed to -serve them. It recommends adjusting the value proposition using customer -evidence rather than treating the initial mapping as established fit -([official template](https://www.strategyzer.com/library/the-value-proposition-canvas)). - -**Inference:** jobs, pains, and gains are useful contingent scaffolding when a -user cannot yet articulate needs or differentiation. They should not become -mandatory fields for every product or imply external validation that has not -occurred. - -### Impact Mapping prevents feature lists without strategic causality - -Impact Mapping grows scope through four linked questions: goal, actors, desired -behaviour impacts, and deliverables. Its primary guidance argues that this -trace makes the reasoning behind a feature inspectable and helps discard work -that does not contribute to a critical impact -([Drawing impact maps](https://www.impactmapping.org/drawing.html)). - -**Inference:** every strategic capability in `PRODUCT.md` should trace to an -actor, desired impact, and product or business goal. The skill should preserve -multiple plausible deliverables as hypotheses and stop before prioritising or -sequencing them into a roadmap. - -### Four product risks expose uncertainty without blocking definition - -SVPG distinguishes value risk, usability risk, feasibility risk, and business -viability risk. The taxonomy broadens discovery beyond whether a feature can be -built and makes the product's different uncertainty classes explicit -([The Four Big Risks](https://www.svpg.com/four-big-risks/)). - -**Inference:** the skill should complete a four-risk pass but may finish with -labelled hypotheses and open questions. Requiring every risk to be resolved -would incorrectly turn product definition into a full validation programme. - -### Existing-system evidence and product intent have different authorities - -Source code, tests, routes, public contracts, and operational configuration can -show what an existing system currently does. They cannot establish why the -product should exist or which future direction is intended. - -**Inference:** the existing-product branch should inspect representative -repository evidence before questioning, label it as observed current state, -and ask the user to resolve contradictions with intended direction. Absence -from inspected code remains unknown rather than proof that a capability does -not exist. - -## Conflicts - -The Product Vision Board recommends validated strategy statements, while the -confirmed skill must also support early ideas that cannot yet be validated. -The skill resolves this by preserving the board's dimensions while explicitly -labelling observations, user-confirmed direction, research, hypotheses, and -unknowns. It does not describe hypotheses as validated findings. - -## Limitations - -The method can establish a coherent product definition from repository and -user evidence, but it cannot prove customer demand, usability, technical -feasibility, or business viability without the corresponding research and -experiments. Impact Mapping establishes a causal hypothesis, not proof that a -feature will create the intended impact. - -## Method - -On 2026-07-15, primary descriptions from the method authors and organisations -were compared against the confirmed use cases. Each method was tested for a -distinct responsibility, overlap with composed skills, applicability to new -and existing products, and risk of crossing into roadmap or implementation -planning. The selected stack was falsified against early unvalidated ideas, -existing repositories whose implementation conflicts with intent, vague user -segments, and feature lists without outcome traces. - -## Primary sources - -- [The Product Vision Board](https://www.romanpichler.com/blog/the-product-vision-board/) — Roman Pichler, updated 2025-10-13, accessed 2026-07-15; vision and product-strategy structure. -- [The Value Proposition Canvas](https://www.strategyzer.com/library/the-value-proposition-canvas) — Strategyzer, published 2026-01-28, accessed 2026-07-15; customer jobs, pains, gains, and value mapping. -- [Drawing impact maps](https://www.impactmapping.org/drawing.html) — Impact Mapping, accessed 2026-07-15; goal, actor, impact, and deliverable trace. -- [The Four Big Risks](https://www.svpg.com/four-big-risks/) — Silicon Valley Product Group, published 2017-12-04, accessed 2026-07-15; value, usability, feasibility, and viability risk taxonomy. From 2bb7cad15d45b8ddbaea11a147940f1cc9c812a1 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 19:56:37 +0100 Subject: [PATCH 36/52] style(markdown): keep prose on single lines --- .oxfmtrc.json | 1 + CONTEXT.md | 132 ++++++------------ README.md | 25 ++-- skills/code-review/SKILL.md | 64 ++------- skills/commit/SKILL.md | 35 +---- skills/debug/SKILL.md | 43 +----- skills/debug/references/TECHNIQUES.md | 87 +++++------- skills/define-product/SKILL.md | 48 +------ .../define-product/assets/product-template.md | 31 ++-- skills/define-product/references/DISCOVERY.md | 47 ++----- skills/elicit-with-context/SKILL.md | 7 +- skills/elicit/SKILL.md | 61 ++------ skills/implement/SKILL.md | 28 +--- skills/maintain-agents/SKILL.md | 42 +----- skills/maintain-context/SKILL.md | 48 +------ .../assets/context-template.md | 6 +- skills/pr/SKILL.md | 39 ++---- skills/research/SKILL.md | 59 ++------ .../assets/research-report-template.md | 13 +- skills/review-architecture/SKILL.md | 77 ++-------- .../references/architecture-analysis.md | 112 +++++---------- .../references/report-design.md | 103 ++++---------- skills/tdd/SKILL.md | 47 ++----- skills/write-skill/SKILL.md | 75 ++-------- skills/write-skill/references/CRAFT.md | 54 ++----- skills/write-skill/references/SECTIONS.md | 43 ++---- skills/write-skill/references/TESTING.md | 31 +--- 27 files changed, 316 insertions(+), 1042 deletions(-) diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 398f676..553cf6c 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -2,6 +2,7 @@ "$schema": "./node_modules/oxfmt/configuration_schema.json", "ignorePatterns": ["node_modules/**", ".opencode/node_modules/**"], "printWidth": 80, + "proseWrap": "never", "tabWidth": 4, "singleQuote": true, "sortImports": { diff --git a/CONTEXT.md b/CONTEXT.md index 3f01065..0b7368d 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -4,176 +4,132 @@ Propulsion is an agentic coding workflow composed of skills that steer a coding ## Language -**Predictability**: -The degree to which a skill makes the agent follow the same process on every run, without requiring the same output. +**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. +**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 for skills expected to be invoked often enough that automatic discovery earns its permanent context cost. +**Model-invoked skill**: A skill the agent may select autonomously or invoke from another skill. Use this exception for skills expected to be invoked often enough that automatic discovery earns 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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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 uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates code-review findings until verified and elicits user intent when a finding would change behaviour, contracts, architecture, or scope. +**Implement skill**: The user-invoked workflow that uses tracer bullets to deliver a clear implementation request in verified slices, applying TDD when appropriate. It remediates code-review findings until verified 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. +**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. +**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. +**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. +**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. +**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. +**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 user-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. +**Debug skill**: The user-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. +**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 Product Vision Board workflow that composes contextual elicitation and conditional research to maintain an evidence-aware root `PRODUCT.md` and domain language in `CONTEXT.md`. It defines strategic direction and capabilities without becoming a roadmap or implementation plan. +**Define-product skill**: The user-invoked Product Vision Board workflow that composes contextual elicitation and conditional research to maintain an evidence-aware root `PRODUCT.md` and domain language in `CONTEXT.md`. It defines strategic direction and capabilities without becoming a roadmap or implementation 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. +**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. +**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 workflow that uses evidence synthesis to answer a scoped question from primary sources and writes a cited research report. It delegates source discovery, appraisal, and report writing to a background agent when available so the caller receives only the durable report and concise findings; other skills invoke it only when the evidence warrants that durable record. +**Research skill**: The model-invoked workflow that uses evidence synthesis to answer a scoped question from primary sources and writes a cited research report. It delegates source discovery, appraisal, and report writing to a background agent when available so the caller receives only the durable report and 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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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. +**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/README.md b/README.md index edaac2a..5bc3e80 100644 --- a/README.md +++ b/README.md @@ -18,25 +18,20 @@ Choose the skills and coding agents you want when prompted. ### Local -When developing Propulsion from a local clone, link each skill you want to use -into the shared Agent Skills directory: +When developing Propulsion from a local clone, link each skill you want to use into the shared Agent Skills directory: ```sh mkdir -p ~/.agents/skills 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. +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 -Propulsion skills are independently invocable. For most feature and change -requests, use this recommended workflow: +Propulsion skills are independently invocable. For most feature and change requests, use this recommended workflow: -1. Shape the idea with `$elicit-with-context` until the request is understood - and confirmed. +1. Shape the idea with `$elicit-with-context` until the request is understood and confirmed. ```text $elicit-with-context Help me work through an idea for <desired outcome>. @@ -48,8 +43,7 @@ requests, use this recommended workflow: $implement the request we just confirmed. ``` -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. +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. 4. Commit the reviewed changes, then create the pull request. @@ -66,18 +60,15 @@ For a bug, start with `$debug` instead of elicitation and implementation: $debug Fix <observed problem>. ``` -After the repair, rejoin the recommended workflow at human review, followed by -`$commit` and `$pr`. +After the repair, rejoin the recommended workflow at human review, followed by `$commit` and `$pr`. -For codebase improvements, start with `$review-architecture` to produce an -architecture report: +For codebase improvements, start with `$review-architecture` to produce an architecture report: ```text $review-architecture Review <scope> for high-value architecture improvements. ``` -Review the report, then take each accepted recommendation through the -recommended workflow separately, beginning with `$elicit-with-context`. +Review the report, then take each accepted recommendation through the recommended workflow separately, beginning with `$elicit-with-context`. ## Acknowledgements diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 9e78866..2742aee 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -8,86 +8,44 @@ disable-model-invocation: false # Code Review -**Google code review** applies the code-health standard to a scoped change. -Separate requirements and code-health passes keep delivery gaps, defects, and -refactor opportunities independently visible. +**Google code review** applies the code-health standard to a scoped change. Separate requirements and code-health passes keep delivery gaps, defects, and refactor opportunities independently visible. ## Process ### 1. Resolve the scope -Resolve the change scope in this order: an explicit caller-supplied scope, -uncommitted tracked and untracked work, then the current branch from its -default-branch merge base. Confirm any revision exists and the change set is -non-empty; report the exact blocker and stop when either check fails, and ask -the user only when multiple scopes remain plausible. Recover requirements -from caller context, a supplied request, specification or ticket, then the -change description and commit history. When none exists, state that there is -no requirements source rather than inventing one. The exact change set and -best available requirements source are explicit. +Resolve the change scope in this order: an explicit caller-supplied scope, uncommitted tracked and untracked work, then the current branch from its default-branch merge base. Confirm any revision exists and the change set is non-empty; report the exact blocker and stop when either check fails, and ask the user only when multiple scopes remain plausible. Recover requirements from caller context, a supplied request, specification or ticket, then the change description and commit history. When none exists, state that there is no requirements source rather than inventing one. The exact change set and best available requirements source are explicit. ### 2. Gather the evidence -Read repository instructions, relevant context and decisions, changed files -in full, nearby tests, and the surrounding code needed to judge effects. Run -non-mutating verification already required by the repository when its result -materially informs the review. The review evidence and applicable standards -are complete. +Read repository instructions, relevant context and decisions, changed files in full, nearby tests, and the surrounding code needed to judge effects. Run non-mutating verification already required by the repository when its result materially informs the review. The review evidence and applicable standards are complete. ### 3. Trace the requirements -Perform a **requirements traceability** pass. Compare the change with every -available requirement and identify missing, partial, incorrect, conflicting, -or unrequested behaviour and relevant unhandled cases. When there is no -requirements source, preserve that limitation instead of treating inferred -intent as a requirement. Requirements candidates are explicit. +Perform a **requirements traceability** pass. Compare the change with every available requirement and identify missing, partial, incorrect, conflicting, or unrequested behaviour and relevant unhandled cases. When there is no requirements source, preserve that limitation instead of treating inferred intent as a requirement. Requirements candidates are explicit. ### 4. Assess code health -Perform an independent code-health pass across correctness, design, -complexity, tests, naming, documentation, security, performance, reliability, -and repository standards where relevant. Apply the **Test Desiderata** to -changed tests, especially behavioural sensitivity, structure insensitivity, -specificity, and determinism. Use **code smells** as a heuristic baseline: -**Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, -**Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, -**Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, -**Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other -established smells when the changed code provides a concrete cue. A smell -becomes a finding only when evidence shows a worthwhile correction. -Code-health candidates are explicit. +Perform an independent code-health pass across correctness, design, complexity, tests, naming, documentation, security, performance, reliability, and repository standards where relevant. Apply the **Test Desiderata** to changed tests, especially behavioural sensitivity, structure insensitivity, specificity, and determinism. Use **code smells** as a heuristic baseline: **Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, **Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, **Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, **Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other established smells when the changed code provides a concrete cue. A smell becomes a finding only when evidence shows a worthwhile correction. Code-health candidates are explicit. ### 5. Validate the candidates -Apply **falsification** to every candidate against the scoped change, full -context, requirements, and repository standards. Run targeted non-mutating -tests, type checks, linting, or other checks when they can settle a claim. -Discard any candidate without a demonstrated consequence. Every remaining -finding is reproducible or directly evidenced. +Apply **falsification** to every candidate against the scoped change, full context, requirements, and repository standards. Run targeted non-mutating tests, type checks, linting, or other checks when they can settle a claim. Discard any candidate without a demonstrated consequence. Every remaining finding is reproducible or directly evidenced. ### 6. Prioritise the findings -Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and -order findings within each from highest to lowest priority. Every reported -finding is actionable. +Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and order findings within each from highest to lowest priority. Every reported finding is actionable. ## Rules - Keep the review read-only and return corrections for the caller to implement. - Report only issues introduced by or materially relevant to the scoped change. - Prefer code evidence and documented standards over personal preference. -- Hold refactor opportunities to the same evidence, consequence, priority, and - correction standard as behavioural findings. +- Hold refactor opportunities to the same evidence, consequence, priority, and correction standard as behavioural findings. ## Handoff -State the exact scope and requirements source, then return `## Requirements` -and `## Code health`. Use `No requirements source.` when applicable and `No -findings.` for a clean axis. Format each finding as: +State the exact scope and requirements source, then return `## Requirements` and `## Code health`. Use `No requirements source.` when applicable and `No findings.` for a clean axis. Format each finding as: ```markdown ### [priority] Concise finding @@ -97,6 +55,4 @@ findings.` for a clean axis. Format each finding as: - Correction: smallest effective change ``` -End with `## Summary`, including the finding count for each axis and any check -that could not run. When no material finding remains, say the scoped change is -clean plainly. +End with `## Summary`, including the finding count for each axis and any check that could not run. When no material finding remains, say the scoped change is clean plainly. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 2b0965c..ef6bb35 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -8,51 +8,30 @@ disable-model-invocation: false # Commit -**Conventional Commits** turns uncommitted work into atomic commits whose -messages state each change's intent. +**Conventional Commits** turns uncommitted work into atomic commits whose messages state each change's intent. ## Process ### 1. Establish authority and scope -Establish commit authority from an explicit user request or authorised -caller. Inspect `git status`, the repository's Git instructions and current -operation, staged, unstaged, and untracked changes, and recent commit messages. -Honour user-supplied scope or message constraints and compatible repository -conventions. When authority is absent or no eligible change remains, report -it and stop without changing Git state. Otherwise the complete candidate diff -and commit context are explicit. +Establish commit authority from an explicit user request or authorised caller. Inspect `git status`, the repository's Git instructions and current operation, staged, unstaged, and untracked changes, and recent commit messages. Honour user-supplied scope or message constraints and compatible repository conventions. When authority is absent or no eligible change remains, report it and stop without changing Git state. Otherwise the complete candidate diff and commit context are explicit. ### 2. Partition coherent concerns -Partition eligible changes by coherent intent using **atomic commits**. -Keep related implementation, tests, and documentation together while -leaving unrelated or ambiguous work uncommitted. Treat a coherent, -independent pre-staged set as the first commit; when it mixes concerns or -belongs with unstaged work, ask the user before altering the staged set. -Each planned commit has one explainable purpose. +Partition eligible changes by coherent intent using **atomic commits**. Keep related implementation, tests, and documentation together while leaving unrelated or ambiguous work uncommitted. Treat a coherent, independent pre-staged set as the first commit; when it mixes concerns or belongs with unstaged work, ask the user before altering the staged set. Each planned commit has one explainable purpose. ### 3. Stage one concern -For each concern, retain an already exact staged selection or use -**interactive staging** at file or hunk granularity to stage exactly that -change, then inspect the complete staged diff. The index represents one -atomic change while unselected work remains intact. +For each concern, retain an already exact staged selection or use **interactive staging** at file or hunk granularity to stage exactly that change, then inspect the complete staged diff. The index represents one atomic change while unselected work remains intact. ### 4. Write the message -Write an accurate Conventional Commit message in the form -`type[(scope)][!]: description` for the staged diff. +Write an accurate Conventional Commit message in the form `type[(scope)][!]: description` for the staged diff. ### 5. Create the commit -Create the commit and allow configured Git hooks to run. On any failure, -treat hook output as authoritative when present, preserve the index and -working tree, and report the exact output and resulting Git state. Obtain -user direction for any repository or user Git configuration change. +Create the commit and allow configured Git hooks to run. On any failure, treat hook output as authoritative when present, preserve the index and working tree, and report the exact output and resulting Git state. Obtain user direction for any repository or user Git configuration change. ### 6. Verify the commits -Verify each created commit against its recorded diff, inspect the remaining -status before continuing, and return each hash and subject plus work left -uncommitted. +Verify each created commit against its recorded diff, inspect the remaining status before continuing, and return each hash and subject plus work left uncommitted. diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 0a72fc3..861863c 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -8,57 +8,26 @@ disable-model-invocation: true # Debug -**Scientific method** turns a repeatable failing signal into a verified causal -repair through falsifiable hypotheses and discriminating experiments. +**Scientific method** turns a repeatable failing signal into a verified causal repair through falsifiable hypotheses and discriminating experiments. ## Process ### 1. Establish a repeatable signal -Read repository instructions and establish the authorised scope, expected -behaviour, observed behaviour, and a repeatable failing signal. Use the -smallest reliable reproduction: a failing test, benchmark, trace, log -pattern, or targeted probe may substitute for a local reproduction when it -distinguishes the fault. When the signal or a later discriminating experiment -is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select -and tighten the smallest applicable one. Preserve pre-existing user work. -When no repeatable signal can be established, leave the implementation -unchanged and report the evidence, blocker, and next discriminating -experiment. The failure and mutation boundary are explicit. +Read repository instructions and establish the authorised scope, expected behaviour, observed behaviour, and a repeatable failing signal. Use the smallest reliable reproduction: a failing test, benchmark, trace, log pattern, or targeted probe may substitute for a local reproduction when it distinguishes the fault. When the signal or a later discriminating experiment is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select and tighten the smallest applicable one. Preserve pre-existing user work. When no repeatable signal can be established, leave the implementation unchanged and report the evidence, blocker, and next discriminating experiment. The failure and mutation boundary are explicit. ### 2. Isolate the root cause -Gather evidence and state falsifiable hypotheses in evidence-supported -order. Run the cheapest experiment that distinguishes the leading -hypotheses, changing one variable at a time and recording the result. Use a -**minimal reproducible example**, **binary search**, or **delta debugging** -when it will narrow the failing input, change, component, or boundary. -Repeat until **root-cause analysis** identifies a cause supported by the -experiments rather than a correlated symptom. The demonstrated cause is -explicit before repair. +Gather evidence and state falsifiable hypotheses in evidence-supported order. Run the cheapest experiment that distinguishes the leading hypotheses, changing one variable at a time and recording the result. Use a **minimal reproducible example**, **binary search**, or **delta debugging** when it will narrow the failing input, change, component, or boundary. Repeat until **root-cause analysis** identifies a cause supported by the experiments rather than a correlated symptom. The demonstrated cause is explicit before repair. ### 3. Repair the cause -When the user explicitly requested diagnosis only, stop before mutation and -follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and -the fault has a stable regression seam. When TDD is not applicable, apply -the smallest correction to the demonstrated cause and use the repeatable -signal as the immediate feedback loop. Keep the repair within the authorised -scope; report a cause that requires external access or expanded authority as -a blocker. The repair is causal, focused, and covered by the strongest -feasible regression protection. +When the user explicitly requested diagnosis only, stop before mutation and follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and the fault has a stable regression seam. When TDD is not applicable, apply the smallest correction to the demonstrated cause and use the repeatable signal as the immediate feedback loop. Keep the repair within the authorised scope; report a cause that requires external access or expanded authority as a blocker. The repair is causal, focused, and covered by the strongest feasible regression protection. ### 4. Verify the repair -Re-run the original reproduction and confirm the expected behaviour, then -run focused regression coverage, relevant nearby checks, and the -repository-prescribed wider checks. Separate unrelated pre-existing failures -from repair regressions. The original fault is repaired and relevant checks -pass, or the exact remaining failure and uncertainty are explicit. +Re-run the original reproduction and confirm the expected behaviour, then run focused regression coverage, relevant nearby checks, and the repository-prescribed wider checks. Separate unrelated pre-existing failures from repair regressions. The original fault is repaired and relevant checks pass, or the exact remaining failure and uncertainty are explicit. ## Handoff -Report the expected and observed behaviour, failing signal, hypotheses and -experiments, root cause, changed files, regression protection, verification -commands and results, and any blocker or unresolved uncertainty. For -diagnosis-only work, state plainly that no implementation was changed. +Report the expected and observed behaviour, failing signal, hypotheses and experiments, root cause, changed files, regression protection, verification commands and results, and any blocker or unresolved uncertainty. For diagnosis-only work, state plainly that no implementation was changed. diff --git a/skills/debug/references/TECHNIQUES.md b/skills/debug/references/TECHNIQUES.md index 87e4e5a..ea5288d 100644 --- a/skills/debug/references/TECHNIQUES.md +++ b/skills/debug/references/TECHNIQUES.md @@ -1,70 +1,51 @@ # Debugging Techniques -Use this reference when the repeatable failing signal or next discriminating -experiment is not obvious. Select the smallest applicable technique; combine -techniques only when each settles a distinct question, then return to the main -workflow. +Use this reference when the repeatable failing signal or next discriminating experiment is not obvious. Select the smallest applicable technique; combine techniques only when each settles a distinct question, then return to the main workflow. ## Tighten the Signal -Run the signal at least once and record its command or probe, input, expected -verdict, and observed verdict. A useful signal is: +Run the signal at least once and record its command or probe, input, 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 - non-deterministic 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. +- **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 non-deterministic 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; compare the -measured failure rate under the same conditions. +A passing retry does not turn an intermittent failure green; compare the measured failure rate under the same conditions. ## 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. | -| The fault requires browser behaviour | Headless browser script | Assert the relevant DOM, console, request, or response outcome; retain the smallest trace or fixture that exposes the symptom. | -| Only a production request or event exposes the fault | Capture and replay | Capture the smallest safe request, event, trace, or payload and replay it at the nearest stable seam; retain correlation and environment context without secrets. | -| 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 | Repetition loop | Run the exact trigger repeatedly, report failures per attempts, and control time, randomness, order, load, and environment one dimension at a time. | -| The fault is concurrent | Controlled schedule or race probe | Prefer a recorded or systematic schedule and repository-supported race tooling. Use stress only to amplify and capture a failure, not to prove its absence. | -| The fault is performance | Benchmark loop | Define a representative workload and failing threshold; warm up, repeat, and report variance before profiling the same workload. | +| 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. | +| The fault requires browser behaviour | Headless browser script | Assert the relevant DOM, console, request, or response outcome; retain the smallest trace or fixture that exposes the symptom. | +| Only a production request or event exposes the fault | Capture and replay | Capture the smallest safe request, event, trace, or payload and replay it at the nearest stable seam; retain correlation and environment context without secrets. | +| 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 | Repetition loop | Run the exact trigger repeatedly, report failures per attempts, and control time, randomness, order, load, and environment one dimension at a time. | +| The fault is concurrent | Controlled schedule or race probe | Prefer a recorded or systematic schedule and repository-supported race tooling. Use stress only to amplify and capture a failure, not to prove its absence. | +| The fault is performance | Benchmark loop | Define a representative workload and failing threshold; warm up, repeat, and report variance before profiling the same workload. | ## 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** | Record hypothesis-relevant input, output, state, configuration, timing, and correlation 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 | Vary one timing, order, load, or scheduling dimension and compare the measured rate. Prefer waiting for observable conditions over guessed delays. | -| A controlled benchmark proves a regression | Profiler, query plan, or resource trace | Identify the work responsible for the measured difference before changing it; remeasure the identical workload after repair. | +| 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** | Record hypothesis-relevant input, output, state, configuration, timing, and correlation 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 | Vary one timing, order, load, or scheduling dimension and compare the measured rate. Prefer waiting for observable conditions over guessed delays. | +| A controlled benchmark proves a regression | Profiler, query plan, or resource trace | Identify the work responsible for the measured difference before changing it; 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. +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. +- 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. diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md index e4f79a1..386f0fe 100644 --- a/skills/define-product/SKILL.md +++ b/skills/define-product/SKILL.md @@ -8,62 +8,26 @@ disable-model-invocation: true # Define Product -The **Product Vision Board** turns a new idea or existing system into a shared, -evidence-aware product definition that guides strategic features without -becoming a delivery plan. +The **Product Vision Board** turns a new idea or existing system into a shared, evidence-aware product definition that guides strategic features without becoming a delivery plan. ## Process ### 1. Inspect the product context -Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions -and research, and the smallest representative repository evidence. Select a -create or improve branch. For an existing product, treat code and tests as -evidence of current behaviour and the user as the authority on intent; -expose contradictions between them. The branch, current evidence, and -definition boundary are explicit. +Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions and research, and the smallest representative repository evidence. Select a create or improve branch. For an existing product, treat code and tests as evidence of current behaviour and the user as the authority on intent; expose contradictions between them. The branch, current evidence, and definition boundary are explicit. ### 2. Elicit shared understanding -Invoke `$elicit-with-context` to reach shared understanding of the vision, -users and customers, needs, product type, value proposition, alternatives, -differentiating capabilities, business goals, success signals, boundaries, -current state, and intended direction. When a dimension is unclear, load -only the relevant section of [Discovery Techniques](references/DISCOVERY.md). -Invoke `$research` when external evidence could materially resolve a product -question or help the user formulate a decision; keep its report authoritative -and link applicable findings. Each product dimension is confirmed, supported, -or explicitly uncertain. +Invoke `$elicit-with-context` to reach shared understanding of the vision, users and customers, needs, product type, value proposition, alternatives, differentiating capabilities, business goals, success signals, boundaries, current state, and intended direction. When a dimension is unclear, load only the relevant section of [Discovery Techniques](references/DISCOVERY.md). Invoke `$research` when external evidence could materially resolve a product question or help the user formulate a decision; keep its report authoritative and link applicable findings. Each product dimension is confirmed, supported, or explicitly uncertain. ### 3. Trace strategic value -Use **Impact Mapping** to trace every strategic capability or feature concept -through an actor and desired behaviour change to a product or business goal. -Apply the product-discovery risks of value, usability, feasibility, and -viability as a completeness pass. Classify product state as `current`, -`confirmed direction`, or `hypothesis`, and evidence as `observed`, -`user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature -ideas without a strategic trace or retain them as explicit open questions. -The definition distinguishes direction from evidence and exposes its risks. +Use **Impact Mapping** to trace every strategic capability or feature concept through an actor and desired behaviour change to a product or business goal. Apply the product-discovery risks of value, usability, feasibility, and viability as a completeness pass. Classify product state as `current`, `confirmed direction`, or `hypothesis`, and evidence as `observed`, `user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature ideas without a strategic trace or retain them as explicit open questions. The definition distinguishes direction from evidence and exposes its risks. ### 4. Write the product definition -At `$elicit-with-context`'s final confirmation, create or update the single -root `PRODUCT.md` from the -[Product Definition Template](assets/product-template.md). Preserve one -authoritative meaning for each statement, use canonical terms from -`CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to -durable evidence. Record high-level capabilities and feature concepts while -leaving sequencing, estimates, tickets, implementation, architecture, and -feature-level acceptance criteria to downstream work. The living product -definition reflects the confirmed contract without overstating certainty. +At `$elicit-with-context`'s final confirmation, create or update the single root `PRODUCT.md` from the [Product Definition Template](assets/product-template.md). Preserve one authoritative meaning for each statement, use canonical terms from `CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to durable evidence. Record high-level capabilities and feature concepts while leaving sequencing, estimates, tickets, implementation, architecture, and feature-level acceptance criteria to downstream work. The living product definition reflects the confirmed contract without overstating certainty. ### 5. Verify the definition -Verify every current-state claim against cited repository evidence, every -direction claim against user confirmation, every strategic feature against -its impact trace, and every material uncertainty against the risk pass. -Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and -research reports. Return changed files, the confirmed current state and -direction, supporting research, and unresolved questions. The user receives -a coherent product guide ready to inform later feature work. +Verify every current-state claim against cited repository evidence, every direction claim against user confirmation, every strategic feature against its impact trace, and every material uncertainty against the risk pass. Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and research reports. Return changed files, the confirmed current state and direction, supporting research, and unresolved questions. The user receives a coherent product guide ready to inform later feature work. diff --git a/skills/define-product/assets/product-template.md b/skills/define-product/assets/product-template.md index 7b8b49c..9e34367 100644 --- a/skills/define-product/assets/product-template.md +++ b/skills/define-product/assets/product-template.md @@ -1,19 +1,14 @@ # {Product name} -{One sentence stating who the product serves, the outcome it enables, and what -makes its approach distinct.} _Evidence: {status and source}._ +{One sentence stating who the product serves, the outcome it enables, and what makes its approach distinct.} _Evidence: {status and source}._ ## Vision -{The product's purpose and positive change, independent of a particular -implementation.} _Evidence: {status and source}._ +{The product's purpose and positive change, independent of a particular implementation.} _Evidence: {status and source}._ ## Current state -{For an existing product, summarise its observed purpose, users, capability -groups, lifecycle stage, and material constraints. Cite representative -repository evidence. Omit this section for a new product without a current -state.} +{For an existing product, summarise its observed purpose, users, capability groups, lifecycle stage, and material constraints. Cite representative repository evidence. Omit this section for a new product without a current state.} ## Users and needs @@ -23,26 +18,23 @@ state.} ## Value proposition and differentiation -{State why each primary user would choose this product over current -alternatives, including non-consumption or manual work. Keep differentiators -specific and few.} _Evidence: {status and source}._ +{State why each primary user would choose this product over current alternatives, including non-consumption or manual work. Keep differentiators specific and few.} _Evidence: {status and source}._ ## Strategic capabilities -| State | Capability or feature concept | Actor | Desired impact | Product or business goal | Evidence | -| --------------------------------------------- | ----------------------------- | ------- | ----------------------------- | ------------------------ | ------------------- | -| {current, confirmed direction, or hypothesis} | {High-level capability} | {Actor} | {Behaviour change or outcome} | {Goal} | {Status and source} | +| State | Capability or feature concept | Actor | Desired impact | Product or business goal | Evidence | +| --- | --- | --- | --- | --- | --- | +| {current, confirmed direction, or hypothesis} | {High-level capability} | {Actor} | {Behaviour change or outcome} | {Goal} | {Status and source} | ## Business goals and success signals -| Goal | Observable success signal | Evidence | -| ------------------------------------- | ------------------------------ | ------------------- | +| Goal | Observable success signal | Evidence | +| --- | --- | --- | | {Desired product or business outcome} | {Measure or observable change} | {Status and source} | ## Boundaries and non-goals -- {A durable product boundary and why it focuses the definition.} _Evidence: - {status and source}._ +- {A durable product boundary and why it focuses the definition.} _Evidence: {status and source}._ ## Risks and evidence @@ -59,5 +51,4 @@ specific and few.} _Evidence: {status and source}._ ## Evidence -- [{Repository artifact or research report}]({relative path}) — {Claim or - decision it supports.} +- [{Repository artifact or research report}]({relative path}) — {Claim or decision it supports.} diff --git a/skills/define-product/references/DISCOVERY.md b/skills/define-product/references/DISCOVERY.md index a916965..6e665f9 100644 --- a/skills/define-product/references/DISCOVERY.md +++ b/skills/define-product/references/DISCOVERY.md @@ -1,23 +1,14 @@ # Discovery Techniques -Load only the technique needed by the active elicitation branch. These methods -support product-specific discovery; `$elicit-with-context` remains authoritative -for questioning, confirmation, language, and qualifying architecture decisions. +Load only the technique needed by the active elicitation branch. These methods support product-specific discovery; `$elicit-with-context` remains authoritative for questioning, confirmation, language, and qualifying architecture decisions. ## Establish an existing product -Use **repository archaeology** to recover observed behaviour before asking the -user to restate it. Start with root documentation and manifests, then sample -user entry points, routes or commands, public contracts, data boundaries, -tests, and operational configuration. Follow evidence only until the major -actors and capability groups are stable. Treat absence from the repository as -unknown rather than proof, distinguish shipped behaviour from abandoned or -planned code, and present contradictions with stated intent for resolution. +Use **repository archaeology** to recover observed behaviour before asking the user to restate it. Start with root documentation and manifests, then sample user entry points, routes or commands, public contracts, data boundaries, tests, and operational configuration. Follow evidence only until the major actors and capability groups are stable. Treat absence from the repository as unknown rather than proof, distinguish shipped behaviour from abandoned or planned code, and present contradictions with stated intent for resolution. ## Shape the product strategy -Use the **Product Vision Board** in needs-first order after establishing the -vision: +Use the **Product Vision Board** in needs-first order after establishing the vision: 1. State the positive change and enduring purpose. 2. Separate users, customers, and other influential actors. @@ -25,17 +16,11 @@ vision: 4. Describe the product type and the few capabilities that make it stand out. 5. Define the product or business outcomes that justify investment. -For an existing product, distinguish the observed current strategy from the -user's confirmed future strategy instead of blending them. +For an existing product, distinguish the observed current strategy from the user's confirmed future strategy instead of blending them. ## Clarify users and value -When needs or differentiation remain vague, use the **Value Proposition -Canvas** one segment at a time. Ask what the actor is trying to accomplish, -which pains or risks obstruct that outcome, which gains define success, and how -the product relieves the important pains or creates the important gains. Rank -the few that materially influence adoption; preserve unsupported claims as -hypotheses. +When needs or differentiation remain vague, use the **Value Proposition Canvas** one segment at a time. Ask what the actor is trying to accomplish, which pains or risks obstruct that outcome, which gains define success, and how the product relieves the important pains or creates the important gains. Rank the few that materially influence adoption; preserve unsupported claims as hypotheses. ## Trace strategic features @@ -46,17 +31,11 @@ Use **Impact Mapping** to test each high-level capability or feature concept: 3. How: what observable behaviour or outcome should change? 4. What: which capability might cause or enable that impact? -Discard an untraceable feature from the definition or record the missing link -as an open question. Keep multiple plausible capabilities as hypotheses; this -is strategic scope, not a roadmap, backlog, or implementation specification. +Discard an untraceable feature from the definition or record the missing link as an open question. Keep multiple plausible capabilities as hypotheses; this is strategic scope, not a roadmap, backlog, or implementation specification. ## Establish differentiation -Compare the product with the alternatives users employ today, including manual -work and doing nothing. Invoke `$research` when competitor capabilities, -market conditions, standards, regulation, or user evidence would materially -change the conclusion. Retain only differentiators that serve a prioritised -need and can plausibly influence choice; label the remainder as hypotheses. +Compare the product with the alternatives users employ today, including manual work and doing nothing. Invoke `$research` when competitor capabilities, market conditions, standards, regulation, or user evidence would materially change the conclusion. Retain only differentiators that serve a prioritised need and can plausibly influence choice; label the remainder as hypotheses. ## Expose product risk @@ -64,11 +43,7 @@ Test the emerging definition against four product-discovery risks: - **Value**: users or customers may not choose, adopt, or pay for it. - **Usability**: users may not understand or successfully use it. -- **Feasibility**: the product may not be buildable with the available - technology, skills, time, or constraints. -- **Viability**: it may not work for the organisation, operating model, legal - obligations, economics, channels, or brand. - -For each material risk, record the available evidence, the remaining -hypothesis, and the smallest evidence that could resolve it. The definition may -finish with uncertainty when that uncertainty is visible and actionable. +- **Feasibility**: the product may not be buildable with the available technology, skills, time, or constraints. +- **Viability**: it may not work for the organisation, operating model, legal obligations, economics, channels, or brand. + +For each material risk, record the available evidence, the remaining hypothesis, and the smallest evidence that could resolve it. The definition may finish with uncertainty when that uncertainty is visible and actionable. diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index 7a91fe4..01db8ba 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -8,11 +8,8 @@ disable-model-invocation: true # Elicit with Context -Shared understanding stays aligned with durable project language and -qualifying architecture decisions. +Shared understanding stays aligned with durable project language and qualifying architecture decisions. ## Process -Invoke `$elicit`, applying `$maintain-context` throughout. Treat `$elicit`'s -final confirmation as the acceptance boundary for qualifying ADRs, then return -the elicitation state, context changes, and unresolved language or decisions. +Invoke `$elicit`, applying `$maintain-context` throughout. Treat `$elicit`'s final confirmation as the acceptance boundary for qualifying ADRs, then return the elicitation state, context changes, and unresolved language or decisions. diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index 029943c..98fd386 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -8,79 +8,34 @@ disable-model-invocation: false # Elicit -**Requirements elicitation** turns choices into confirmed shared understanding -while the user directs every decision. +**Requirements elicitation** turns choices into confirmed shared understanding while the user directs every decision. ## Process ### 1. Establish the factual basis -Inspect the request, conversation, and task-scoped environment for facts -needed by the current branch. Use accessible read-only sources incrementally -as answers expose new branches. Keep pre-confirmation fact-finding read-only; -when establishing a fact requires a state-changing operation, make that -operation a decision and wait for the user's authorisation. When a material -fact remains unavailable, state the inspected evidence, best-supported -inference, and confidence, then ask one factual verification question. The -current branch has an explicit factual basis. +Inspect the request, conversation, and task-scoped environment for facts needed by the current branch. Use accessible read-only sources incrementally as answers expose new branches. Keep pre-confirmation fact-finding read-only; when establishing a fact requires a state-changing operation, make that operation a decision and wait for the user's authorisation. When a material fact remains unavailable, state the inspected evidence, best-supported inference, and confidence, then ask one factual verification question. The current branch has an explicit factual basis. ### 2. Build the decision tree -Build and continually update an internal, dependency-ordered **decision -tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, -prerequisites, dependencies, constraints, flows, exceptions, permissions, -risks, and success conditions. Treat the active user as the sole decision -authority. Preserve compatible decisions after a redirection, rebuild -affected branches, and select the highest-impact decision whose dependencies -are resolved. One current decision is explicit. +Build and continually update an internal, dependency-ordered **decision tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, prerequisites, dependencies, constraints, flows, exceptions, permissions, risks, and success conditions. Treat the active user as the sole decision authority. Preserve compatible decisions after a redirection, rebuild affected branches, and select the highest-impact decision whose dependencies are resolved. One current decision is explicit. ### 3. Ask one decision -Use **Socratic questioning** to ask exactly one question per turn about one -decision. State the context, recommended answer, concise reasoning, and as -many educated alternatives as help the user think, then ask the decision -once while leaving room for their own answer. Derive recommendations from -the user's confirmed outcome, evidence, project conventions, consequences, -and trade-offs. Treat their choice as authoritative and record a logically -necessary consequence without asking it again. The user confirms the current -decision. +Use **Socratic questioning** to ask exactly one question per turn about one decision. State the context, recommended answer, concise reasoning, and as many educated alternatives as help the user think, then ask the decision once while leaving room for their own answer. Derive recommendations from the user's confirmed outcome, evidence, project conventions, consequences, and trade-offs. Treat their choice as authoritative and record a logically necessary consequence without asking it again. The user confirms the current decision. ### 4. Test the answer -Apply **falsification** to each answer through relevant scenarios, -counterexamples, and edge cases. Ask another question only when testing -exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or -conflicting answer on the current branch and reframe its single point of -uncertainty. Answer the user's requests for context directly, then return to -the same decision. Present a discovered constraint and its consequence as -facts, then reframe the decision around feasible options. The answer is clear -and consistent with the confirmed tree. +Apply **falsification** to each answer through relevant scenarios, counterexamples, and edge cases. Ask another question only when testing exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or conflicting answer on the current branch and reframe its single point of uncertainty. Answer the user's requests for context directly, then return to the same decision. Present a discovered constraint and its consequence as facts, then reframe the decision around feasible options. The answer is clear and consistent with the confirmed tree. ### 5. Scaffold the decision -Use **contingent scaffolding** when the user has difficulty deciding. Adapt -the form and clarity of support through plain-language restatement, -alternatives and trade-offs, examples, or scenarios. When useful, replace a -complex decision with its highest-impact prerequisite decisions, resolve -them one at a time, and recombine them. The user reaches and confirms the -decision. +Use **contingent scaffolding** when the user has difficulty deciding. Adapt the form and clarity of support through plain-language restatement, alternatives and trade-offs, examples, or scenarios. When useful, replace a complex decision with its highest-impact prerequisite decisions, resolve them one at a time, and recombine them. The user reaches and confirms the decision. ### 6. Reach theoretical saturation -Continue until **theoretical saturation**: every relevant dimension has been -assessed, every discovered choice has a confirmed answer, dependencies and -answers are consistent, and a final scenario-and-edge-case pass reveals no -new material branch. Present one concise, self-contained synthesis of the -outcome, boundaries, key decisions, constraints, and observable success -conditions, then ask for explicit confirmation. Shared understanding is -ready for confirmation. +Continue until **theoretical saturation**: every relevant dimension has been assessed, every discovered choice has a confirmed answer, dependencies and answers are consistent, and a final scenario-and-edge-case pass reveals no new material branch. Present one concise, self-contained synthesis of the outcome, boundaries, key decisions, constraints, and observable success conditions, then ask for explicit confirmation. Shared understanding is ready for confirmation. ### 7. Complete or redirect -When the user corrects or rejects the synthesis, rebuild the affected -branches and continue from step 2 until saturation returns. An affirmative -confirmation completes the contract and authorises the already-requested -downstream outcome. A pause returns a concise checkpoint of confirmed -decisions and the active decision; a cancellation acknowledges the user's -direction and ends without a synthesis or handoff. The caller receives only -the handoff the user selected. +When the user corrects or rejects the synthesis, rebuild the affected branches and continue from step 2 until saturation returns. An affirmative confirmation completes the contract and authorises the already-requested downstream outcome. A pause returns a concise checkpoint of confirmed decisions and the active decision; a cancellation acknowledges the user's direction and ends without a synthesis or handoff. The caller receives only the handoff the user selected. diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index ca554f5..0e4cb18 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -8,42 +8,26 @@ disable-model-invocation: true # Implement -**Tracer bullets** deliver the smallest end-to-end slice and use its feedback to -aim the next one. `$tdd` builds applicable behaviour; `$code-review` assesses -the completed implementation independently. +**Tracer bullets** deliver the smallest end-to-end slice and use its feedback to aim the next one. `$tdd` builds applicable behaviour; `$code-review` assesses the completed implementation independently. ## Process ### 1. Deliver a verified slice -Deliver the smallest end-to-end slice that advances the request. Invoke -`$tdd` when its prerequisite applies; otherwise implement directly with the -best available targeted verification. Repeat until every requested behaviour -and acceptance condition is implemented. +Deliver the smallest end-to-end slice that advances the request. Invoke `$tdd` when its prerequisite applies; otherwise implement directly with the best available targeted verification. Repeat until every requested behaviour and acceptance condition is implemented. ### 2. Review and remediate -Invoke `$code-review` with the confirmed request and exact implementation -scope. Address every in-scope finding in priority order, invoking `$tdd` for -applicable behavioural corrections. Invoke `$elicit` when a correction would -materially change agreed behaviour, a public contract, architecture, or -authorised scope. Re-run relevant verification and `$code-review` until its -latest report has no unresolved in-scope findings. +Invoke `$code-review` with the confirmed request and exact implementation scope. Address every in-scope finding in priority order, invoking `$tdd` for applicable behavioural corrections. Invoke `$elicit` when a correction would materially change agreed behaviour, a public contract, architecture, or authorised scope. Re-run relevant verification and `$code-review` until its latest report has no unresolved in-scope findings. ### 3. Run the final checks -Run the repository's prescribed final checks without modifying pre-existing -out-of-scope changes. Isolate a mutating check when needed; when that cannot -be done safely, leave it unrun and report the blocker. Available checks pass, -or the exact blocker and any unrelated pre-existing failure are reported -without claiming full verification. +Run the repository's prescribed final checks without modifying pre-existing out-of-scope changes. Isolate a mutating check when needed; when that cannot be done safely, leave it unrun and report the blocker. Available checks pass, or the exact blocker and any unrelated pre-existing failure are reported without claiming full verification. ## Rules -- Preserve pre-existing user changes and keep implementation, review, and - remediation scoped to the current request. +- Preserve pre-existing user changes and keep implementation, review, and remediation scoped to the current request. ## Handoff -Report the implemented behaviour and changed files, `$tdd` applicability, -verification and review evidence, and any unresolved blocker or uncertainty. +Report the implemented behaviour and changed files, `$tdd` applicability, verification and review evidence, and any unresolved blocker or uncertainty. diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md index 186823c..1e36fdf 100644 --- a/skills/maintain-agents/SKILL.md +++ b/skills/maintain-agents/SKILL.md @@ -8,56 +8,26 @@ disable-model-invocation: true # Maintain AGENTS.md -**Lossless compression** turns repository-wide constraints into the smallest -durable instruction surface an agent needs before reading the code. +**Lossless compression** turns repository-wide constraints into the smallest durable instruction surface an agent needs before reading the code. ## Process ### 1. Inspect the instruction surface -Locate the repository root and inspect the root `AGENTS.md`, applicable -instruction layers, and task-relevant repository evidence. Read manifests, -task-runner configuration, CI, and contributor documentation only far enough -to identify the canonical project harness and recover the intent of existing -guidance. The target file, active instruction chain, and candidate harness -are explicit. +Locate the repository root and inspect the root `AGENTS.md`, applicable instruction layers, and task-relevant repository evidence. Read manifests, task-runner configuration, CI, and contributor documentation only far enough to identify the canonical project harness and recover the intent of existing guidance. The target file, active instruction chain, and candidate harness are explicit. ### 2. Classify the instructions -Classify every existing and proposed instruction. Keep only succinct -project-wide behaviour that applies across tasks and cannot be reliably -inferred from the relevant code, configuration, or documentation, plus a -canonical command whose selection prevents ambiguous verification. Remove -stale guidance, rationale, boilerplate, repository description, duplicated -enforcement, personal preferences, and task-specific workflows. Report each -useful displaced instruction with its smallest appropriate destination, such -as an existing skill, a scoped instruction file, or executable enforcement; -leave those destinations unchanged. Every retained instruction earns its -permanent context cost. +Classify every existing and proposed instruction. Keep only succinct project-wide behaviour that applies across tasks and cannot be reliably inferred from the relevant code, configuration, or documentation, plus a canonical command whose selection prevents ambiguous verification. Remove stale guidance, rationale, boilerplate, repository description, duplicated enforcement, personal preferences, and task-specific workflows. Report each useful displaced instruction with its smallest appropriate destination, such as an existing skill, a scoped instruction file, or executable enforcement; leave those destinations unchanged. Every retained instruction earns its permanent context cost. ### 3. Establish the required guidance -Ensure the file states: `When the user corrects you with a reusable, -project-wide rule, ask whether to update AGENTS.md.` Inspect available check -entry points and select one safe aggregate harness that represents completed -work. When alternatives materially differ or a candidate has external side -effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the -check instruction rather than inventing one. The correction feedback loop -and, when available, one canonical completion check are explicit. +Ensure the file states: `When the user corrects you with a reusable, project-wide rule, ask whether to update AGENTS.md.` Inspect available check entry points and select one safe aggregate harness that represents completed work. When alternatives materially differ or a candidate has external side effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the check instruction rather than inventing one. The correction feedback loop and, when available, one canonical completion check are explicit. ### 4. Write the root instructions -Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, -merge overlapping meanings, remove headings that add no navigation, and -apply lossless compression until every word changes agent behaviour or -preserves a necessary condition. The file contains one authoritative -expression of each retained rule. +Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, merge overlapping meanings, remove headings that add no navigation, and apply lossless compression until every word changes agent behaviour or preserves a necessary condition. The file contains one authoritative expression of each retained rule. ### 5. Verify and hand off -Re-read every line against its repository-wide scope and runtime value. -Verify the selected harness exists and run it when it is safe and applicable. -Return the changed file, harness result or limitation, removed instructions -with destinations, and any unresolved conflict in the active instruction -chain. The user receives a thin verified root instruction file and a visible -account of displaced guidance. +Re-read every line against its repository-wide scope and runtime value. Verify the selected harness exists and run it when it is safe and applicable. Return the changed file, harness result or limitation, removed instructions with destinations, and any unresolved conflict in the active instruction chain. The user receives a thin verified root instruction file and a visible account of displaced guidance. diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 46ce193..223d91b 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -8,34 +8,17 @@ disable-model-invocation: false # Maintain Context -**Ubiquitous language** keeps project terms rigorous through everyday use and -refinement; concise architecture decision records preserve the consequential -choices that shape the codebase. +**Ubiquitous language** keeps project terms rigorous through everyday use and refinement; concise architecture decision records preserve the consequential choices that shape the codebase. ## Process ### 1. Resolve project language -Compare domain language in the conversation with the root `CONTEXT.md` and -relevant code. Challenge vague, overloaded, or conflicting terms, propose -one precise canonical term, and test it with concrete scenarios and edge -cases. Treat code as evidence of current behaviour and the user's confirmed -answer as intent; surface contradictions for resolution. Reuse a compatible -convention and obtain agreement before moving or reshaping conflicting -durable records. The term is either validated with the user or remains -explicitly unresolved. +Compare domain language in the conversation with the root `CONTEXT.md` and relevant code. Challenge vague, overloaded, or conflicting terms, propose one precise canonical term, and test it with concrete scenarios and edge cases. Treat code as evidence of current behaviour and the user's confirmed answer as intent; surface contradictions for resolution. Reuse a compatible convention and obtain agreement before moving or reshaping conflicting durable records. The term is either validated with the user or remains explicitly unresolved. ### 2. Maintain the glossary -As soon as a term is validated and agreed, create or update the single root -`CONTEXT.md` using the [context template](assets/context-template.md). Keep -definitions to one or two sentences, add `_Avoid_` only for aliases or -ambiguous alternatives that actually occur, and group terms under descriptive -subheadings when natural clusters emerge; keep a flat list when all terms form -one cohesive area. Define domain meaning rather than implementation, -specifications, or general programming concepts. Give each domain meaning one -authoritative entry and link supporting material from it. The glossary -reflects each resolved term before the discussion continues. +As soon as a term is validated and agreed, create or update the single root `CONTEXT.md` using the [context template](assets/context-template.md). Keep definitions to one or two sentences, add `_Avoid_` only for aliases or ambiguous alternatives that actually occur, and group terms under descriptive subheadings when natural clusters emerge; keep a flat list when all terms form one cohesive area. Define domain meaning rather than implementation, specifications, or general programming concepts. Give each domain meaning one authoritative entry and link supporting material from it. The glossary reflects each resolved term before the discussion continues. ### 3. Test the ADR gates @@ -45,33 +28,16 @@ Test an accepted codebase decision against all three ADR gates: - a future reader would find it surprising without context; and - viable alternatives created a genuine trade-off. -Offer an ADR only when all three gates pass. The decision is either rejected -as routine or identified as a qualifying architectural decision. +Offer an ADR only when all three gates pass. The decision is either rejected as routine or identified as a qualifying architectural decision. ### 4. Record a qualifying decision -After a qualifying decision is accepted, 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 the file -`NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision -first, then only the context and significant ramifications needed to explain -it. Give each architectural decision one authoritative ADR. Require only -`Decision`, `Context`, and `Ramifications` as content sections, in that order; -reserve frontmatter for `status` and conditional supersession links. Link -supporting material from that record. The new ADR is brief, accepted, -sequentially numbered, and readable from its filename. +After a qualifying decision is accepted, 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 the file `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision first, then only the context and significant ramifications needed to explain it. Give each architectural decision one authoritative ADR. Require only `Decision`, `Context`, and `Ramifications` as content sections, in that order; reserve frontmatter for `status` and conditional supersession links. Link supporting material from that record. The new ADR is brief, accepted, sequentially numbered, and readable from its filename. ### 5. Supersede a changed decision -When an accepted decision changes, read only the specific ADR it supersedes, -preserve that record, and create a new one. Set the old record's `status` to -`superseded` with a relative `superseded-by` link, and give the new record a -relative `supersedes` link; leave the old decision, context, and ramifications -unchanged. Both records expose the decision history in both directions. +When an accepted decision changes, read only the specific ADR it supersedes, preserve that record, and create a new one. Set the old record's `status` to `superseded` with a relative `superseded-by` link, and give the new record a relative `supersedes` link; leave the old decision, context, and ramifications unchanged. Both records expose the decision history in both directions. ### 6. Verify and hand off -Re-read every changed artifact against the resolved language, accepted -decisions, and relevant code evidence, then report the files changed and any -unresolved contradiction. The handoff identifies a consistent durable -record or names the exact uncertainty that prevented one. +Re-read every changed artifact against the resolved language, accepted decisions, and relevant code evidence, then report the files changed and any unresolved contradiction. The handoff identifies a consistent durable record or names the exact uncertainty that prevented one. diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md index 4bb0d39..78c101f 100644 --- a/skills/maintain-context/assets/context-template.md +++ b/skills/maintain-context/assets/context-template.md @@ -1,10 +1,8 @@ # {Project Name} Context -{Describe the project domain and why this language exists in one or two -sentences.} +{Describe the project domain and why this language exists in one or two sentences.} ## Language -**{Canonical term}**: -{Define what the term is in one or two sentences.} +**{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/pr/SKILL.md b/skills/pr/SKILL.md index 289da12..31dacc8 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -8,57 +8,34 @@ disable-model-invocation: true # Pull Request -**GitHub flow** publishes the current branch as a concise, ready-for-review pull -request. Invoke `$commit` when eligible uncommitted work exists; it remains -authoritative for commit selection, staging, and messages. +**GitHub flow** publishes the current branch as a concise, ready-for-review pull request. Invoke `$commit` when eligible uncommitted work exists; it remains authoritative for commit selection, staging, and messages. ## Prerequisites -A GitHub remote, authenticated push and pull-request access, an attached branch, -and a distinct base branch are required. Use the user-supplied base or the -remote's default branch. Report the missing condition and stop when a -prerequisite cannot be resolved. +A GitHub remote, authenticated push and pull-request access, an attached branch, and a distinct base branch are required. Use the user-supplied base or the remote's default branch. Report the missing condition and stop when a prerequisite cannot be resolved. ## Process ### 1. Inspect the publication context -Inspect repository instructions and pull-request templates, Git status and -current operation, the current branch, GitHub remotes, authentication, the -selected base, and any existing pull request for the branch. The publication -context and applicable repository requirements are explicit before mutation. +Inspect repository instructions and pull-request templates, Git status and current operation, the current branch, GitHub remotes, authentication, the selected base, and any existing pull request for the branch. The publication context and applicable repository requirements are explicit before mutation. ### 2. Commit eligible work -Invoke `$commit` when eligible uncommitted work exists. Continue with its -reported commits and intentionally excluded work visible. +Invoke `$commit` when eligible uncommitted work exists. Continue with its reported commits and intentionally excluded work visible. ### 3. Establish the pull-request scope -Fetch the selected remote base, find its merge base with `HEAD`, and inspect -the complete commit history and diff from that point. Stop when the branch -has no publishable diff; otherwise the full pull-request scope is explicit. +Fetch the selected remote base, find its merge base with `HEAD`, and inspect the complete commit history and diff from that point. Stop when the branch has no publishable diff; otherwise the full pull-request scope is explicit. ### 4. Write the pull request -Derive an accurate Conventional Commit title in the form -`type[(scope)][!]: description` for the complete diff. Populate every required -repository-template section; without a required template, write one short -**BLUF** paragraph explaining what changed and why. The title and body -represent the complete branch rather than one commit. +Derive an accurate Conventional Commit title in the form `type[(scope)][!]: description` for the complete diff. Populate every required repository-template section; without a required template, write one short **BLUF** paragraph explaining what changed and why. The title and body represent the complete branch rather than one commit. ### 5. Publish the branch -Push the current branch without rewriting remote history and create a ready -pull request against the selected base, or a draft only when the user -explicitly requested one. When an open pull request already represents the -branch, reuse it and reconcile its base, title, body, and ready or draft state -with the selected publication context. The remote branch and one -corresponding pull request exist with the requested metadata and state. +Push the current branch without rewriting remote history and create a ready pull request against the selected base, or a draft only when the user explicitly requested one. When an open pull request already represents the branch, reuse it and reconcile its base, title, body, and ready or draft state with the selected publication context. The remote branch and one corresponding pull request exist with the requested metadata and state. ### 6. Verify the pull request -Verify the pull request's head, base, draft state, title, and body against the -inspected scope and repository requirements. Return its URL and report any -failed publication or verification with the resulting local and remote -state. +Verify the pull request's head, base, draft state, title, and body against the inspected scope and repository requirements. Return its URL and report any failed publication or verification with the resulting local and remote state. diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 43e8f52..5deebe7 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -8,77 +8,34 @@ disable-model-invocation: false # Research -**Evidence synthesis** turns a scoped question into a reproducible repository -report whose material claims trace to primary sources. +**Evidence synthesis** turns a scoped question into a reproducible repository report whose material claims trace to primary sources. ## Process ### 1. Define the research contract -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 any ambiguity -that could materially change the investigation; the research contract and -applicable prior evidence are explicit. +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 any ambiguity that could materially change the investigation; the research contract and applicable prior evidence are explicit. ### 2. Assign the investigation -When the host supports background agents, delegate source discovery, -appraisal, synthesis, and report writing with the complete research -contract, relevant repository context, primary-source standard, and output -contract. Continue only independent caller work while it runs, then validate -its result. Perform the workflow inline when delegation is unavailable or -fails, and repair an invalid delegated result before handoff. One researcher -owns the investigation and report at a time. +When the host supports background agents, delegate source discovery, appraisal, synthesis, and report writing with the complete research contract, relevant repository context, primary-source standard, and output contract. Continue only independent caller work while it runs, then validate its result. Perform the workflow inline when delegation is unavailable or fails, and repair an invalid delegated result before handoff. One researcher owns the investigation and report at a time. ### 3. Discover primary evidence -Discover the strongest applicable primary evidence, including official -documentation, source code, standards, original publications, first-party -APIs, or first-party data. Use secondary sources only to locate originals. -Apply **source criticism** to authority, proximity, currency, applicability, -and stability; use **citation chaining** to reach the evidence behind -material claims. The evidence set is relevant, current enough for the -question, and traceable. +Discover the strongest applicable primary evidence, including official documentation, source code, standards, original publications, first-party APIs, or first-party data. Use secondary sources only to locate originals. Apply **source criticism** to authority, proximity, currency, applicability, and stability; use **citation chaining** to reach the evidence behind material claims. The evidence set is relevant, current enough for the question, and traceable. ### 4. Synthesize the findings -Compare independent evidence through **triangulation** and test emerging -conclusions through **falsification**. 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. +Compare independent evidence through **triangulation** and test emerging conclusions through **falsification**. 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. ### 5. Write the research report -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 the primary -evidence. Replace every placeholder and retain only applicable lifecycle -fields. Complete every applicable template section and record enough method -and source detail for **reproducibility**, but omit the raw search trail. When -a distinct report already occupies the same dated path, append `-2` to the -filename slug and increment it until available without changing the -frontmatter title or H1. +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 the primary evidence. Replace every placeholder and retain only applicable lifecycle fields. Complete every applicable template section and record enough method and source detail for **reproducibility**, but omit the raw search trail. When a distinct report already occupies the same dated path, append `-2` to the filename slug and increment it until available without changing the frontmatter title or H1. ### 6. Preserve provenance -Preserve **provenance** when related research already exists. Apply a minor -correction in place only when it repairs wording, formatting, or the link to -the same evidence without changing a material claim; retain `createdAt` and -change `updatedAt`. New evidence, changed scope, or a materially changed -finding creates a new dated snapshot with `supersedes`; mark the previous -snapshot `superseded` and add its relative `supersededBy` link without -rewriting its historical findings. The report history distinguishes -correction from substantive refresh. +Preserve **provenance** when related research already exists. Apply a minor correction in place only when it repairs wording, formatting, or the link to the same evidence without changing a material claim; retain `createdAt` and change `updatedAt`. New evidence, changed scope, or a materially changed finding creates a new dated snapshot with `supersedes`; mark the previous snapshot `superseded` and add its relative `supersededBy` link without rewriting its historical findings. The report history distinguishes correction from substantive refresh. ### 7. Verify and hand off -Verify that each material claim is supported by its cited primary source, -every link and relative report path resolves, conflicts and uncertainty are -visible, and the recorded method can reproduce the investigation. 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. +Verify that each material claim is supported by its cited primary source, every link and relative report path resolves, conflicts and uncertainty are visible, and the recorded method can reproduce the investigation. 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. diff --git a/skills/research/assets/research-report-template.md b/skills/research/assets/research-report-template.md index a999322..354d2d6 100644 --- a/skills/research/assets/research-report-template.md +++ b/skills/research/assets/research-report-template.md @@ -16,8 +16,7 @@ status: current **Intended use:** {The decision or caller this evidence informs} -**Scope:** {Included and excluded concerns, applicable versions or environments, -and evidence currency} +**Scope:** {Included and excluded concerns, applicable versions or environments, and evidence currency} ## Conclusion @@ -27,8 +26,7 @@ and evidence currency} ### {Finding} -{Material claims with direct links to supporting primary sources. Identify -inferences explicitly.} +{Material claims with direct links to supporting primary sources. Identify inferences explicitly.} ## Conflicts @@ -40,11 +38,8 @@ inferences explicitly.} ## Method -{How sources were discovered, appraised, compared, and falsified; include the -research date and any reproducibility constraints without retaining the raw -search trail.} +{How sources were discovered, appraised, compared, and falsified; include the research date and any reproducibility constraints without retaining the raw search trail.} ## Primary sources -- [{Source title}]({URL or repository-relative path}) — {publisher or owner, - version or publication date, accessed YYYY-MM-DD, and relevance} +- [{Source title}]({URL or repository-relative path}) — {publisher or owner, version or publication date, accessed YYYY-MM-DD, and relevance} diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index 8e9c5bd..147527f 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -8,101 +8,46 @@ disable-model-invocation: true # Review Architecture -**Information hiding** turns codebase evidence into modular redesigns whose -small, stable contracts hide cohesive implementation and change-prone decisions. +**Information hiding** turns codebase evidence into modular redesigns whose small, stable contracts hide cohesive implementation and change-prone decisions. ## Process ### 1. Establish the review scope -Establish the review scope. Use the user's explicit scope or the whole -repository with the slug `full-codebase`. Convert an explicit scope to a -concise lowercase hyphenated slug. Inspect project context, architecture -decisions, source, tests, contracts, schemas, dependencies, build and -deployment configuration, and documentation. Exclude generated output, -vendored dependencies, caches, and binaries from detailed analysis unless -they participate in a material boundary. The inspected scope and exclusions -are explicit. +Establish the review scope. Use the user's explicit scope or the whole repository with the slug `full-codebase`. Convert an explicit scope to a concise lowercase hyphenated slug. Inspect project context, architecture decisions, source, tests, contracts, schemas, dependencies, build and deployment configuration, and documentation. Exclude generated output, vendored dependencies, caches, and binaries from detailed analysis unless they participate in a material boundary. The inspected scope and exclusions are explicit. ### 2. Recover the quality drivers -Recover quality drivers from explicit project evidence, then apply the -priority order in [Architecture Analysis](references/architecture-analysis.md). -Distinguish confirmed drivers from inference. Ask the user only when an -unknown priority could materially change which redesigns qualify or how they -rank. The review has an evidence-backed quality hierarchy. +Recover quality drivers from explicit project evidence, then apply the priority order in [Architecture Analysis](references/architecture-analysis.md). Distinguish confirmed drivers from inference. Ask the user only when an unknown priority could materially change which redesigns qualify or how they rank. The review has an evidence-backed quality hierarchy. ### 3. Map the architecture -Use the reference's diagnostics to map cohesive capabilities, public -contracts, hidden decisions, dependency direction, adapters, seams, runtime -boundaries, verification, and change propagation. Treat a module as a -capability with a contract, not as a directory, file, class, or service. -Record repository-relative paths and precise locations for material -evidence. The current architecture and its material pressures are traceable. +Use the reference's diagnostics to map cohesive capabilities, public contracts, hidden decisions, dependency direction, adapters, seams, runtime boundaries, verification, and change propagation. Treat a module as a capability with a contract, not as a directory, file, class, or service. Record repository-relative paths and precise locations for material evidence. The current architecture and its material pressures are traceable. ### 4. Design each candidate twice -Apply **design it twice** to every serious candidate. Compare at least two -materially different boundaries, including their contracts, hidden -decisions, dependency direction, quality effects, trade-offs, and migration -seams. Use principles and patterns from the reference only when their -conditions fit the evidence. Discard rearrangements, new layers, and -fashionable patterns that do not materially improve a priority quality. Each -candidate has a tested alternative and a codebase-specific rationale. +Apply **design it twice** to every serious candidate. Compare at least two materially different boundaries, including their contracts, hidden decisions, dependency direction, quality effects, trade-offs, and migration seams. Use principles and patterns from the reference only when their conditions fit the evidence. Discard rearrangements, new layers, and fashionable patterns that do not materially improve a priority quality. Each candidate has a tested alternative and a codebase-specific rationale. ### 5. Research material external claims -Invoke `$research` when a candidate materially depends on an external -framework, language, platform, or architecture claim that warrants durable -verification. Use the resulting report as evidence and link it from the -architecture report without duplicating its source catalogue. Repository -evidence remains sufficient when no material external claim exists. +Invoke `$research` when a candidate materially depends on an external framework, language, platform, or architecture claim that warrants durable verification. Use the resulting report as evidence and link it from the architecture report without duplicating its source catalogue. Repository evidence remains sufficient when no material external claim exists. ### 6. Evaluate and rank the candidates -Evaluate candidates with explained `high`, `medium`, or `low` impact, -effort, risk, and confidence labels; do not calculate a composite score. -Retain every redesign that clears the reference's high-value threshold, -whether none or many, and rank retained recommendations through the quality -hierarchy and evidence. Record reviewed areas without a qualifying redesign -as concise coverage rather than low-value findings. The result contains no -quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. +Evaluate candidates with explained `high`, `medium`, or `low` impact, effort, risk, and confidence labels; do not calculate a composite score. Retain every redesign that clears the reference's high-value threshold, whether none or many, and rank retained recommendations through the quality hierarchy and evidence. Record reviewed areas without a qualifying redesign as concise coverage rather than low-value findings. The result contains no quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. ### 7. Define the recommendations -For each recommendation, define the evidenced problem, affected modules and -contracts, target boundary, rejected alternative, expected quality -improvements, framework fit, costs, risks, dependencies, incremental stages, -containment or rollback route, smallest useful first slice, and observable -architecture fitness checks. Stop before changing implementation or -producing a file-by-file implementation plan. Every recommendation is -independently understandable, actionable, and verifiable. +For each recommendation, define the evidenced problem, affected modules and contracts, target boundary, rejected alternative, expected quality improvements, framework fit, costs, risks, dependencies, incremental stages, containment or rollback route, smallest useful first slice, and observable architecture fitness checks. Stop before changing implementation or producing a file-by-file implementation plan. Every recommendation is independently understandable, actionable, and verifiable. ### 8. Create the report -Read [Report Design](references/report-design.md), then create one single-file -interactive HTML report at -`docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an -existing path by adding `-2`, `-3`, and so on before `.html` unless the user -explicitly requests replacement. Generate the overview, comparison, -diagrams, progressive detail, evidence, coverage, and research links from -the completed analysis. The artifact follows the report contract and no -existing report is unintentionally overwritten. +Read [Report Design](references/report-design.md), then create one single-file interactive HTML report at `docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an existing path by adding `-2`, `-3`, and so on before `.html` unless the user explicitly requests replacement. Generate the overview, comparison, diagrams, progressive detail, evidence, coverage, and research links from the completed analysis. The artifact follows the report contract and no existing report is unintentionally overwritten. ### 9. Validate the report -Validate the HTML structure and inspect the report in an available browser -at desktop and narrow widths. Verify loaded scripts and styles, diagrams, -filters, pointer and keyboard operation, visible focus, collapsed and -expanded states, overflow, and print output. Correct every material content, -interaction, accessibility, or layout defect. When browser inspection is -unavailable, complete structural checks and mark visual acceptance as -incomplete. The report is either visually accepted or carries an explicit -verification limitation. +Validate the HTML structure and inspect the report in an available browser at desktop and narrow widths. Verify loaded scripts and styles, diagrams, filters, pointer and keyboard operation, visible focus, collapsed and expanded states, overflow, and print output. Correct every material content, interaction, accessibility, or layout defect. When browser inspection is unavailable, complete structural checks and mark visual acceptance as incomplete. The report is either visually accepted or carries an explicit verification limitation. ## Handoff -Return the report path, scope and exclusions, recommendation count, invoked -research reports, validation performed, and unresolved evidence or visual-QA -limitations. Preserve the reviewed implementation unchanged. +Return the report path, scope and exclusions, recommendation count, invoked research reports, validation performed, and unresolved evidence or visual-QA limitations. Preserve the reviewed implementation unchanged. diff --git a/skills/review-architecture/references/architecture-analysis.md b/skills/review-architecture/references/architecture-analysis.md index dab0302..d186cf5 100644 --- a/skills/review-architecture/references/architecture-analysis.md +++ b/skills/review-architecture/references/architecture-analysis.md @@ -1,8 +1,6 @@ # Architecture Analysis -Load this reference while mapping, comparing, and ranking architecture -redesigns. It supplies diagnostics and decision criteria; `SKILL.md` owns the -workflow and report boundary. +Load this reference while mapping, comparing, and ranking architecture redesigns. It supplies diagnostics and decision criteria; `SKILL.md` owns the workflow and report boundary. ## Quality Priority @@ -13,16 +11,9 @@ Apply the first applicable evidence in this order: 3. Information hiding and change isolation. 4. Cohesion, coupling, and interface depth. 5. Testability and migration safety. -6. Operability, reliability, performance, scalability, and portability when - evidenced by the system. +6. Operability, reliability, performance, scalability, and portability when evidenced by the system. -Explicit project evidence overrides the baseline. Recover it 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 concrete scenario: stimulus, affected -capability or boundary, expected response, and observable measure. Label an -inferred driver and its confidence. Ask the user when competing designs depend -on an unknown priority that the repository cannot establish. +Explicit project evidence overrides the baseline. Recover it 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 concrete scenario: stimulus, affected capability or boundary, expected response, and observable measure. Label an inferred driver and its confidence. Ask the user when competing designs depend on an unknown priority that the repository cannot establish. ## Architecture Map @@ -37,35 +28,29 @@ Map capabilities before proposing structure: - runtime flows for important quality scenarios; - repeated changes that cross boundaries or force coordinated edits. -Do not infer an architectural boundary from a directory, namespace, class, -package, service, or deployment unit alone. One architecture module may contain -several internal actions, and one directory may mix several capabilities. +Do not infer an architectural boundary from a directory, namespace, class, package, service, or deployment unit alone. One architecture module may contain several internal actions, and one directory may mix several capabilities. ## Diagnostics Use these as questions, not as a pattern checklist. -| Signal | Test | Redesign direction | Guardrail | -| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -| Information leakage | Which consumers know a representation, ordering rule, protocol, framework type, or policy that belongs elsewhere? | Gather the knowledge behind one explicit contract. | Moving the same leaked fact to a new helper is not hiding it. | -| Shallow or pass-through interface | Does the interface expose nearly as much complexity as its implementation or repeat another layer's API? | Pull cohesive complexity behind a smaller contract or remove the redundant boundary. | A small function is not automatically a shallow architecture module. | -| Temporal decomposition | Are modules organised by processing steps although the underlying decisions change together? | Group by owned knowledge or capability rather than execution order. | Preserve genuinely independent pipeline stages. | -| Weak cohesion | Do unrelated actors, policies, or change reasons force edits to the same module? | Separate the knowledge that changes for different reasons. | Do not split cohesive internal actions merely to make files smaller. | -| Harmful coupling | Does a change propagate through consumers, create cycles, rely on shared mutable data, or reverse intended policy direction? | Narrow the contract, move ownership, introduce a seam, or invert the volatile dependency. | Coupling is necessary; remove knowledge and coordination, not all connection. | -| Missing seam | Can behaviour be verified or replaced only through the full runtime stack? | Expose the smallest purposeful contract at the volatile boundary. | Do not create interfaces without a verification, replacement, or migration need. | -| Framework leakage | Does domain or application policy depend on transport, persistence, UI, or vendor types? | Translate at an adapter and keep the capability contract in its own language. | Framework conventions may be the correct boundary for framework-owned code. | -| Duplicated policy | Is one rule reimplemented across entry points, services, jobs, or clients? | Give one cohesive module ownership and make callers depend on its contract. | Similar syntax is not necessarily the same policy. | -| Runtime boundary mismatch | Do process, transaction, data ownership, failure, or deployment boundaries cut through a supposedly atomic capability? | Align the contract and migration plan with actual consistency and failure constraints. | Do not force distribution when an in-process boundary is sufficient. | - -Trace every material signal to repository-relative paths and precise locations. -Separate observed facts, conclusions supported by several observations, and -uncertainty. Metrics may locate candidates, but they do not prove a redesign. +| Signal | Test | Redesign direction | Guardrail | +| --- | --- | --- | --- | +| Information leakage | Which consumers know a representation, ordering rule, protocol, framework type, or policy that belongs elsewhere? | Gather the knowledge behind one explicit contract. | Moving the same leaked fact to a new helper is not hiding it. | +| Shallow or pass-through interface | Does the interface expose nearly as much complexity as its implementation or repeat another layer's API? | Pull cohesive complexity behind a smaller contract or remove the redundant boundary. | A small function is not automatically a shallow architecture module. | +| Temporal decomposition | Are modules organised by processing steps although the underlying decisions change together? | Group by owned knowledge or capability rather than execution order. | Preserve genuinely independent pipeline stages. | +| Weak cohesion | Do unrelated actors, policies, or change reasons force edits to the same module? | Separate the knowledge that changes for different reasons. | Do not split cohesive internal actions merely to make files smaller. | +| Harmful coupling | Does a change propagate through consumers, create cycles, rely on shared mutable data, or reverse intended policy direction? | Narrow the contract, move ownership, introduce a seam, or invert the volatile dependency. | Coupling is necessary; remove knowledge and coordination, not all connection. | +| Missing seam | Can behaviour be verified or replaced only through the full runtime stack? | Expose the smallest purposeful contract at the volatile boundary. | Do not create interfaces without a verification, replacement, or migration need. | +| Framework leakage | Does domain or application policy depend on transport, persistence, UI, or vendor types? | Translate at an adapter and keep the capability contract in its own language. | Framework conventions may be the correct boundary for framework-owned code. | +| Duplicated policy | Is one rule reimplemented across entry points, services, jobs, or clients? | Give one cohesive module ownership and make callers depend on its contract. | Similar syntax is not necessarily the same policy. | +| Runtime boundary mismatch | Do process, transaction, data ownership, failure, or deployment boundaries cut through a supposedly atomic capability? | Align the contract and migration plan with actual consistency and failure constraints. | Do not force distribution when an in-process boundary is sufficient. | + +Trace every material signal to repository-relative paths and precise locations. Separate observed facts, conclusions supported by several observations, and uncertainty. Metrics may locate candidates, but they do not prove a redesign. ## Design It Twice -For every serious candidate, compare at least two materially different designs. -A variation in naming, file placement, or interface syntax is not a second -design. For each alternative state: +For every serious candidate, compare at least two materially different designs. A variation in naming, file placement, or interface syntax is not a second design. For each alternative state: - the capability boundary and public contract; - the knowledge and volatile decisions hidden inside it; @@ -75,66 +60,46 @@ design. For each alternative state: - migration seam, first useful slice, and containment route; - new complexity, risks, and decisions it creates. -Prefer the design that hides more relevant knowledge behind the simpler stable -contract while satisfying the higher-priority quality evidence. Reject an -alternative explicitly; do not present the first plausible design as inevitable. +Prefer the design that hides more relevant knowledge behind the simpler stable contract while satisfying the higher-priority quality evidence. Reject an alternative explicitly; do not present the first plausible design as inevitable. ## Conditional Concepts Use a concept only under its condition: -| Concept | Use when | Avoid when | -| --------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| Deep module | A cohesive capability can hide substantial knowledge behind a small stable interface. | The boundary merely combines unrelated work or grows an equally complex interface. | -| Single responsibility | Different actors or change reasons are entangled in one boundary. | A cohesive capability has several internal implementation steps. | -| Dependency inversion | Stable policy depends directly on a volatile mechanism and a purposeful contract can reverse that knowledge dependency. | The abstraction has one accidental consumer and hides no meaningful volatility. | -| Ports and adapters | A purposeful application conversation needs multiple technologies, isolated verification, or replacement. | It would wrap every framework call or create ports without alternate adapters or isolation value. | -| Seam | Verification, replacement, observation, or incremental migration needs a controlled boundary. | Direct use is already stable, observable, and local. | -| Strangler fig | A high-risk boundary must be replaced gradually while old behaviour remains live. | A safe local replacement can be completed and verified atomically. | -| Fitness function | A quality claim can be guarded by an objective repeatable signal. | The proposed measure is a subjective proxy unrelated to the claimed improvement. | +| Concept | Use when | Avoid when | +| --- | --- | --- | +| Deep module | A cohesive capability can hide substantial knowledge behind a small stable interface. | The boundary merely combines unrelated work or grows an equally complex interface. | +| Single responsibility | Different actors or change reasons are entangled in one boundary. | A cohesive capability has several internal implementation steps. | +| Dependency inversion | Stable policy depends directly on a volatile mechanism and a purposeful contract can reverse that knowledge dependency. | The abstraction has one accidental consumer and hides no meaningful volatility. | +| Ports and adapters | A purposeful application conversation needs multiple technologies, isolated verification, or replacement. | It would wrap every framework call or create ports without alternate adapters or isolation value. | +| Seam | Verification, replacement, observation, or incremental migration needs a controlled boundary. | Direct use is already stable, observable, and local. | +| Strangler fig | A high-risk boundary must be replaced gradually while old behaviour remains live. | A safe local replacement can be completed and verified atomically. | +| Fitness function | A quality claim can be guarded by an objective repeatable signal. | The proposed measure is a subjective proxy unrelated to the claimed improvement. | ## Evaluation Assign each label with a one-sentence evidence-based rationale: -- **Impact** — `high` changes a constraint or explicit driver, or removes a - repeated high-reach pressure; `medium` materially improves a bounded - capability; `low` is marginal or mostly local. -- **Effort** — `high` crosses several boundaries or requires staged data, - contract, or deployment work; `medium` needs multiple 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 or an unverified assumption. - -Do not combine labels into a score. Rank qualifying recommendations by the -quality priority, then the strength and reach of impact, confidence in the -evidence, and migration feasibility and risk. Explain judgment where the order -is not obvious. +- **Impact** — `high` changes a constraint or explicit driver, or removes a repeated high-reach pressure; `medium` materially improves a bounded capability; `low` is marginal or mostly local. +- **Effort** — `high` crosses several boundaries or requires staged data, contract, or deployment work; `medium` needs multiple 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 or an unverified assumption. + +Do not combine labels into a score. Rank qualifying recommendations by the quality priority, then the strength and reach of impact, confidence in the evidence, and migration feasibility and risk. Explain judgment where the order is not obvious. A redesign qualifies only when it: - materially improves at least one priority quality; - traces the problem and expected improvement to repository evidence; -- hides or realigns architectural knowledge rather than performing a local - refactor or cosmetic rearrangement; +- hides or realigns architectural knowledge rather than performing a local refactor or cosmetic rearrangement; - has a credible incremental route with known dependencies and risks; and - is supported strongly enough to recommend, with material uncertainty visible. -Report every qualifying redesign and none below the threshold. Zero is valid; -there is no minimum or maximum. Record non-qualifying areas only in review -coverage. +Report every qualifying redesign and none below the threshold. Zero is valid; there is no minimum or maximum. Record non-qualifying areas only in review coverage. ## Migration and Fitness -For a retained redesign, define stages that keep the system operable and -verifiable. Name prerequisites, the smallest independently useful first slice, -coexistence between old and new boundaries, data or contract transition, -containment or rollback, and removal of the superseded path. Stop before a -file-by-file implementation plan. +For a retained redesign, define stages that keep the system operable and verifiable. Name prerequisites, the smallest independently useful first slice, coexistence between old and new boundaries, data or contract transition, containment or rollback, and removal of the superseded path. Stop before a file-by-file implementation plan. Pair each claimed improvement with observable fitness evidence, such as: @@ -145,5 +110,4 @@ Pair each claimed improvement with observable fitness evidence, such as: - performance, reliability, security, or operability thresholds; - deployment, telemetry, or runtime signals. -State the signal, expected result, and where it should run. Prefer existing -verification when it proves the quality; propose new machinery only when needed. +State the signal, expected result, and where it should run. Prefer existing verification when it proves the quality; propose new machinery only when needed. diff --git a/skills/review-architecture/references/report-design.md b/skills/review-architecture/references/report-design.md index ee11596..17e90fc 100644 --- a/skills/review-architecture/references/report-design.md +++ b/skills/review-architecture/references/report-design.md @@ -1,30 +1,18 @@ # Architecture Review Report Design -Use this reference when generating and visually verifying the architecture -review HTML. The report is a decision tool, not a static audit or a wall of -technical prose. +Use this reference when generating and visually verifying the architecture review HTML. The report is a decision tool, not a static audit or a wall of technical prose. ## Information Architecture Use one HTML document with this reading order: -1. **Header** — title, review date, scope, exclusions, evidence confidence, and - a one-sentence outcome. -2. **Current architecture** — a concise capability and boundary overview with a - diagram only when it improves understanding. -3. **Recommendations** — the complete ranked set as comparable summary cards, - followed by filters and progressive detail. A zero-result state plainly says - that no redesign crossed the evidence threshold. -4. **Review coverage** — areas examined without a qualifying redesign and any - evidence limitations. -5. **Method and sources** — repository evidence conventions, invoked research - reports, generation time, and visual-verification status. - -The initial viewport should explain the result and expose the ranked -recommendations without requiring detailed reading. Preserve the ranking as the -default view. When several recommendations exist, allow filtering by affected -capability, impact, effort, risk, and confidence; show the visible count and -provide a clear reset. +1. **Header** — title, review date, scope, exclusions, evidence confidence, and a one-sentence outcome. +2. **Current architecture** — a concise capability and boundary overview with a diagram only when it improves understanding. +3. **Recommendations** — the complete ranked set as comparable summary cards, followed by filters and progressive detail. A zero-result state plainly says that no redesign crossed the evidence threshold. +4. **Review coverage** — areas examined without a qualifying redesign and any evidence limitations. +5. **Method and sources** — repository evidence conventions, invoked research reports, generation time, and visual-verification status. + +The initial viewport should explain the result and expose the ranked recommendations without requiring detailed reading. Preserve the ranking as the default view. When several recommendations exist, allow filtering by affected capability, impact, effort, risk, and confidence; show the visible count and provide a clear reset. ## Recommendation Design @@ -50,19 +38,13 @@ Its expanded detail contains: - fitness checks with expected results; - links to any durable research report. -Use plain language in summaries and retain exact technical names in evidence. -Do not hide a recommendation's main cost, risk, or uncertainty inside the -expanded content. +Use plain language in summaries and retain exact technical names in evidence. Do not hide a recommendation's main cost, risk, or uncertainty inside the expanded content. ## Visual and Interaction Language -Use strong hierarchy, generous spacing, readable line lengths, restrained -colour, and consistent cards and labels. Paths, symbols, and contracts may use a -monospace face. Use colour to reinforce meaning, never to carry it alone. Avoid -decoration that competes with comparison or implies unsupported precision. +Use strong hierarchy, generous spacing, readable line lengths, restrained colour, and consistent cards and labels. Paths, symbols, and contracts may use a monospace face. Use colour to reinforce meaning, never to carry it alone. Avoid decoration that competes with comparison or implies unsupported precision. -Scripts, styles, fonts, and diagram libraries may load from CDNs when they help -the current report. Tailwind and Mermaid are suitable defaults: +Scripts, styles, fonts, and diagram libraries may load from CDNs when they help the current report. Tailwind and Mermaid are suitable defaults: ```html <script src="https://cdn.tailwindcss.com"></script> @@ -76,66 +58,39 @@ the current report. Tailwind and Mermaid are suitable defaults: </script> ``` -The artifact is a single generated HTML file whose markup and behaviour remain -together; verified CDN dependencies may provide scripts, styles, fonts, and -diagram libraries. It need not work offline or preserve CDN compatibility -indefinitely. Verify every selected dependency in the rendered report at -generation time. Escape repository-derived text before placing it in HTML, -attributes, scripts, or diagram definitions. +The artifact is a single generated HTML file whose markup and behaviour remain together; verified CDN dependencies may provide scripts, styles, fonts, and diagram libraries. It need not work offline or preserve CDN compatibility indefinitely. Verify every selected dependency in the rendered report at generation time. Escape repository-derived text before placing it in HTML, attributes, scripts, or diagram definitions. -Prefer semantic HTML controls and disclosure elements. Filters update results -immediately, preserve an obvious current state, and remain operable without a -pointer. Avoid interactions whose only purpose is visual novelty. +Prefer semantic HTML controls and disclosure elements. Filters update results immediately, preserve an obvious current state, and remain operable without a pointer. Avoid interactions whose only purpose is visual novelty. ## Diagrams -Use a diagram when boundaries, dependency direction, runtime flow, or migration -stages are materially clearer visually. Choose the smallest fitting form: +Use a diagram when boundaries, dependency direction, runtime flow, or migration stages are materially clearer visually. Choose the smallest fitting form: - a dependency or boundary graph for current and target modules; - a flow or sequence for a quality scenario; - a before-and-after comparison for changed ownership; - a staged flow for incremental migration. -Give each diagram one question to answer. Keep nodes few, labels short, arrows -directional, and current and target semantics consistent. Place a concise text -explanation beside it, label the relationship in prose, and do not rely on -colour alone. Avoid ornamental system maps and unreadable whole-repository -graphs. +Give each diagram one question to answer. Keep nodes few, labels short, arrows directional, and current and target semantics consistent. Place a concise text explanation beside it, label the relationship in prose, and do not rely on colour alone. Avoid ornamental system maps and unreadable whole-repository graphs. ## Accessibility and Layout -- Use semantic landmarks, ordered headings, labelled controls, buttons for - actions, and native disclosure where practical. -- Make every interaction keyboard-operable with a visible focus indicator and - logical focus order. -- Maintain readable text and non-text contrast and pair colour with words, - shapes, or symbols. -- Give tables headers, diagrams accessible names and adjacent explanations, and - icon-only controls accessible labels. -- Reflow cards, filters, diagrams, and evidence at narrow widths without hiding - content or requiring page-level horizontal scrolling. -- Provide print styles that expand recommendation detail, remove interactive - chrome, preserve diagrams and evidence, and avoid splitting short cards - unnecessarily. +- Use semantic landmarks, ordered headings, labelled controls, buttons for actions, and native disclosure where practical. +- Make every interaction keyboard-operable with a visible focus indicator and logical focus order. +- Maintain readable text and non-text contrast and pair colour with words, shapes, or symbols. +- Give tables headers, diagrams accessible names and adjacent explanations, and icon-only controls accessible labels. +- Reflow cards, filters, diagrams, and evidence at narrow widths without hiding content or requiring page-level horizontal scrolling. +- Provide print styles that expand recommendation detail, remove interactive chrome, preserve diagrams and evidence, and avoid splitting short cards unnecessarily. ## Visual QA Inspect the actual file rather than inferring appearance from source: -1. Open it with network access and confirm every external script, style, font, - and diagram dependency loads without a material error. -2. Check the overview, the report's actual zero-or-many recommendation state, - filters, reset, and every collapsed and expanded state. -3. Exercise controls with pointer and keyboard; verify focus visibility, order, - labels, and no keyboard trap. -4. Inspect desktop and narrow viewports for hierarchy, wrapping, overflow, - diagram readability, and content order. -5. Check that labels and diagrams remain understandable without colour and that - evidence paths are legible. -6. Inspect print preview for expanded detail, clipping, missing diagrams, and - wasteful page breaks. - -Correct material defects and rerun affected checks. If browser inspection is -unavailable, validate document structure and scripts as far as the environment -allows, then mark visual acceptance incomplete in both the report and handoff. +1. Open it with network access and confirm every external script, style, font, and diagram dependency loads without a material error. +2. Check the overview, the report's actual zero-or-many recommendation state, filters, reset, and every collapsed and expanded state. +3. Exercise controls with pointer and keyboard; verify focus visibility, order, labels, and no keyboard trap. +4. Inspect desktop and narrow viewports for hierarchy, wrapping, overflow, diagram readability, and content order. +5. Check that labels and diagrams remain understandable without colour and that evidence paths are legible. +6. Inspect print preview for expanded detail, clipping, missing diagrams, and wasteful page breaks. + +Correct material defects and rerun affected checks. If browser inspection is unavailable, validate document structure and scripts as far as the environment allows, then mark visual acceptance incomplete in both the report and handoff. diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 42d2fc4..78a7d55 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -8,65 +8,34 @@ disable-model-invocation: false # Test-Driven Development -**Test-driven development** builds one observable behaviour at a time through -red-green-refactor. Use **Classicist TDD** to test stable public seams with real -internal collaborators, introducing doubles mainly at uncontrollable boundaries. +**Test-driven development** builds one observable behaviour at a time through red-green-refactor. Use **Classicist TDD** to test stable public seams with real internal collaborators, introducing doubles mainly at uncontrollable boundaries. ## Prerequisite -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. +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. ## Process ### 1. Establish the baseline -Read repository instructions, identify the relevant test command, and run the -existing suite to establish a known baseline. Separate unrelated existing -failures from the change, then select the smallest observable behaviour. The -baseline, test seam, and next behaviour are explicit. +Read repository instructions, identify the relevant test command, and run the existing suite to establish a known baseline. Separate unrelated existing failures from the change, then select the smallest observable behaviour. The baseline, test seam, and next behaviour are explicit. ### 2. Red -Use **Arrange-Act-Assert** to add one focused test through a stable -public interface. For a bug, reproduce the incorrect behaviour; adopt an -already-failing regression test only when it independently specifies the -desired behaviour. Run the test and confirm that it fails for the expected -behavioural reason rather than a test defect or environment error. When it -does not, remain in Red: correct an in-scope test defect or report an -environment blocker, then rerun until the expected failure is observed. -Meaningful red evidence is recorded before Green begins. +Use **Arrange-Act-Assert** to add one focused test through a stable public interface. For a bug, reproduce the incorrect behaviour; adopt an already-failing regression test only when it independently specifies the desired behaviour. Run the test and confirm that it fails for the expected behavioural reason rather than a test defect or environment error. When it does not, remain in Red: correct an in-scope test defect or report an environment blocker, then rerun until the expected failure is observed. Meaningful red evidence is recorded before Green begins. ### 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 hiding baseline failures. +Implement only enough production code to satisfy the behaviour, then run the focused test and relevant nearby tests. The new behaviour passes without hiding baseline failures. ### 4. Refactor -Improve the test and production code while keeping behaviour -fixed. Run the focused tests after each material change until the design is -clear and green. The cycle ends with no refactor regression. +Improve the test and production code while keeping behaviour fixed. Run the focused tests after each material change until the design is clear and green. The cycle ends with no refactor regression. ### 5. Complete the cycles -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. +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. ## Test Quality -Apply the **Test Desiderata** to retain tests that are isolated, composable, -fast, inspiring, writable, readable, behavioural, structure-insensitive, -automated, specific, deterministic, and predictive. Retained tests remain -unchanged when production code is refactored without changing observable -behaviour; when structure alone breaks a test, move its assertions to the public -outcome. Prefer assertions on public outcomes over CSS classes, incidental DOM -shape, private methods, internal call sequences, broad snapshots, or -coverage-only cases. +Apply the **Test Desiderata** to retain tests that are isolated, composable, fast, inspiring, writable, readable, behavioural, structure-insensitive, automated, specific, deterministic, and predictive. Retained tests remain unchanged when production code is refactored without changing observable behaviour; when structure alone breaks a test, move its assertions to the public outcome. Prefer assertions on public outcomes over CSS classes, incidental DOM shape, private methods, internal call sequences, broad snapshots, or coverage-only cases. diff --git a/skills/write-skill/SKILL.md b/skills/write-skill/SKILL.md index 2c1fe80..f6f1c34 100644 --- a/skills/write-skill/SKILL.md +++ b/skills/write-skill/SKILL.md @@ -8,99 +8,46 @@ disable-model-invocation: true # Write Skill -**Minimalist instruction** turns confirmed behaviours into the smallest skill -bundle that reliably teaches them. +**Minimalist instruction** turns confirmed behaviours into the smallest skill bundle that reliably teaches them. ## Process ### 1. Establish the behavioural 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, 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. ### 2. Compare governing methodologies -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. +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. ### 3. Select supporting concepts -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. +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. ### 4. Confirm the design -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. +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. ### 5. Write the bundle -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. +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. ### 6. Separate the concerns -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. +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. ### 7. Compress the language -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. +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. ### 8. Validate the mechanics -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. +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. ### 9. Forward-test the behaviour -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. +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. ### 10. Report the result -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. +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. diff --git a/skills/write-skill/references/CRAFT.md b/skills/write-skill/references/CRAFT.md index 9aa73ae..d55e740 100644 --- a/skills/write-skill/references/CRAFT.md +++ b/skills/write-skill/references/CRAFT.md @@ -1,12 +1,10 @@ # Skill Craft -Use this reference when a methodology, supporting concept, section boundary, -leading word, or disclosure decision remains unclear. +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: +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; @@ -14,64 +12,34 @@ familiarity. Use **design it twice** to compare credible candidates through: - 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. +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. +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. +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. +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. +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. +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. +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. +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. +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 55003a8..7d3ac9f 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -1,57 +1,42 @@ # Skill Sections -Use this reference when invocation metadata, optional sections, or bundled -resource placement needs more detail than the fixed skill spine. +Use this reference when invocation metadata, optional sections, or bundled resource placement needs more detail than the fixed skill spine. ## Frontmatter Include the skill's discovery and invocation contract: -- `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. +- `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. -Use user invocation by default. Use model invocation when composition or broad -reuse earns the permanent description context. +Use user invocation by default. Use model invocation when composition or broad reuse earns 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. +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. +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. +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: +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. +- `## 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. +Rename or combine optional sections when that improves the confirmed behaviour. Every optional section earns its place through clearer execution. ## Bundled resources @@ -62,8 +47,4 @@ Use **progressive disclosure** as an information hierarchy: - 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. +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. diff --git a/skills/write-skill/references/TESTING.md b/skills/write-skill/references/TESTING.md index 3e78691..263937e 100644 --- a/skills/write-skill/references/TESTING.md +++ b/skills/write-skill/references/TESTING.md @@ -1,21 +1,14 @@ # Forward Testing -Use this reference when scenario selection, context isolation, or observable -pass evidence needs more detail than the main success scenario. +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. +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: +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; @@ -23,24 +16,14 @@ smallest scenario for a retained material exception when it distinguishes: - 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. +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. +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. +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. +Stop when every confirmed scenario passes or reducing the remaining variance would change the confirmed contract. Report unresolved variance plainly. From 4ed8fa0bf866e5e56c803f1341343287d7718971 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 21:11:20 +0100 Subject: [PATCH 37/52] feat(elicit): enforce exhaustive decision resolution --- skills/elicit/SKILL.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/skills/elicit/SKILL.md b/skills/elicit/SKILL.md index 98fd386..515dcaa 100644 --- a/skills/elicit/SKILL.md +++ b/skills/elicit/SKILL.md @@ -8,34 +8,34 @@ disable-model-invocation: false # Elicit -**Requirements elicitation** turns choices into confirmed shared understanding while the user directs every decision. +**Goal-oriented requirements engineering** refines a request into user-confirmed decisions until every branch reaches shared understanding. ## Process -### 1. Establish the factual basis +### 1. Establish the root goal -Inspect the request, conversation, and task-scoped environment for facts needed by the current branch. Use accessible read-only sources incrementally as answers expose new branches. Keep pre-confirmation fact-finding read-only; when establishing a fact requires a state-changing operation, make that operation a decision and wait for the user's authorisation. When a material fact remains unavailable, state the inspected evidence, best-supported inference, and confidence, then ask one factual verification question. The current branch has an explicit factual 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. -### 2. Build the decision tree +### 2. Refine the decision tree -Build and continually update an internal, dependency-ordered **decision tree**. Assess the relevant outcome, scope, terminology, inputs, outputs, prerequisites, dependencies, constraints, flows, exceptions, permissions, risks, and success conditions. Treat the active user as the sole decision authority. Preserve compatible decisions after a redirection, rebuild affected branches, and select the highest-impact decision whose dependencies are resolved. One current decision is explicit. +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. -### 3. Ask one decision +### 3. Ask one issue -Use **Socratic questioning** to ask exactly one question per turn about one decision. State the context, recommended answer, concise reasoning, and as many educated alternatives as help the user think, then ask the decision once while leaving room for their own answer. Derive recommendations from the user's confirmed outcome, evidence, project conventions, consequences, and trade-offs. Treat their choice as authoritative and record a logically necessary consequence without asking it again. The user confirms the current decision. +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. -### 4. Test the answer +### 4. Scaffold an answer -Apply **falsification** to each answer through relevant scenarios, counterexamples, and edge cases. Ask another question only when testing exposes a choice, contradiction, or boundary. Keep an ambiguous, partial, or conflicting answer on the current branch and reframe its single point of uncertainty. Answer the user's requests for context directly, then return to the same decision. Present a discovered constraint and its consequence as facts, then reframe the decision around feasible options. The answer is clear and consistent with the confirmed tree. +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. -### 5. Scaffold the decision +### 5. Validate the answer -Use **contingent scaffolding** when the user has difficulty deciding. Adapt the form and clarity of support through plain-language restatement, alternatives and trade-offs, examples, or scenarios. When useful, replace a complex decision with its highest-impact prerequisite decisions, resolve them one at a time, and recombine them. The user reaches and confirms the decision. +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. ### 6. Reach theoretical saturation -Continue until **theoretical saturation**: every relevant dimension has been assessed, every discovered choice has a confirmed answer, dependencies and answers are consistent, and a final scenario-and-edge-case pass reveals no new material branch. Present one concise, self-contained synthesis of the outcome, boundaries, key decisions, constraints, and observable success conditions, then ask for explicit confirmation. Shared understanding is ready for confirmation. +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. Complete or redirect +### 7. Confirm shared understanding -When the user corrects or rejects the synthesis, rebuild the affected branches and continue from step 2 until saturation returns. An affirmative confirmation completes the contract and authorises the already-requested downstream outcome. A pause returns a concise checkpoint of confirmed decisions and the active decision; a cancellation acknowledges the user's direction and ends without a synthesis or handoff. The caller receives only the handoff the user selected. +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. From ba8730f077108a89602437eb1cb900881162bcaa Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 21:20:34 +0100 Subject: [PATCH 38/52] Skills --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 7092f6e..fe21d4d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,4 @@ .DS_Store .idea /node_modules -/docs/propulsion \ No newline at end of file +/docs \ No newline at end of file From 06fef0827018f17efaf55bc73f4959e81c44c3cc Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 22:01:27 +0100 Subject: [PATCH 39/52] refactor(research): sharpen primary-source workflow --- CONTEXT.md | 2 +- skills/research/SKILL.md | 24 ++++++++----------- .../assets/research-report-template.md | 2 +- .../research/references/REPORT-LIFECYCLE.md | 15 ++++++++++++ 4 files changed, 27 insertions(+), 16 deletions(-) create mode 100644 skills/research/references/REPORT-LIFECYCLE.md diff --git a/CONTEXT.md b/CONTEXT.md index 0b7368d..5bf01a2 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -74,7 +74,7 @@ _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 workflow that uses evidence synthesis to answer a scoped question from primary sources and writes a cited research report. It delegates source discovery, appraisal, and report writing to a background agent when available so the caller receives only the durable report and concise findings; other skills invoke it only when the evidence warrants that durable record.\ +**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.\ diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 5deebe7..c6c4cfc 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,6 +1,6 @@ --- name: research -description: Investigates questions against primary sources and persists cited findings. Use when research, documentation, API facts, or reading legwork needs a durable report. +description: Researches questions against high-trust primary sources and persists cited reports. Use when a durable evidence-backed answer is needed. metadata: invocation: model disable-model-invocation: false @@ -8,34 +8,30 @@ disable-model-invocation: false # Research -**Evidence synthesis** turns a scoped question into a reproducible repository report whose material claims trace to primary sources. +**Rapid evidence assessment** turns a scoped question into an auditable report grounded in high-trust primary sources. ## Process ### 1. Define the research contract -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 any ambiguity that could materially change the investigation; the research contract and applicable prior evidence are explicit. +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. ### 2. Assign the investigation -When the host supports background agents, delegate source discovery, appraisal, synthesis, and report writing with the complete research contract, relevant repository context, primary-source standard, and output contract. Continue only independent caller work while it runs, then validate its result. Perform the workflow inline when delegation is unavailable or fails, and repair an invalid delegated result before handoff. One researcher owns the investigation and report at a time. +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. -### 3. Discover primary evidence +### 3. Discover and appraise primary evidence -Discover the strongest applicable primary evidence, including official documentation, source code, standards, original publications, first-party APIs, or first-party data. Use secondary sources only to locate originals. Apply **source criticism** to authority, proximity, currency, applicability, and stability; use **citation chaining** to reach the evidence behind material claims. The evidence set is relevant, current enough for the question, and traceable. +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. ### 4. Synthesize the findings -Compare independent evidence through **triangulation** and test emerging conclusions through **falsification**. 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. +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. ### 5. Write the research report -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 the primary evidence. Replace every placeholder and retain only applicable lifecycle fields. Complete every applicable template section and record enough method and source detail for **reproducibility**, but omit the raw search trail. When a distinct report already occupies the same dated path, append `-2` to the filename slug and increment it until available without changing the frontmatter title or H1. +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. -### 6. Preserve provenance +### 6. Verify and hand off -Preserve **provenance** when related research already exists. Apply a minor correction in place only when it repairs wording, formatting, or the link to the same evidence without changing a material claim; retain `createdAt` and change `updatedAt`. New evidence, changed scope, or a materially changed finding creates a new dated snapshot with `supersedes`; mark the previous snapshot `superseded` and add its relative `supersededBy` link without rewriting its historical findings. The report history distinguishes correction from substantive refresh. - -### 7. Verify and hand off - -Verify that each material claim is supported by its cited primary source, every link and relative report path resolves, conflicts and uncertainty are visible, and the recorded method can reproduce the investigation. 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. +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. diff --git a/skills/research/assets/research-report-template.md b/skills/research/assets/research-report-template.md index 354d2d6..8e382bd 100644 --- a/skills/research/assets/research-report-template.md +++ b/skills/research/assets/research-report-template.md @@ -38,7 +38,7 @@ status: current ## Method -{How sources were discovered, appraised, compared, and falsified; include the research date and any reproducibility constraints without retaining the raw search trail.} +{The research date, material search locations, terms or approaches, appraisal basis, triangulation and falsification method, and auditability constraints without the raw search trail.} ## Primary sources diff --git a/skills/research/references/REPORT-LIFECYCLE.md b/skills/research/references/REPORT-LIFECYCLE.md new file mode 100644 index 0000000..c01349d --- /dev/null +++ b/skills/research/references/REPORT-LIFECYCLE.md @@ -0,0 +1,15 @@ +# 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. From 283b00cfe3cfd6df4a66e1990723e7f4640c8353 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Wed, 15 Jul 2026 22:40:53 +0100 Subject: [PATCH 40/52] feat(maintain-context): maintain project language inline --- skills/maintain-context/SKILL.md | 39 +++++++++++-------- .../maintain-context/assets/adr-template.md | 4 -- .../assets/context-template.md | 2 + 3 files changed, 25 insertions(+), 20 deletions(-) diff --git a/skills/maintain-context/SKILL.md b/skills/maintain-context/SKILL.md index 223d91b..658c59e 100644 --- a/skills/maintain-context/SKILL.md +++ b/skills/maintain-context/SKILL.md @@ -1,6 +1,6 @@ --- name: maintain-context -description: Maintains project language and architecture decisions. Use when domain terms or consequential codebase decisions emerge or change. +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 @@ -8,36 +8,43 @@ disable-model-invocation: false # Maintain Context -**Ubiquitous language** keeps project terms rigorous through everyday use and refinement; concise architecture decision records preserve the consequential choices that shape the codebase. +**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. Resolve project language +### 1. Maintain the language inline -Compare domain language in the conversation with the root `CONTEXT.md` and relevant code. Challenge vague, overloaded, or conflicting terms, propose one precise canonical term, and test it with concrete scenarios and edge cases. Treat code as evidence of current behaviour and the user's confirmed answer as intent; surface contradictions for resolution. Reuse a compatible convention and obtain agreement before moving or reshaping conflicting durable records. The term is either validated with the user or remains explicitly unresolved. +Apply this loop to each material domain term while the discussion is taking place: -### 2. Maintain the glossary +- 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. -As soon as a term is validated and agreed, create or update the single root `CONTEXT.md` using the [context template](assets/context-template.md). Keep definitions to one or two sentences, add `_Avoid_` only for aliases or ambiguous alternatives that actually occur, and group terms under descriptive subheadings when natural clusters emerge; keep a flat list when all terms form one cohesive area. Define domain meaning rather than implementation, specifications, or general programming concepts. Give each domain meaning one authoritative entry and link supporting material from it. The glossary reflects each resolved term before the discussion continues. +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. -### 3. Test the ADR gates +### 2. Keep the glossary rigorous -Test an accepted codebase decision against all three ADR gates: +Define domain meaning rather than implementation, specifications, or general programming concepts. Give each meaning one authoritative entry, keep its definition to one or two sentences, 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 only when all three gates pass. The decision is either rejected as routine or identified as a qualifying architectural decision. +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 a qualifying decision is accepted, 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 the file `NNNN-decision-shaped-slug.md`. Use an inverted pyramid: state the decision first, then only the context and significant ramifications needed to explain it. Give each architectural decision one authoritative ADR. Require only `Decision`, `Context`, and `Ramifications` as content sections, in that order; reserve frontmatter for `status` and conditional supersession links. Link supporting material from that record. The new ADR is brief, accepted, sequentially numbered, and readable from its filename. - -### 5. Supersede a changed decision - -When an accepted decision changes, read only the specific ADR it supersedes, preserve that record, and create a new one. Set the old record's `status` to `superseded` with a relative `superseded-by` link, and give the new record a relative `supersedes` link; leave the old decision, context, and ramifications unchanged. Both records expose the decision history in both directions. +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. -### 6. Verify and hand off +### 5. Verify and hand off -Re-read every changed artifact against the resolved language, accepted decisions, and relevant code evidence, then report the files changed and any unresolved contradiction. The handoff identifies a consistent durable record or names the exact uncertainty that prevented one. +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/assets/adr-template.md b/skills/maintain-context/assets/adr-template.md index 19c3d8d..fbf0562 100644 --- a/skills/maintain-context/assets/adr-template.md +++ b/skills/maintain-context/assets/adr-template.md @@ -1,7 +1,3 @@ ---- -status: accepted ---- - # {Decision-shaped title} ## Decision diff --git a/skills/maintain-context/assets/context-template.md b/skills/maintain-context/assets/context-template.md index 78c101f..486cc18 100644 --- a/skills/maintain-context/assets/context-template.md +++ b/skills/maintain-context/assets/context-template.md @@ -4,5 +4,7 @@ ## 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.} From b652c415ba39817cff858b71060fa754bf75b0c7 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 08:32:06 +0100 Subject: [PATCH 41/52] feat(tdd): add durable test guidance --- skills/tdd/SKILL.md | 18 +++--- skills/tdd/references/TEST-DOUBLES.md | 59 +++++++++++++++++++ skills/tdd/references/TEST-QUALITY.md | 83 +++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 10 deletions(-) create mode 100644 skills/tdd/references/TEST-DOUBLES.md create mode 100644 skills/tdd/references/TEST-QUALITY.md diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 78a7d55..a33232f 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -1,6 +1,6 @@ --- name: tdd -description: Builds observable behaviour through red-green-refactor. Use when a feature or bug fix can be exercised by an existing runnable test suite through a stable seam. +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. metadata: invocation: model disable-model-invocation: false @@ -8,7 +8,7 @@ disable-model-invocation: false # Test-Driven Development -**Test-driven development** builds one observable behaviour at a time through red-green-refactor. Use **Classicist TDD** to test stable public seams with real internal collaborators, introducing doubles mainly at uncontrollable boundaries. +**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. ## Prerequisite @@ -18,24 +18,22 @@ TDD applies when an existing runnable test suite can exercise the requested beha ### 1. Establish the baseline -Read repository instructions, identify the relevant test command, and run the existing suite to establish a known baseline. Separate unrelated existing failures from the change, then select the smallest observable behaviour. The baseline, test seam, and next behaviour are explicit. +Read repository instructions, identify the relevant test command, and run the existing suite. Separate unrelated failures, then select the smallest requested behaviour. Apply **information hiding** to choose the narrowest public seam that exposes the outcome while concealing implementation decisions likely to change. 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, and oracle are explicit. ### 2. Red -Use **Arrange-Act-Assert** to add one focused test through a stable public interface. For a bug, reproduce the incorrect behaviour; adopt an already-failing regression test only when it independently specifies the desired behaviour. Run the test and confirm that it fails for the expected behavioural reason rather than a test defect or environment error. When it does not, remain in Red: correct an in-scope test defect or report an environment blocker, then rerun until the expected failure is observed. Meaningful red evidence is recorded before Green begins. +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. + +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. ### 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 hiding baseline failures. +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. ### 4. Refactor -Improve the test and production code while keeping behaviour fixed. Run the focused tests after each material change until the design is clear and green. The cycle ends with no refactor regression. +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. ### 5. Complete the cycles 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. - -## Test Quality - -Apply the **Test Desiderata** to retain tests that are isolated, composable, fast, inspiring, writable, readable, behavioural, structure-insensitive, automated, specific, deterministic, and predictive. Retained tests remain unchanged when production code is refactored without changing observable behaviour; when structure alone breaks a test, move its assertions to the public outcome. Prefer assertions on public outcomes over CSS classes, incidental DOM shape, private methods, internal call sequences, broad snapshots, or coverage-only cases. diff --git a/skills/tdd/references/TEST-DOUBLES.md b/skills/tdd/references/TEST-DOUBLES.md new file mode 100644 index 0000000..ded54f2 --- /dev/null +++ b/skills/tdd/references/TEST-DOUBLES.md @@ -0,0 +1,59 @@ +# 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 new file mode 100644 index 0000000..1a53249 --- /dev/null +++ b/skills/tdd/references/TEST-QUALITY.md @@ -0,0 +1,83 @@ +# 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. From 4fdfa1c9cdd661994b58a0474077422a168c3aac Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 11:24:47 +0100 Subject: [PATCH 42/52] feat(code-review): add independent inspection workflow --- skills/code-review/SKILL.md | 47 +++++++++++--------- skills/code-review/agents/openai.yaml | 2 +- skills/code-review/references/CODE-SMELLS.md | 28 ++++++++++++ 3 files changed, 54 insertions(+), 23 deletions(-) create mode 100644 skills/code-review/references/CODE-SMELLS.md diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 2742aee..ca72eae 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -description: Reviews scoped code changes for requirements and code health. Use when assessing a diff, branch, pull request, or completed implementation. +description: Reviews scoped code changes against a specification and applicable standards. Use when assessing a diff, branch, pull request, or completed implementation. metadata: invocation: model disable-model-invocation: false @@ -8,51 +8,54 @@ disable-model-invocation: false # Code Review -**Google code review** applies the code-health standard to a scoped change. Separate requirements and code-health passes keep delivery gaps, defects, and refactor opportunities independently visible. +**Tailored software formal inspection** prepares fixed evidence packets for independent Standards and Spec inspectors, then presents their diagnostic findings without changing the reviewed work. ## Process -### 1. Resolve the scope +### 1. Fix the inspection scope -Resolve the change scope in this order: an explicit caller-supplied scope, uncommitted tracked and untracked work, then the current branch from its default-branch merge base. Confirm any revision exists and the change set is non-empty; report the exact blocker and stop when either check fails, and ask the user only when multiple scopes remain plausible. Recover requirements from caller context, a supplied request, specification or ticket, then the change description and commit history. When none exists, state that there is no requirements source rather than inventing one. The exact change set and best available requirements source are explicit. +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. -### 2. Gather the evidence +### 2. Resolve the inspection sources -Read repository instructions, relevant context and decisions, changed files in full, nearby tests, and the surrounding code needed to judge effects. Run non-mutating verification already required by the repository when its result materially informs the review. The review evidence and applicable standards are complete. +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. -### 3. Trace the requirements +### 3. Prepare the work aids -Perform a **requirements traceability** pass. Compare the change with every available requirement and identify missing, partial, incorrect, conflicting, or unrequested behaviour and relevant unhandled cases. When there is no requirements source, preserve that limitation instead of treating inferred intent as a requirement. Requirements candidates are explicit. +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. -### 4. Assess code health +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. -Perform an independent code-health pass across correctness, design, complexity, tests, naming, documentation, security, performance, reliability, and repository standards where relevant. Apply the **Test Desiderata** to changed tests, especially behavioural sensitivity, structure insensitivity, specificity, and determinism. Use **code smells** as a heuristic baseline: **Mysterious Name**, **Duplicated Code**, **Global Data**, **Mutable Data**, **Divergent Change**, **Shotgun Surgery**, **Feature Envy**, **Data Clumps**, **Primitive Obsession**, **Repeated Switches**, **Speculative Generality**, **Message Chains**, **Middle Man**, and **Refused Bequest**. Investigate other established smells when the changed code provides a concrete cue. A smell becomes a finding only when evidence shows a worthwhile correction. Code-health candidates are explicit. +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. -### 5. Validate the candidates +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. -Apply **falsification** to every candidate against the scoped change, full context, requirements, and repository standards. Run targeted non-mutating tests, type checks, linting, or other checks when they can settle a claim. Discard any candidate without a demonstrated consequence. Every remaining finding is reproducible or directly evidenced. +### 4. Assign the inspections -### 6. Prioritise the findings +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. -Use **risk-based prioritisation**: `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 improvement. Keep both review axes separate and order findings within each from highest to lowest priority. Every reported finding is actionable. +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. + +### 5. Present the inspection report + +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. ## Rules -- Keep the review read-only and return corrections for the caller to implement. -- Report only issues introduced by or materially relevant to the scoped change. -- Prefer code evidence and documented standards over personal preference. -- Hold refactor opportunities to the same evidence, consequence, priority, and correction standard as behavioural findings. +- 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. ## Handoff -State the exact scope and requirements source, then return `## Requirements` and `## Code health`. Use `No requirements source.` when applicable and `No findings.` for a clean axis. Format each finding as: +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: ```markdown ### [priority] Concise finding -- Evidence: exact `path:line` and observed fact +- Evidence: exact code `path:line`, applicable authority, and observed fact - Consequence: concrete behaviour or code-health impact -- Correction: smallest effective change ``` -End with `## Summary`, including the finding count for each axis and any check that could not run. When no material finding remains, say the scoped change is clean plainly. +End with `## Summary` and the finding count for each axis. When neither axis contains a material finding, say the fixed change is clean plainly. diff --git a/skills/code-review/agents/openai.yaml b/skills/code-review/agents/openai.yaml index faa414c..a243ba1 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 for requirements and health' + short_description: 'Review code against standards and specification' policy: allow_implicit_invocation: true diff --git a/skills/code-review/references/CODE-SMELLS.md b/skills/code-review/references/CODE-SMELLS.md new file mode 100644 index 0000000..38e2b5d --- /dev/null +++ b/skills/code-review/references/CODE-SMELLS.md @@ -0,0 +1,28 @@ +# 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. + +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. +3. **Long Function** — A function contains enough distinct steps, branches, or levels of abstraction to obscure its purpose or invariants. A cohesive linear workflow may be clearer when read together. +4. **Long Parameter List** — Numerous inputs or recurring groups of related values make a callable's contract hard to understand or use safely. A boundary function may intentionally expose independent dependencies. +5. **Global Data** — Broadly accessible data creates hidden dependencies across consumers. Immutable constants or configuration with explicit ownership may not carry that risk. +6. **Mutable Data** — In-place changes or aliases make state transitions and observers difficult to reason about. Mutation with a tight owner, lifetime, and invariant may remain local and explicit. +7. **Divergent Change** — One module changes for several unrelated responsibilities within the scoped work. Multiple edits may still serve one cohesive responsibility. +8. **Shotgun Surgery** — One conceptual change requires coordinated edits scattered across many locations. Layer-specific or generated representations may legitimately change together. +9. **Feature Envy** — Behaviour depends more on another object's data or decisions than on its own owner. Orchestration, presentation, and adapter code may properly coordinate across a boundary. +10. **Data Clumps** — The same group of values repeatedly travels or appears together as an implicit concept. Coincidental co-occurrence or a constrained public boundary may not establish one shared abstraction. +11. **Primitive Obsession** — Primitive values repeatedly carry domain states, units, validation, or rules that callers must remember. Simple, local, already-constrained values may remain unambiguous. +12. **Repeated Switches** — Conditional dispatch over the same discriminator recurs across the change. A single exhaustive boundary mapping may keep variation explicit without scattering it. +13. **Loops** — Imperative iteration obscures the transformation, selection, or control intent being performed. Stateful traversal, early exit, or measured performance constraints may make the loop the clearest form. +14. **Lazy Element** — An abstraction carries little distinct behaviour, policy, or information. A small named boundary may still express a domain concept or preserve a necessary interface seam. +15. **Speculative Generality** — Flexibility, parameters, hooks, or abstractions serve only hypothetical requirements. A current specification, compatibility contract, or demonstrated extension point may make the flexibility concrete. +16. **Temporary Field** — An object's field is meaningful only during particular modes or phases, leaving other states uncertain. An explicit lifecycle with guarded access may make those states intentional. +17. **Message Chains** — A caller navigates through a sequence of collaborators and therefore depends on their internal structure. A stable data traversal or intentional fluent interface may expose that chain as its contract. +18. **Middle Man** — An element mostly forwards requests without contributing policy, translation, or information. A boundary may still provide isolation, authorisation, observability, or compatibility. +19. **Insider Trading** — Modules rely on each other's internal knowledge or backchannels beyond their stated contracts. A deliberately shared internal protocol may have clear ownership and stability. +20. **Large Class** — A class accumulates enough unrelated state or behaviour to obscure its responsibility and invariants. A cohesive aggregate may need central ownership to protect one invariant boundary. +21. **Alternative Classes with Different Interfaces** — Types serving the same conceptual role expose unnecessarily different contracts. Similar-looking types may instead represent distinct domain roles. +22. **Data Class** — A type mainly stores data while its rules or meaningful behaviour live elsewhere. A transfer object, event, or serialisation record may be intentionally data-only. +23. **Refused Bequest** — A subtype rejects, ignores, or cannot honour a substantial part of its inherited contract. A narrow implementation may still fully honour the interface actually promised. +24. **Comments** — Comments compensate for code whose intent or structure is unclear, or merely restate what it does. Rationale, safety constraints, protocol details, and public contracts may require commentary beyond the code. From 8c8773341746bcb50cd45a812060a4bdb2a8d760 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 11:38:39 +0100 Subject: [PATCH 43/52] refactor(elicit-with-context): reduce router to composition --- skills/elicit-with-context/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/elicit-with-context/SKILL.md b/skills/elicit-with-context/SKILL.md index 01db8ba..e14c444 100644 --- a/skills/elicit-with-context/SKILL.md +++ b/skills/elicit-with-context/SKILL.md @@ -8,8 +8,8 @@ disable-model-invocation: true # Elicit with Context -Shared understanding stays aligned with durable project language and qualifying architecture decisions. +Elicits shared understanding while maintaining project context. ## Process -Invoke `$elicit`, applying `$maintain-context` throughout. Treat `$elicit`'s final confirmation as the acceptance boundary for qualifying ADRs, then return the elicitation state, context changes, and unresolved language or decisions. +Invoke `$elicit` for questioning, applying `$maintain-context` throughout. From 3453292a865896b5af3cc0e1c7b34859a7d7fcb4 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 12:30:52 +0100 Subject: [PATCH 44/52] refactor(implement): reduce router to PDCA loop --- skills/implement/SKILL.md | 24 +++--------------------- skills/implement/agents/openai.yaml | 2 +- 2 files changed, 4 insertions(+), 22 deletions(-) diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md index 0e4cb18..ee4b4dd 100644 --- a/skills/implement/SKILL.md +++ b/skills/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -description: Implements clear software requests through verified slices and review. Use when the user asks to change code, documentation, or configuration. +description: Routes confirmed implementation work through TDD and code review until complete. Use when the user asks to implement a clear software request. metadata: invocation: user disable-model-invocation: true @@ -8,26 +8,8 @@ disable-model-invocation: true # Implement -**Tracer bullets** deliver the smallest end-to-end slice and use its feedback to aim the next one. `$tdd` builds applicable behaviour; `$code-review` assesses the completed implementation independently. +A bounded **Plan–Do–Check–Act (PDCA)** cycle routes confirmed work through `$tdd` and `$code-review` until complete. ## Process -### 1. Deliver a verified slice - -Deliver the smallest end-to-end slice that advances the request. Invoke `$tdd` when its prerequisite applies; otherwise implement directly with the best available targeted verification. Repeat until every requested behaviour and acceptance condition is implemented. - -### 2. Review and remediate - -Invoke `$code-review` with the confirmed request and exact implementation scope. Address every in-scope finding in priority order, invoking `$tdd` for applicable behavioural corrections. Invoke `$elicit` when a correction would materially change agreed behaviour, a public contract, architecture, or authorised scope. Re-run relevant verification and `$code-review` until its latest report has no unresolved in-scope findings. - -### 3. Run the final checks - -Run the repository's prescribed final checks without modifying pre-existing out-of-scope changes. Isolate a mutating check when needed; when that cannot be done safely, leave it unrun and report the blocker. Available checks pass, or the exact blocker and any unrelated pre-existing failure are reported without claiming full verification. - -## Rules - -- Preserve pre-existing user changes and keep implementation, review, and remediation scoped to the current request. - -## Handoff - -Report the implemented behaviour and changed files, `$tdd` applicability, verification and review evidence, and any unresolved blocker or uncertainty. +Invoke `$tdd` to implement the confirmed work, then invoke `$code-review` on the result. Route every finding through `$tdd`, then repeat `$code-review` until the work is complete and the latest review has no findings. diff --git a/skills/implement/agents/openai.yaml b/skills/implement/agents/openai.yaml index 302154c..0e09bd3 100644 --- a/skills/implement/agents/openai.yaml +++ b/skills/implement/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Implement' - short_description: 'Implement changes in verified slices' + short_description: 'Implement through TDD and review' policy: allow_implicit_invocation: false From 042278b63916f8163b34d3b95b63849cbb3e494e Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 12:41:22 +0100 Subject: [PATCH 45/52] feat(tdd): select slices with tracer bullets --- skills/tdd/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index a33232f..5baf647 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -18,7 +18,7 @@ TDD applies when an existing runnable test suite can exercise the requested beha ### 1. Establish the baseline -Read repository instructions, identify the relevant test command, and run the existing suite. Separate unrelated failures, then select the smallest requested behaviour. Apply **information hiding** to choose the narrowest public seam that exposes the outcome while concealing implementation decisions likely to change. 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, and oracle are explicit. +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 apply **information hiding** to choose the narrowest stable public seam that can observe that slice while concealing implementation decisions likely to change. 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, and oracle are explicit. ### 2. Red From 17ca9ed15b07ba9be2b0d59636ee738fa5907233 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 13:42:55 +0100 Subject: [PATCH 46/52] refactor(skills): simplify commit and PR workflows --- skills/commit/SKILL.md | 28 ++++++++++------------------ skills/pr/SKILL.md | 32 ++++++++++---------------------- skills/pr/agents/openai.yaml | 2 +- 3 files changed, 21 insertions(+), 41 deletions(-) diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index ef6bb35..19e39f6 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,6 +1,6 @@ --- name: commit -description: Creates coherent conventional commits from uncommitted work. Use when the user or an authorised publishing workflow requests ready changes be inspected, separated, staged, and committed. +description: Creates coherent Conventional Commits from eligible changed work. Use when the user or an authorised workflow asks to commit ready changes. metadata: invocation: model disable-model-invocation: false @@ -8,30 +8,22 @@ disable-model-invocation: false # Commit -**Conventional Commits** turns uncommitted work into atomic commits whose messages state each change's intent. +**Conventional Commits** turns eligible changed work into coherent commits whose messages state each change's intent. ## Process -### 1. Establish authority and scope +### 1. Inspect the changed work -Establish commit authority from an explicit user request or authorised caller. Inspect `git status`, the repository's Git instructions and current operation, staged, unstaged, and untracked changes, and recent commit messages. Honour user-supplied scope or message constraints and compatible repository conventions. When authority is absent or no eligible change remains, report it and stop without changing Git state. Otherwise the complete candidate diff and commit context are explicit. +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. Partition coherent concerns +### 2. Group coherent changes -Partition eligible changes by coherent intent using **atomic commits**. Keep related implementation, tests, and documentation together while leaving unrelated or ambiguous work uncommitted. Treat a coherent, independent pre-staged set as the first commit; when it mixes concerns or belongs with unstaged work, ask the user before altering the staged set. Each planned commit has one explainable purpose. +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. Stage one concern +### 3. Create the commits -For each concern, retain an already exact staged selection or use **interactive staging** at file or hunk granularity to stage exactly that change, then inspect the complete staged diff. The index represents one atomic change while unselected work remains intact. +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. Write the message +### 4. Verify the result -Write an accurate Conventional Commit message in the form `type[(scope)][!]: description` for the staged diff. - -### 5. Create the commit - -Create the commit and allow configured Git hooks to run. On any failure, treat hook output as authoritative when present, preserve the index and working tree, and report the exact output and resulting Git state. Obtain user direction for any repository or user Git configuration change. - -### 6. Verify the commits - -Verify each created commit against its recorded diff, inspect the remaining status before continuing, and return each hash and subject plus work left uncommitted. +Verify each created commit and inspect the remaining status. Return each hash and subject plus any work left uncommitted. diff --git a/skills/pr/SKILL.md b/skills/pr/SKILL.md index 31dacc8..475567d 100644 --- a/skills/pr/SKILL.md +++ b/skills/pr/SKILL.md @@ -1,6 +1,6 @@ --- name: pr -description: Publishes the current GitHub branch as a concise pull request. Use when work is ready to be committed, pushed, and opened for review. +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 @@ -8,34 +8,22 @@ disable-model-invocation: true # Pull Request -**GitHub flow** publishes the current branch as a concise, ready-for-review pull request. Invoke `$commit` when eligible uncommitted work exists; it remains authoritative for commit selection, staging, and messages. - -## Prerequisites - -A GitHub remote, authenticated push and pull-request access, an attached branch, and a distinct base branch are required. Use the user-supplied base or the remote's default branch. Report the missing condition and stop when a prerequisite cannot be resolved. +Publish the current branch through the repository's available setup and represent its complete work in one pull request. ## Process -### 1. Inspect the publication context - -Inspect repository instructions and pull-request templates, Git status and current operation, the current branch, GitHub remotes, authentication, the selected base, and any existing pull request for the branch. The publication context and applicable repository requirements are explicit before mutation. - -### 2. Commit eligible work - -Invoke `$commit` when eligible uncommitted work exists. Continue with its reported commits and intentionally excluded work visible. - -### 3. Establish the pull-request scope +### 1. Inspect the repository setup -Fetch the selected remote base, find its merge base with `HEAD`, and inspect the complete commit history and diff from that point. Stop when the branch has no publishable diff; otherwise the full pull-request scope is explicit. +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. -### 4. Write the pull request +### 2. Establish the grouped work -Derive an accurate Conventional Commit title in the form `type[(scope)][!]: description` for the complete diff. Populate every required repository-template section; without a required template, write one short **BLUF** paragraph explaining what changed and why. The title and body represent the complete branch rather than one commit. +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. -### 5. Publish the branch +### 3. Write the pull request -Push the current branch without rewriting remote history and create a ready pull request against the selected base, or a draft only when the user explicitly requested one. When an open pull request already represents the branch, reuse it and reconcile its base, title, body, and ready or draft state with the selected publication context. The remote branch and one corresponding pull request exist with the requested metadata and state. +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. -### 6. Verify the pull request +### 4. Publish and verify -Verify the pull request's head, base, draft state, title, and body against the inspected scope and repository requirements. Return its URL and report any failed publication or verification with the resulting local and remote state. +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/pr/agents/openai.yaml b/skills/pr/agents/openai.yaml index d9506f9..b844df6 100644 --- a/skills/pr/agents/openai.yaml +++ b/skills/pr/agents/openai.yaml @@ -1,5 +1,5 @@ interface: display_name: 'Pull Request' - short_description: 'Publish a concise GitHub pull request' + short_description: 'Publish a concise pull request' policy: allow_implicit_invocation: false From 49978e7c9c0315e3fd92b21403507f36a4358541 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 14:47:55 +0100 Subject: [PATCH 47/52] feat(maintain-agents): enforce lean repository guidance --- skills/maintain-agents/SKILL.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/skills/maintain-agents/SKILL.md b/skills/maintain-agents/SKILL.md index 1e36fdf..038ca5f 100644 --- a/skills/maintain-agents/SKILL.md +++ b/skills/maintain-agents/SKILL.md @@ -1,6 +1,6 @@ --- name: maintain-agents -description: Initializes and compresses repository-wide agent guidance. Use when creating or improving a root AGENTS.md. +description: Creates and compresses lean root AGENTS.md files. Use when initializing or improving repository-wide agent guidance. metadata: invocation: user disable-model-invocation: true @@ -8,26 +8,26 @@ disable-model-invocation: true # Maintain AGENTS.md -**Lossless compression** turns repository-wide constraints into the smallest durable instruction surface an agent needs before reading the code. +**Progressive Disclosure** keeps root `AGENTS.md` guidance limited to behaviour every repository task needs while narrower instructions remain discoverable on demand. ## Process ### 1. Inspect the instruction surface -Locate the repository root and inspect the root `AGENTS.md`, applicable instruction layers, and task-relevant repository evidence. Read manifests, task-runner configuration, CI, and contributor documentation only far enough to identify the canonical project harness and recover the intent of existing guidance. The target file, active instruction chain, and candidate harness are explicit. +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. -### 2. Classify the instructions +### 2. Allocate the guidance -Classify every existing and proposed instruction. Keep only succinct project-wide behaviour that applies across tasks and cannot be reliably inferred from the relevant code, configuration, or documentation, plus a canonical command whose selection prevents ambiguous verification. Remove stale guidance, rationale, boilerplate, repository description, duplicated enforcement, personal preferences, and task-specific workflows. Report each useful displaced instruction with its smallest appropriate destination, such as an existing skill, a scoped instruction file, or executable enforcement; leave those destinations unchanged. Every retained instruction earns its permanent context cost. +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. ### 3. Establish the required guidance -Ensure the file states: `When the user corrects you with a reusable, project-wide rule, ask whether to update AGENTS.md.` Inspect available check entry points and select one safe aggregate harness that represents completed work. When alternatives materially differ or a candidate has external side effects, invoke `$elicit`; when no trustworthy aggregate exists, omit the check instruction rather than inventing one. The correction feedback loop and, when available, one canonical completion check are explicit. +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. ### 4. Write the root instructions -Create or rewrite only the root `AGENTS.md`. Use direct imperative lines, merge overlapping meanings, remove headings that add no navigation, and apply lossless compression until every word changes agent behaviour or preserves a necessary condition. The file contains one authoritative expression of each retained rule. +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. ### 5. Verify and hand off -Re-read every line against its repository-wide scope and runtime value. Verify the selected harness exists and run it when it is safe and applicable. Return the changed file, harness result or limitation, removed instructions with destinations, and any unresolved conflict in the active instruction chain. The user receives a thin verified root instruction file and a visible account of displaced guidance. +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. From 127b1bf7e0b27bb477d8764d3fad206afb941c41 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 15:27:00 +0100 Subject: [PATCH 48/52] feat(debug): enforce scientific repair loop --- skills/debug/SKILL.md | 20 ++++++----- skills/debug/references/BOUNDARY-EVIDENCE.md | 23 ++++++++++++ skills/debug/references/NONDETERMINISTIC.md | 37 ++++++++++++++++++++ skills/debug/references/PERFORMANCE.md | 28 +++++++++++++++ skills/debug/references/TECHNIQUES.md | 25 ++++++------- 5 files changed, 113 insertions(+), 20 deletions(-) create mode 100644 skills/debug/references/BOUNDARY-EVIDENCE.md create mode 100644 skills/debug/references/NONDETERMINISTIC.md create mode 100644 skills/debug/references/PERFORMANCE.md diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 861863c..e913da3 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -8,26 +8,30 @@ disable-model-invocation: true # Debug -**Scientific method** turns a repeatable failing signal into a verified causal repair through falsifiable hypotheses and discriminating experiments. +**Scientific debugging** turns a repeatable failing signal into a verified causal repair through falsifiable hypotheses, predicted observations, and discriminating experiments. ## Process ### 1. Establish a repeatable signal -Read repository instructions and establish the authorised scope, expected behaviour, observed behaviour, and a repeatable failing signal. Use the smallest reliable reproduction: a failing test, benchmark, trace, log pattern, or targeted probe may substitute for a local reproduction when it distinguishes the fault. When the signal or a later discriminating experiment is not obvious, use [Debugging Techniques](references/TECHNIQUES.md) to select and tighten the smallest applicable one. Preserve pre-existing user work. When no repeatable signal can be established, leave the implementation unchanged and report the evidence, blocker, and next discriminating experiment. The failure and mutation boundary are explicit. +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. ### 2. Isolate the root cause -Gather evidence and state falsifiable hypotheses in evidence-supported order. Run the cheapest experiment that distinguishes the leading hypotheses, changing one variable at a time and recording the result. Use a **minimal reproducible example**, **binary search**, or **delta debugging** when it will narrow the failing input, change, component, or boundary. Repeat until **root-cause analysis** identifies a cause supported by the experiments rather than a correlated symptom. The demonstrated cause is explicit before repair. +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. -### 3. Repair the cause +### 3. Test one repair -When the user explicitly requested diagnosis only, stop before mutation and follow the Handoff. Otherwise invoke `$tdd` when its prerequisite applies and the fault has a stable regression seam. When TDD is not applicable, apply the smallest correction to the demonstrated cause and use the repeatable signal as the immediate feedback loop. Keep the repair within the authorised scope; report a cause that requires external access or expanded authority as a blocker. The repair is causal, focused, and covered by the strongest feasible regression protection. +When the user requested diagnosis only, stop before mutation and follow the Handoff. Otherwise 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. -### 4. Verify the repair +### 4. Accept or revert the repair -Re-run the original reproduction and confirm the expected behaviour, then run focused regression coverage, relevant nearby checks, and the repository-prescribed wider checks. Separate unrelated pre-existing failures from repair regressions. The original fault is repaired and relevant checks pass, or the exact remaining failure and uncertainty are explicit. +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. + +### 5. Verify and clean up + +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. ## Handoff -Report the expected and observed behaviour, failing signal, hypotheses and experiments, root cause, changed files, regression protection, verification commands and results, and any blocker or unresolved uncertainty. For diagnosis-only work, state plainly that no implementation was changed. +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. diff --git a/skills/debug/references/BOUNDARY-EVIDENCE.md b/skills/debug/references/BOUNDARY-EVIDENCE.md new file mode 100644 index 0000000..35ad9aa --- /dev/null +++ b/skills/debug/references/BOUNDARY-EVIDENCE.md @@ -0,0 +1,23 @@ +# 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/NONDETERMINISTIC.md b/skills/debug/references/NONDETERMINISTIC.md new file mode 100644 index 0000000..ab0ac8d --- /dev/null +++ b/skills/debug/references/NONDETERMINISTIC.md @@ -0,0 +1,37 @@ +# 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/PERFORMANCE.md b/skills/debug/references/PERFORMANCE.md new file mode 100644 index 0000000..d648a72 --- /dev/null +++ b/skills/debug/references/PERFORMANCE.md @@ -0,0 +1,28 @@ +# 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 index ea5288d..9cd3d5c 100644 --- a/skills/debug/references/TECHNIQUES.md +++ b/skills/debug/references/TECHNIQUES.md @@ -1,19 +1,19 @@ # Debugging Techniques -Use this reference when the repeatable failing signal or next discriminating experiment is not obvious. Select the smallest applicable technique; combine techniques only when each settles a distinct question, then return to the main workflow. +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, expected verdict, and observed verdict. A useful signal is: +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 non-deterministic fault; +- **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; compare the measured failure rate under the same conditions. +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 @@ -22,12 +22,12 @@ A passing retry does not turn an intermittent failure green; compare the measure | 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. | -| The fault requires browser behaviour | Headless browser script | Assert the relevant DOM, console, request, or response outcome; retain the smallest trace or fixture that exposes the symptom. | -| Only a production request or event exposes the fault | Capture and replay | Capture the smallest safe request, event, trace, or payload and replay it at the nearest stable seam; retain correlation and environment context without secrets. | +| 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 | Repetition loop | Run the exact trigger repeatedly, report failures per attempts, and control time, randomness, order, load, and environment one dimension at a time. | -| The fault is concurrent | Controlled schedule or race probe | Prefer a recorded or systematic schedule and repository-supported race tooling. Use stress only to amplify and capture a failure, not to prove its absence. | -| The fault is performance | Benchmark loop | Define a representative workload and failing threshold; warm up, repeat, and report variance before profiling the same workload. | +| 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 @@ -37,10 +37,10 @@ A passing retry does not turn an intermittent failure green; compare the measure | 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** | Record hypothesis-relevant input, output, state, configuration, timing, and correlation at the few boundaries that distinguish the candidates. | +| 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 | Vary one timing, order, load, or scheduling dimension and compare the measured rate. Prefer waiting for observable conditions over guessed delays. | -| A controlled benchmark proves a regression | Profiler, query plan, or resource trace | Identify the work responsible for the measured difference before changing it; remeasure the identical workload after repair. | +| 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. @@ -49,3 +49,4 @@ An experiment is complete when its observation confirms or rejects a stated hypo - 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. From d484f958ce1aa05bba3bc4e4da213c77ce627c54 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 17:59:53 +0100 Subject: [PATCH 49/52] feat(modular-design): add shared architecture standard --- skills/code-review/SKILL.md | 2 + skills/debug/SKILL.md | 2 +- skills/modular-design/SKILL.md | 55 +++++++++++++++++++ skills/modular-design/agents/openai.yaml | 5 ++ .../modular-design/references/TECHNIQUES.md | 33 +++++++++++ skills/review-architecture/SKILL.md | 6 +- .../references/architecture-analysis.md | 23 ++------ skills/tdd/SKILL.md | 2 +- 8 files changed, 104 insertions(+), 24 deletions(-) create mode 100644 skills/modular-design/SKILL.md create mode 100644 skills/modular-design/agents/openai.yaml create mode 100644 skills/modular-design/references/TECHNIQUES.md diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index ca72eae..083740b 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -28,6 +28,8 @@ The Spec packet applies **bidirectional requirements traceability**: trace every 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. +When the fixed change alters modular architecture, invoke `$modular-design` and include the applicable standard in the Standards packet. + 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. ### 4. Assign the inspections diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index e913da3..57e00a0 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -22,7 +22,7 @@ Gather evidence and state falsifiable causal hypotheses in evidence-supported or ### 3. Test one repair -When the user requested diagnosis only, stop before mutation and follow the Handoff. Otherwise 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. +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. ### 4. Accept or revert the repair diff --git a/skills/modular-design/SKILL.md b/skills/modular-design/SKILL.md new file mode 100644 index 0000000..4620ee4 --- /dev/null +++ b/skills/modular-design/SKILL.md @@ -0,0 +1,55 @@ +--- +name: modular-design +description: Defines an evidence-backed modular architecture standard. Use when designing or assessing modules, interfaces, dependencies, ownership, or seams. +metadata: + invocation: model +disable-model-invocation: false +--- + +# 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. + +## 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. + +## Standard + +### Name the architecture precisely + +- 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 this vocabulary for reasoning while preserving established project and framework names in code and reports. + +### Hide owned knowledge + +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. + +### Prefer deep cohesive modules + +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. + +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. + +### Choose an idiomatic realization + +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. + +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. + +### Load only applicable techniques + +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. + +## 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. diff --git a/skills/modular-design/agents/openai.yaml b/skills/modular-design/agents/openai.yaml new file mode 100644 index 0000000..5214400 --- /dev/null +++ b/skills/modular-design/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: 'Modular Design' + short_description: 'Apply an evidence-backed modular design standard' +policy: + allow_implicit_invocation: true diff --git a/skills/modular-design/references/TECHNIQUES.md b/skills/modular-design/references/TECHNIQUES.md new file mode 100644 index 0000000..5c27e2b --- /dev/null +++ b/skills/modular-design/references/TECHNIQUES.md @@ -0,0 +1,33 @@ +# 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/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index 147527f..1639a41 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -18,15 +18,15 @@ Establish the review scope. Use the user's explicit scope or the whole repositor ### 2. Recover the quality drivers -Recover quality drivers from explicit project evidence, then apply the priority order in [Architecture Analysis](references/architecture-analysis.md). Distinguish confirmed drivers from inference. Ask the user only when an unknown priority could materially change which redesigns qualify or how they rank. The review has an evidence-backed quality hierarchy. +Invoke `$modular-design` to load the shared architecture standard. Recover quality drivers from explicit project evidence, then apply the priority order in [Architecture Analysis](references/architecture-analysis.md). Distinguish confirmed drivers from inference. Ask the user only when an unknown priority could materially change which redesigns qualify or how they rank. The review has an evidence-backed quality hierarchy and modular baseline. ### 3. Map the architecture -Use the reference's diagnostics to map cohesive capabilities, public contracts, hidden decisions, dependency direction, adapters, seams, runtime boundaries, verification, and change propagation. Treat a module as a capability with a contract, not as a directory, file, class, or service. Record repository-relative paths and precise locations for material evidence. The current architecture and its material pressures are traceable. +Apply the shared standard through the reference's diagnostics to map cohesive capabilities, public contracts, hidden decisions, dependency direction, adapters, seams, runtime boundaries, verification, and change propagation. Record repository-relative paths and precise locations for material evidence. The current architecture and its material pressures are traceable. ### 4. Design each candidate twice -Apply **design it twice** to every serious candidate. Compare at least two materially different boundaries, including their contracts, hidden decisions, dependency direction, quality effects, trade-offs, and migration seams. Use principles and patterns from the reference only when their conditions fit the evidence. Discard rearrangements, new layers, and fashionable patterns that do not materially improve a priority quality. Each candidate has a tested alternative and a codebase-specific rationale. +Apply **design it twice** to every serious candidate. Compare at least two materially different boundaries, including their contracts, hidden decisions, dependency direction, quality effects, trade-offs, and migration seams. Load the shared standard's conditional techniques only when their conditions fit the evidence. Discard rearrangements, new layers, and fashionable patterns that do not materially improve a priority quality. Each candidate has a tested alternative and a codebase-specific rationale. ### 5. Research material external claims diff --git a/skills/review-architecture/references/architecture-analysis.md b/skills/review-architecture/references/architecture-analysis.md index d186cf5..0d6619e 100644 --- a/skills/review-architecture/references/architecture-analysis.md +++ b/skills/review-architecture/references/architecture-analysis.md @@ -8,10 +8,9 @@ Apply the first applicable evidence in this order: 1. Safety, correctness, security, and data integrity constraints. 2. Explicit project quality drivers. -3. Information hiding and change isolation. -4. Cohesion, coupling, and interface depth. -5. Testability and migration safety. -6. Operability, reliability, performance, scalability, and portability when evidenced by the system. +3. The qualities defined by `$modular-design`. +4. Testability and migration safety. +5. Operability, reliability, performance, scalability, and portability when evidenced by the system. Explicit project evidence overrides the baseline. Recover it 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 concrete scenario: stimulus, affected capability or boundary, expected response, and observable measure. Label an inferred driver and its confidence. Ask the user when competing designs depend on an unknown priority that the repository cannot establish. @@ -62,20 +61,6 @@ For every serious candidate, compare at least two materially different designs. Prefer the design that hides more relevant knowledge behind the simpler stable contract while satisfying the higher-priority quality evidence. Reject an alternative explicitly; do not present the first plausible design as inevitable. -## Conditional Concepts - -Use a concept only under its condition: - -| Concept | Use when | Avoid when | -| --- | --- | --- | -| Deep module | A cohesive capability can hide substantial knowledge behind a small stable interface. | The boundary merely combines unrelated work or grows an equally complex interface. | -| Single responsibility | Different actors or change reasons are entangled in one boundary. | A cohesive capability has several internal implementation steps. | -| Dependency inversion | Stable policy depends directly on a volatile mechanism and a purposeful contract can reverse that knowledge dependency. | The abstraction has one accidental consumer and hides no meaningful volatility. | -| Ports and adapters | A purposeful application conversation needs multiple technologies, isolated verification, or replacement. | It would wrap every framework call or create ports without alternate adapters or isolation value. | -| Seam | Verification, replacement, observation, or incremental migration needs a controlled boundary. | Direct use is already stable, observable, and local. | -| Strangler fig | A high-risk boundary must be replaced gradually while old behaviour remains live. | A safe local replacement can be completed and verified atomically. | -| Fitness function | A quality claim can be guarded by an objective repeatable signal. | The proposed measure is a subjective proxy unrelated to the claimed improvement. | - ## Evaluation Assign each label with a one-sentence evidence-based rationale: @@ -99,7 +84,7 @@ Report every qualifying redesign and none below the threshold. Zero is valid; th ## Migration and Fitness -For a retained redesign, define stages that keep the system operable and verifiable. Name prerequisites, the smallest independently useful first slice, coexistence between old and new boundaries, data or contract transition, containment or rollback, and removal of the superseded path. Stop before a file-by-file implementation plan. +For a retained redesign, define stages that keep the system operable and verifiable. Name prerequisites, the smallest independently useful first slice, coexistence between old and new boundaries, data or contract transition, containment or rollback, and removal of the superseded path. Route a high-risk replacement incrementally while old behaviour remains live; replace a safe local boundary atomically. Stop before a file-by-file implementation plan. Pair each claimed improvement with observable fitness evidence, such as: diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md index 5baf647..3a365b8 100644 --- a/skills/tdd/SKILL.md +++ b/skills/tdd/SKILL.md @@ -18,7 +18,7 @@ TDD applies when an existing runnable test suite can exercise the requested beha ### 1. Establish the baseline -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 apply **information hiding** to choose the narrowest stable public seam that can observe that slice while concealing implementation decisions likely to change. 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, and oracle are explicit. +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. ### 2. Red From 7b97b1c5981ca3f3933b4dce47488d97311ce8b7 Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 19:09:41 +0100 Subject: [PATCH 50/52] feat(review-architecture): pair durable and visual reports --- skills/review-architecture/SKILL.md | 44 +++----- .../references/architecture-analysis.md | 98 ++++------------- .../references/report-design.md | 102 +++++------------- 3 files changed, 64 insertions(+), 180 deletions(-) diff --git a/skills/review-architecture/SKILL.md b/skills/review-architecture/SKILL.md index 1639a41..910f9bb 100644 --- a/skills/review-architecture/SKILL.md +++ b/skills/review-architecture/SKILL.md @@ -1,6 +1,6 @@ --- name: review-architecture -description: Reviews a codebase or scope for high-value modular redesigns and produces an interactive HTML report. Use when architecture boundaries, coupling, abstractions, or change isolation need assessment. +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. metadata: invocation: user disable-model-invocation: true @@ -8,46 +8,26 @@ disable-model-invocation: true # Review Architecture -**Information hiding** turns codebase evidence into modular redesigns whose small, stable contracts hide cohesive implementation and change-prone decisions. +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. ## Process -### 1. Establish the review scope +### 1. Establish the review -Establish the review scope. Use the user's explicit scope or the whole repository with the slug `full-codebase`. Convert an explicit scope to a concise lowercase hyphenated slug. Inspect project context, architecture decisions, source, tests, contracts, schemas, dependencies, build and deployment configuration, and documentation. Exclude generated output, vendored dependencies, caches, and binaries from detailed analysis unless they participate in a material boundary. The inspected scope and exclusions are explicit. +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. -### 2. Recover the quality drivers +### 2. Select the redesigns -Invoke `$modular-design` to load the shared architecture standard. Recover quality drivers from explicit project evidence, then apply the priority order in [Architecture Analysis](references/architecture-analysis.md). Distinguish confirmed drivers from inference. Ask the user only when an unknown priority could materially change which redesigns qualify or how they rank. The review has an evidence-backed quality hierarchy and modular baseline. +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. -### 3. Map the architecture +### 3. Persist the review -Apply the shared standard through the reference's diagnostics to map cohesive capabilities, public contracts, hidden decisions, dependency direction, adapters, seams, runtime boundaries, verification, and change propagation. Record repository-relative paths and precise locations for material evidence. The current architecture and its material pressures are traceable. +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. -### 4. Design each candidate twice +### 4. Present the visual shortlist -Apply **design it twice** to every serious candidate. Compare at least two materially different boundaries, including their contracts, hidden decisions, dependency direction, quality effects, trade-offs, and migration seams. Load the shared standard's conditional techniques only when their conditions fit the evidence. Discard rearrangements, new layers, and fashionable patterns that do not materially improve a priority quality. Each candidate has a tested alternative and a codebase-specific rationale. +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. -### 5. Research material external claims +### 5. Verify and hand off -Invoke `$research` when a candidate materially depends on an external framework, language, platform, or architecture claim that warrants durable verification. Use the resulting report as evidence and link it from the architecture report without duplicating its source catalogue. Repository evidence remains sufficient when no material external claim exists. - -### 6. Evaluate and rank the candidates - -Evaluate candidates with explained `high`, `medium`, or `low` impact, effort, risk, and confidence labels; do not calculate a composite score. Retain every redesign that clears the reference's high-value threshold, whether none or many, and rank retained recommendations through the quality hierarchy and evidence. Record reviewed areas without a qualifying redesign as concise coverage rather than low-value findings. The result contains no quota, filler, suppressed qualifying redesign, or exhaustive debt catalogue. - -### 7. Define the recommendations - -For each recommendation, define the evidenced problem, affected modules and contracts, target boundary, rejected alternative, expected quality improvements, framework fit, costs, risks, dependencies, incremental stages, containment or rollback route, smallest useful first slice, and observable architecture fitness checks. Stop before changing implementation or producing a file-by-file implementation plan. Every recommendation is independently understandable, actionable, and verifiable. - -### 8. Create the report - -Read [Report Design](references/report-design.md), then create one single-file interactive HTML report at `docs/architecture/YYYYMMDD-{scope}-architecture-review.html`. Preserve an existing path by adding `-2`, `-3`, and so on before `.html` unless the user explicitly requests replacement. Generate the overview, comparison, diagrams, progressive detail, evidence, coverage, and research links from the completed analysis. The artifact follows the report contract and no existing report is unintentionally overwritten. - -### 9. Validate the report - -Validate the HTML structure and inspect the report in an available browser at desktop and narrow widths. Verify loaded scripts and styles, diagrams, filters, pointer and keyboard operation, visible focus, collapsed and expanded states, overflow, and print output. Correct every material content, interaction, accessibility, or layout defect. When browser inspection is unavailable, complete structural checks and mark visual acceptance as incomplete. The report is either visually accepted or carries an explicit verification limitation. - -## Handoff - -Return the report path, scope and exclusions, recommendation count, invoked research reports, validation performed, and unresolved evidence or visual-QA limitations. Preserve the reviewed implementation unchanged. +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. diff --git a/skills/review-architecture/references/architecture-analysis.md b/skills/review-architecture/references/architecture-analysis.md index 0d6619e..fb21338 100644 --- a/skills/review-architecture/references/architecture-analysis.md +++ b/skills/review-architecture/references/architecture-analysis.md @@ -1,98 +1,46 @@ # Architecture Analysis -Load this reference while mapping, comparing, and ranking architecture redesigns. It supplies diagnostics and decision criteria; `SKILL.md` owns the workflow and report boundary. +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 applicable evidence in this order: +Apply the first evidenced priority in this order: 1. Safety, correctness, security, and data integrity constraints. 2. Explicit project quality drivers. -3. The qualities defined by `$modular-design`. +3. Qualities defined by `$modular-design`. 4. Testability and migration safety. -5. Operability, reliability, performance, scalability, and portability when evidenced by the system. +5. Operability, reliability, performance, scalability, and portability when material to the system. -Explicit project evidence overrides the baseline. Recover it 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 concrete scenario: stimulus, affected capability or boundary, expected response, and observable measure. Label an inferred driver and its confidence. Ask the user when competing designs depend on an unknown priority that the repository cannot establish. +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. -## Architecture Map +## Evidence and Comparison -Map capabilities before proposing structure: +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. -- the purpose and knowledge owned by each capability; -- its public contract, consumers, and promised behaviour; -- the implementation and change-prone decisions the contract hides; -- dependencies entering and leaving the boundary, including shared data; -- framework, storage, network, UI, process, and deployment adapters; -- test, replacement, migration, and operational seams; -- runtime flows for important quality scenarios; -- repeated changes that cross boundaries or force coordinated edits. +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. -Do not infer an architectural boundary from a directory, namespace, class, package, service, or deployment unit alone. One architecture module may contain several internal actions, and one directory may mix several capabilities. +## Qualification and Rank -## Diagnostics +A recommendation qualifies only when it: -Use these as questions, not as a pattern checklist. +- 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. -| Signal | Test | Redesign direction | Guardrail | -| --- | --- | --- | --- | -| Information leakage | Which consumers know a representation, ordering rule, protocol, framework type, or policy that belongs elsewhere? | Gather the knowledge behind one explicit contract. | Moving the same leaked fact to a new helper is not hiding it. | -| Shallow or pass-through interface | Does the interface expose nearly as much complexity as its implementation or repeat another layer's API? | Pull cohesive complexity behind a smaller contract or remove the redundant boundary. | A small function is not automatically a shallow architecture module. | -| Temporal decomposition | Are modules organised by processing steps although the underlying decisions change together? | Group by owned knowledge or capability rather than execution order. | Preserve genuinely independent pipeline stages. | -| Weak cohesion | Do unrelated actors, policies, or change reasons force edits to the same module? | Separate the knowledge that changes for different reasons. | Do not split cohesive internal actions merely to make files smaller. | -| Harmful coupling | Does a change propagate through consumers, create cycles, rely on shared mutable data, or reverse intended policy direction? | Narrow the contract, move ownership, introduce a seam, or invert the volatile dependency. | Coupling is necessary; remove knowledge and coordination, not all connection. | -| Missing seam | Can behaviour be verified or replaced only through the full runtime stack? | Expose the smallest purposeful contract at the volatile boundary. | Do not create interfaces without a verification, replacement, or migration need. | -| Framework leakage | Does domain or application policy depend on transport, persistence, UI, or vendor types? | Translate at an adapter and keep the capability contract in its own language. | Framework conventions may be the correct boundary for framework-owned code. | -| Duplicated policy | Is one rule reimplemented across entry points, services, jobs, or clients? | Give one cohesive module ownership and make callers depend on its contract. | Similar syntax is not necessarily the same policy. | -| Runtime boundary mismatch | Do process, transaction, data ownership, failure, or deployment boundaries cut through a supposedly atomic capability? | Align the contract and migration plan with actual consistency and failure constraints. | Do not force distribution when an in-process boundary is sufficient. | +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: -Trace every material signal to repository-relative paths and precise locations. Separate observed facts, conclusions supported by several observations, and uncertainty. Metrics may locate candidates, but they do not prove a redesign. +- **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. -## Design It Twice - -For every serious candidate, compare at least two materially different designs. A variation in naming, file placement, or interface syntax is not a second design. For each alternative state: - -- the capability boundary and public contract; -- the knowledge and volatile decisions hidden inside it; -- consumer and dependency direction changes; -- the quality scenarios it improves or worsens; -- framework fit and runtime consequences; -- migration seam, first useful slice, and containment route; -- new complexity, risks, and decisions it creates. - -Prefer the design that hides more relevant knowledge behind the simpler stable contract while satisfying the higher-priority quality evidence. Reject an alternative explicitly; do not present the first plausible design as inevitable. - -## Evaluation - -Assign each label with a one-sentence evidence-based rationale: - -- **Impact** — `high` changes a constraint or explicit driver, or removes a repeated high-reach pressure; `medium` materially improves a bounded capability; `low` is marginal or mostly local. -- **Effort** — `high` crosses several boundaries or requires staged data, contract, or deployment work; `medium` needs multiple 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 or an unverified assumption. - -Do not combine labels into a score. Rank qualifying recommendations by the quality priority, then the strength and reach of impact, confidence in the evidence, and migration feasibility and risk. Explain judgment where the order is not obvious. - -A redesign qualifies only when it: - -- materially improves at least one priority quality; -- traces the problem and expected improvement to repository evidence; -- hides or realigns architectural knowledge rather than performing a local refactor or cosmetic rearrangement; -- has a credible incremental route with known dependencies and risks; and -- is supported strongly enough to recommend, with material uncertainty visible. - -Report every qualifying redesign and none below the threshold. Zero is valid; there is no minimum or maximum. Record non-qualifying areas only in review coverage. +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 -For a retained redesign, define stages that keep the system operable and verifiable. Name prerequisites, the smallest independently useful first slice, coexistence between old and new boundaries, data or contract transition, containment or rollback, and removal of the superseded path. Route a high-risk replacement incrementally while old behaviour remains live; replace a safe local boundary atomically. Stop before a file-by-file implementation plan. - -Pair each claimed improvement with observable fitness evidence, such as: - -- forbidden or allowed dependency checks; -- public contract or quality-scenario tests; -- change-impact checks across module boundaries; -- adapter conformance or replacement tests; -- performance, reliability, security, or operability thresholds; -- deployment, telemetry, or runtime signals. +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. -State the signal, expected result, and where it should run. Prefer existing verification when it proves the quality; propose new machinery only when needed. +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 index 17e90fc..dc07cd7 100644 --- a/skills/review-architecture/references/report-design.md +++ b/skills/review-architecture/references/report-design.md @@ -1,96 +1,52 @@ # Architecture Review Report Design -Use this reference when generating and visually verifying the architecture review HTML. The report is a decision tool, not a static audit or a wall of technical prose. +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. -## Information Architecture +## Markdown Record -Use one HTML document with this reading order: +Use this reading order: -1. **Header** — title, review date, scope, exclusions, evidence confidence, and a one-sentence outcome. -2. **Current architecture** — a concise capability and boundary overview with a diagram only when it improves understanding. -3. **Recommendations** — the complete ranked set as comparable summary cards, followed by filters and progressive detail. A zero-result state plainly says that no redesign crossed the evidence threshold. -4. **Review coverage** — areas examined without a qualifying redesign and any evidence limitations. -5. **Method and sources** — repository evidence conventions, invoked research reports, generation time, and visual-verification status. +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. -The initial viewport should explain the result and expose the ranked recommendations without requiring detailed reading. Preserve the ranking as the default view. When several recommendations exist, allow filtering by affected capability, impact, effort, risk, and confidence; show the visible count and provide a clear reset. +Name each recommendation `{ID}. {action-led title}`. Lead with three plain-language fields: -## Recommendation Design +- **Issue:** the present architecture friction and consequence. +- **Fix:** the ownership, contract, or dependency change. +- **Benefit:** the concrete quality improvement. -Make every collapsed card comparable through: +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. -- rank and action-led title; -- one-sentence evidenced problem; -- target module or boundary; -- expected quality improvement; -- impact, effort, risk, and confidence labels; -- affected capabilities or contracts; -- smallest useful first slice. +## HTML Shortlist -Its expanded detail contains: +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. -- observed evidence with repository-relative paths and precise locations; -- current and target boundary diagrams where useful; -- the hidden knowledge and proposed public contract; -- framework and runtime fit; -- the alternative considered and why it lost; -- benefits, costs, risks, and unresolved uncertainty; -- dependencies, migration stages, coexistence, and containment or rollback; -- fitness checks with expected results; -- links to any durable research report. +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. -Use plain language in summaries and retain exact technical names in evidence. Do not hide a recommendation's main cost, risk, or uncertainty inside the expanded content. +## Visual Language -## Visual and Interaction 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. -Use strong hierarchy, generous spacing, readable line lengths, restrained colour, and consistent cards and labels. Paths, symbols, and contracts may use a monospace face. Use colour to reinforce meaning, never to carry it alone. Avoid decoration that competes with comparison or implies unsupported precision. +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. -Scripts, styles, fonts, and diagram libraries may load from CDNs when they help the current report. Tailwind and Mermaid are suitable defaults: +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. -```html -<script src="https://cdn.tailwindcss.com"></script> -<script type="module"> - import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; - mermaid.initialize({ - startOnLoad: true, - theme: 'neutral', - securityLevel: 'loose', - }); -</script> -``` +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. -The artifact is a single generated HTML file whose markup and behaviour remain together; verified CDN dependencies may provide scripts, styles, fonts, and diagram libraries. It need not work offline or preserve CDN compatibility indefinitely. Verify every selected dependency in the rendered report at generation time. Escape repository-derived text before placing it in HTML, attributes, scripts, or diagram definitions. +## Plain Language -Prefer semantic HTML controls and disclosure elements. Filters update results immediately, preserve an obvious current state, and remain operable without a pointer. Avoid interactions whose only purpose is visual novelty. - -## Diagrams - -Use a diagram when boundaries, dependency direction, runtime flow, or migration stages are materially clearer visually. Choose the smallest fitting form: - -- a dependency or boundary graph for current and target modules; -- a flow or sequence for a quality scenario; -- a before-and-after comparison for changed ownership; -- a staged flow for incremental migration. - -Give each diagram one question to answer. Keep nodes few, labels short, arrows directional, and current and target semantics consistent. Place a concise text explanation beside it, label the relationship in prose, and do not rely on colour alone. Avoid ornamental system maps and unreadable whole-repository graphs. - -## Accessibility and Layout - -- Use semantic landmarks, ordered headings, labelled controls, buttons for actions, and native disclosure where practical. -- Make every interaction keyboard-operable with a visible focus indicator and logical focus order. -- Maintain readable text and non-text contrast and pair colour with words, shapes, or symbols. -- Give tables headers, diagrams accessible names and adjacent explanations, and icon-only controls accessible labels. -- Reflow cards, filters, diagrams, and evidence at narrow widths without hiding content or requiring page-level horizontal scrolling. -- Provide print styles that expand recommendation detail, remove interactive chrome, preserve diagrams and evidence, and avoid splitting short cards unnecessarily. +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 file rather than inferring appearance from source: +Inspect the actual temporary file with network access: -1. Open it with network access and confirm every external script, style, font, and diagram dependency loads without a material error. -2. Check the overview, the report's actual zero-or-many recommendation state, filters, reset, and every collapsed and expanded state. -3. Exercise controls with pointer and keyboard; verify focus visibility, order, labels, and no keyboard trap. -4. Inspect desktop and narrow viewports for hierarchy, wrapping, overflow, diagram readability, and content order. -5. Check that labels and diagrams remain understandable without colour and that evidence paths are legible. -6. Inspect print preview for expanded detail, clipping, missing diagrams, and wasteful page breaks. +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. If browser inspection is unavailable, validate document structure and scripts as far as the environment allows, then mark visual acceptance incomplete in both the report and handoff. +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. From 3e0b1b808bc4dfbbd00aa448a8f40f3247790bae Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 20:11:51 +0100 Subject: [PATCH 51/52] feat(define-product): prioritize feature-led discovery --- CONTEXT.md | 2 +- skills/define-product/SKILL.md | 32 ++++++---- .../define-product/assets/product-template.md | 51 +++++----------- skills/define-product/references/DISCOVERY.md | 58 ++++++++++--------- 4 files changed, 67 insertions(+), 76 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 5bf01a2..8f46112 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -66,7 +66,7 @@ _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 Product Vision Board workflow that composes contextual elicitation and conditional research to maintain an evidence-aware root `PRODUCT.md` and domain language in `CONTEXT.md`. It defines strategic direction and capabilities without becoming a roadmap or implementation plan. +**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 diff --git a/skills/define-product/SKILL.md b/skills/define-product/SKILL.md index 386f0fe..32d42b0 100644 --- a/skills/define-product/SKILL.md +++ b/skills/define-product/SKILL.md @@ -1,6 +1,6 @@ --- name: define-product -description: Defines and maintains a product through confirmed discovery. Use when exploring a new product or documenting and redirecting an existing one. +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. metadata: invocation: user disable-model-invocation: true @@ -8,26 +8,34 @@ disable-model-invocation: true # Define Product -The **Product Vision Board** turns a new idea or existing system into a shared, evidence-aware product definition that guides strategic features without becoming a delivery plan. +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. ## Process -### 1. Inspect the product context +### 1. Inspect existing knowledge -Inspect the request, root `PRODUCT.md` and `CONTEXT.md`, relevant decisions and research, and the smallest representative repository evidence. Select a create or improve branch. For an existing product, treat code and tests as evidence of current behaviour and the user as the authority on intent; expose contradictions between them. The branch, current evidence, and definition boundary are explicit. +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. -### 2. Elicit shared understanding +### 2. Frame the product -Invoke `$elicit-with-context` to reach shared understanding of the vision, users and customers, needs, product type, value proposition, alternatives, differentiating capabilities, business goals, success signals, boundaries, current state, and intended direction. When a dimension is unclear, load only the relevant section of [Discovery Techniques](references/DISCOVERY.md). Invoke `$research` when external evidence could materially resolve a product question or help the user formulate a decision; keep its report authoritative and link applicable findings. Each product dimension is confirmed, supported, or explicitly uncertain. +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. -### 3. Trace strategic value +### 3. Map the whole product -Use **Impact Mapping** to trace every strategic capability or feature concept through an actor and desired behaviour change to a product or business goal. Apply the product-discovery risks of value, usability, feasibility, and viability as a completeness pass. Classify product state as `current`, `confirmed direction`, or `hypothesis`, and evidence as `observed`, `user-confirmed`, `researched`, `hypothesis`, or `unknown`. Remove feature ideas without a strategic trace or retain them as explicit open questions. The definition distinguishes direction from evidence and exposes its risks. +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. -### 4. Write the product definition +### 4. Explore each feature -At `$elicit-with-context`'s final confirmation, create or update the single root `PRODUCT.md` from the [Product Definition Template](assets/product-template.md). Preserve one authoritative meaning for each statement, use canonical terms from `CONTEXT.md`, omit inapplicable template guidance, and keep claims linked to durable evidence. Record high-level capabilities and feature concepts while leaving sequencing, estimates, tickets, implementation, architecture, and feature-level acceptance criteria to downstream work. The living product definition reflects the confirmed contract without overstating certainty. +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. -### 5. Verify the definition +### 5. Walk the catalogue -Verify every current-state claim against cited repository evidence, every direction claim against user confirmation, every strategic feature against its impact trace, and every material uncertainty against the risk pass. Reconcile the finished document with `CONTEXT.md`, applicable ADRs, and research reports. Return changed files, the confirmed current state and direction, supporting research, and unresolved questions. The user receives a coherent product guide ready to inform later feature work. +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. + +### 6. Write the product definition + +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. + +### 7. Verify the definition + +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. diff --git a/skills/define-product/assets/product-template.md b/skills/define-product/assets/product-template.md index 9e34367..f6ff06f 100644 --- a/skills/define-product/assets/product-template.md +++ b/skills/define-product/assets/product-template.md @@ -1,54 +1,35 @@ # {Product name} -{One sentence stating who the product serves, the outcome it enables, and what makes its approach distinct.} _Evidence: {status and source}._ +{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.} ## Vision -{The product's purpose and positive change, independent of a particular implementation.} _Evidence: {status and source}._ +{The product's enduring purpose and positive change, independent of a particular implementation.} -## Current state +## Intended users and needs -{For an existing product, summarise its observed purpose, users, capability groups, lifecycle stage, and material constraints. Cite representative repository evidence. Omit this section for a new product without a current state.} +- **{User or customer}**: {Prioritised need or desired outcome.} -## Users and needs +## Value proposition and market position -| User or customer | Need or desired outcome | Evidence | -| ---------------- | ----------------------- | ------------------- | -| {Distinct actor} | {Prioritised need} | {Status and source} | +{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.} -## Value proposition and differentiation +## Business model, goals, and success signals -{State why each primary user would choose this product over current alternatives, including non-consumption or manual work. Keep differentiators specific and few.} _Evidence: {status and source}._ +{Describe the business model and applicable pricing decisions, then the product or business outcomes that justify investment and the observable signals of progress.} -## Strategic capabilities +## Product boundaries and non-goals -| State | Capability or feature concept | Actor | Desired impact | Product or business goal | Evidence | -| --- | --- | --- | --- | --- | --- | -| {current, confirmed direction, or hypothesis} | {High-level capability} | {Actor} | {Behaviour change or outcome} | {Goal} | {Status and source} | +- {A durable boundary or non-goal and the focus it preserves.} -## Business goals and success signals +<!-- Repeat the following H2 feature-area block for each natural user-facing area. Order areas by the product journey. Do not add an umbrella Features heading. --> -| Goal | Observable success signal | Evidence | -| --- | --- | --- | -| {Desired product or business outcome} | {Measure or observable change} | {Status and source} | +## {Feature area} -## Boundaries and non-goals +{Optional one-sentence orientation when the area's purpose is not clear from its name.} -- {A durable product boundary and why it focuses the definition.} _Evidence: {status and source}._ +### {Feature name} -## Risks and evidence +_Status: {Current | Confirmed direction | Idea}._ -| Risk | Current evidence | Hypothesis or open question | -| ----------- | --------------------- | ------------------------------ | -| Value | {Evidence or unknown} | {Material uncertainty or none} | -| Usability | {Evidence or unknown} | {Material uncertainty or none} | -| Feasibility | {Evidence or unknown} | {Material uncertainty or none} | -| Viability | {Evidence or unknown} | {Material uncertainty or none} | - -## Open questions - -- {Unresolved question, why it matters, and the evidence that could resolve it.} - -## Evidence - -- [{Repository artifact or research report}]({relative path}) — {Claim or decision it supports.} +{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.} diff --git a/skills/define-product/references/DISCOVERY.md b/skills/define-product/references/DISCOVERY.md index 6e665f9..dce55d9 100644 --- a/skills/define-product/references/DISCOVERY.md +++ b/skills/define-product/references/DISCOVERY.md @@ -1,49 +1,51 @@ # Discovery Techniques -Load only the technique needed by the active elicitation branch. These methods support product-specific discovery; `$elicit-with-context` remains authoritative for questioning, confirmation, language, and qualifying architecture decisions. +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. ## Establish an existing product -Use **repository archaeology** to recover observed behaviour before asking the user to restate it. Start with root documentation and manifests, then sample user entry points, routes or commands, public contracts, data boundaries, tests, and operational configuration. Follow evidence only until the major actors and capability groups are stable. Treat absence from the repository as unknown rather than proof, distinguish shipped behaviour from abandoned or planned code, and present contradictions with stated intent for resolution. +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. -## Shape the product strategy +## Complete the product frame -Use the **Product Vision Board** in needs-first order after establishing the vision: +Use the **Product Vision Board** as a completeness check for the concise opening: -1. State the positive change and enduring purpose. -2. Separate users, customers, and other influential actors. -3. Identify and prioritise their main needs or desired outcomes. -4. Describe the product type and the few capabilities that make it stand out. -5. Define the product or business outcomes that justify investment. +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? -For an existing product, distinguish the observed current strategy from the user's confirmed future strategy instead of blending them. +Keep this frame proportionate to its supporting role. Move into whole-product feature discovery once these dimensions are clear. -## Clarify users and value +## Map the big picture -When needs or differentiation remain vague, use the **Value Proposition Canvas** one segment at a time. Ask what the actor is trying to accomplish, which pains or risks obstruct that outcome, which gains define success, and how the product relieves the important pains or creates the important gains. Rank the few that materially influence adoption; preserve unsupported claims as hypotheses. +Use the **mile-wide, inch-deep** pass before local detail: -## Trace strategic features +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. -Use **Impact Mapping** to test each high-level capability or feature concept: +This pass creates a feature surface, not cards, stories, priorities, screens, releases, or architecture. -1. Why: which product or business goal does it support? -2. Who: which actor can help or hinder that goal? -3. How: what observable behaviour or outcome should change? -4. What: which capability might cause or enable that impact? +## Explore a feature -Discard an untraceable feature from the definition or record the missing link as an open question. Keep multiple plausible capabilities as hypotheses; this is strategic scope, not a roadmap, backlog, or implementation specification. +Resolve only the information required by the mini-brief: -## Establish differentiation +- **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? -Compare the product with the alternatives users employ today, including manual work and doing nothing. Invoke `$research` when competitor capabilities, market conditions, standards, regulation, or user evidence would materially change the conclusion. Retain only differentiators that serve a prioritised need and can plausibly influence choice; label the remainder as hypotheses. +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. -## Expose product risk +## Walk the complete catalogue -Test the emerging definition against four product-discovery risks: +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. -- **Value**: users or customers may not choose, adopt, or pay for it. -- **Usability**: users may not understand or successfully use it. -- **Feasibility**: the product may not be buildable with the available technology, skills, time, or constraints. -- **Viability**: it may not work for the organisation, operating model, legal obligations, economics, channels, or brand. +## Establish external position -For each material risk, record the available evidence, the remaining hypothesis, and the smallest evidence that could resolve it. The definition may finish with uncertainty when that uncertainty is visible and actionable. +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`. From 6e6005bb4bfb9af6bf098661df57a3ab69d60b5b Mon Sep 17 00:00:00 2001 From: Adam Hainsworth-Potter <adam@moonpixels.co.uk> Date: Thu, 16 Jul 2026 20:35:40 +0100 Subject: [PATCH 52/52] fix(skills): align invocation policies with coding use --- CONTEXT.md | 4 ++-- skills/commit/SKILL.md | 6 +++--- skills/commit/agents/openai.yaml | 2 +- skills/debug/SKILL.md | 4 ++-- skills/debug/agents/openai.yaml | 2 +- skills/write-skill/references/SECTIONS.md | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTEXT.md b/CONTEXT.md index 8f46112..ecd1e63 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -10,7 +10,7 @@ _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 for skills expected to be invoked often enough that automatic discovery earns its permanent context cost.\ +**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.\ @@ -61,7 +61,7 @@ _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 user-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.\ +**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. diff --git a/skills/commit/SKILL.md b/skills/commit/SKILL.md index 19e39f6..8756033 100644 --- a/skills/commit/SKILL.md +++ b/skills/commit/SKILL.md @@ -1,9 +1,9 @@ --- name: commit -description: Creates coherent Conventional Commits from eligible changed work. Use when the user or an authorised workflow asks to commit ready changes. +description: Creates coherent Conventional Commits from eligible changed work. Use to commit reviewed changes. metadata: - invocation: model -disable-model-invocation: false + invocation: user +disable-model-invocation: true --- # Commit diff --git a/skills/commit/agents/openai.yaml b/skills/commit/agents/openai.yaml index b722eef..9eca7b4 100644 --- a/skills/commit/agents/openai.yaml +++ b/skills/commit/agents/openai.yaml @@ -2,4 +2,4 @@ interface: display_name: 'Commit' short_description: 'Create coherent conventional commits' policy: - allow_implicit_invocation: true + allow_implicit_invocation: false diff --git a/skills/debug/SKILL.md b/skills/debug/SKILL.md index 57e00a0..0e125e7 100644 --- a/skills/debug/SKILL.md +++ b/skills/debug/SKILL.md @@ -2,8 +2,8 @@ name: debug description: Reproduces, isolates, repairs, and verifies code issues. Use when debugging failures, regressions, runtime errors, or incorrect behaviour. metadata: - invocation: user -disable-model-invocation: true + invocation: model +disable-model-invocation: false --- # Debug diff --git a/skills/debug/agents/openai.yaml b/skills/debug/agents/openai.yaml index 4c6d231..bac6c82 100644 --- a/skills/debug/agents/openai.yaml +++ b/skills/debug/agents/openai.yaml @@ -2,4 +2,4 @@ interface: display_name: 'Debug' short_description: 'Debug issues through verified repair' policy: - allow_implicit_invocation: false + allow_implicit_invocation: true diff --git a/skills/write-skill/references/SECTIONS.md b/skills/write-skill/references/SECTIONS.md index 7d3ac9f..572f708 100644 --- a/skills/write-skill/references/SECTIONS.md +++ b/skills/write-skill/references/SECTIONS.md @@ -11,7 +11,7 @@ Include the skill's discovery and invocation contract: - `metadata.invocation` records `user` or `model`. - `disable-model-invocation` and `agents/openai.yaml` use the matching policy. -Use user invocation by default. Use model invocation when composition or broad reuse earns the permanent description context. +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` | | ---------- | -------------------------- | ---------------------------------- |