diff --git a/.changes/app-control/refactor-control-skill-contract-9579a1c3.md b/.changes/app-control/refactor-control-skill-contract-9579a1c3.md new file mode 100644 index 00000000000..4e73f4f4c74 --- /dev/null +++ b/.changes/app-control/refactor-control-skill-contract-9579a1c3.md @@ -0,0 +1,7 @@ +--- +bump: minor +--- + +### Changed + +- Moved the control-skill contract to `reference/control-skill.md` at plugin level. Feature files are now `features/[/]/README.md` with Parts, Sub-features, Entry points, Reset, Drive and Gotchas sections (`## States` is gone), and `/app-control:drive` resolves a feature id to its folder README, then to a legacy `features/.md`. diff --git a/docs/upstream/cursor-pstack.md b/docs/upstream/cursor-pstack.md index db6d4083f8d..d11269dd324 100644 --- a/docs/upstream/cursor-pstack.md +++ b/docs/upstream/cursor-pstack.md @@ -103,7 +103,7 @@ is adopted by this record. | [`prototype`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/prototype.md) | [`prototype:explore-directions`](../../plugins/prototype/skills/explore-directions/SKILL.md) | Partial | Taken: an optional reference pass, offered while the look is still open, that seeds two to four directions from comparable screens (`plugins/prototype/skills/explore-directions/SKILL.md:172-177`), and a handover that pairs each variant with a screenshot when `/playwright:playwright` is available and closes with the variant we would start from (`:217-230`). Re-checked at 23e4138: holds. | none | | [`authoring-a-skill`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md) | [`playbooks:skill-authoring`](../../plugins/playbooks/skills/skill-authoring/SKILL.md) | Partial | Taken: the reply shape, as a three-part closing report for any run that creates or changes a skill (`plugins/playbooks/skills/skill-authoring/SKILL.md:219-228`). Rejected: skipping subjective tests and dropping the reason behind a rule; we keep both. Re-checked at 23e4138: holds. | none | | [`eval`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/eval.md) | [`evals:design`](../../plugins/evals/skills/design/SKILL.md), [`evals:plugin-eval`](../../plugins/evals/skills/plugin-eval/SKILL.md) | Partial | Rejected: a runner and a mandatory cross-family judge. Re-checked at 23e4138: holds. Taken: `evals:design` case authoring states the user's goal, keeps evaluation words out of prompts, fixture paths and slugs, and never grades from the model's own account (`plugins/evals/skills/design/SKILL.md:87-97`). `evals:plugin-eval` spot-reads outputs against verdicts before trusting a delta and ends with a promote or do not promote line (`plugins/evals/skills/plugin-eval/SKILL.md:318`, `:336`). Re-checked at 88d47514b8: holds; the only change is the subagent model-rule line, machinery we drop. | none | -| [`runtime-forensics`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/runtime-forensics.md), [`trace-forensics`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/trace-forensics.md) | [`debugging:analyze-profile`](../../plugins/debugging/skills/analyze-profile/SKILL.md), `debugging:debug` | Adopted (new skill) | Taken: the capture-by-symptom table is guidance for a control skill's `## Capture` (`plugins/app-control/skills/drive/reference/control-skill.md`), and `/app-control:drive capture` records the artifact; `debugging:analyze-profile` turns a trace, CPU profile or heap snapshot into a SQLite file it queries read-only, and hands a large read to a subagent that returns only the result (`plugins/debugging/skills/analyze-profile/SKILL.md:40-91`). Diagnose-only is a fixed rule, not a setting: the skill reports the mechanism at file:line and edits nothing (`:88`). Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; `trace-forensics` reworded its paired-capture step, and `runtime-forensics` is unchanged. Re-checked at 88d47514b8: holds; the only change to each playbook is the subagent model-rule line on its parsing step, machinery we drop. | none | +| [`runtime-forensics`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/runtime-forensics.md), [`trace-forensics`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/trace-forensics.md) | [`debugging:analyze-profile`](../../plugins/debugging/skills/analyze-profile/SKILL.md), `debugging:debug` | Adopted (new skill) | Taken: the capture-by-symptom table is guidance for a control skill's `## Capture` (`plugins/app-control/reference/control-skill.md`), and `/app-control:drive capture` records the artifact; `debugging:analyze-profile` turns a trace, CPU profile or heap snapshot into a SQLite file it queries read-only, and hands a large read to a subagent that returns only the result (`plugins/debugging/skills/analyze-profile/SKILL.md:40-91`). Diagnose-only is a fixed rule, not a setting: the skill reports the mechanism at file:line and edits nothing (`:88`). Re-checked at 23e4138: holds. Re-checked at 118e73b0e1: holds; `trace-forensics` reworded its paired-capture step, and `runtime-forensics` is unchanged. Re-checked at 88d47514b8: holds; the only change to each playbook is the subagent model-rule line on its parsing step, machinery we drop. | none | | [`session-pickup`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/session-pickup.md) | [`session-flow:find-handoff`](../../plugins/session-flow/skills/find-handoff/SKILL.md), [`session-flow:keep-going`](../../plugins/session-flow/skills/keep-going/SKILL.md) | Partial | Taken: `transcript_scope` in `session-flow` (`worktree` by default, `repo`, `all`, the narrower of the user and repository values winning), which `session-flow:find-handoff` and `session-flow:recall` read before a transcript scan (`plugins/session-flow/reference/config.md:18`, `plugins/session-flow/skills/find-handoff/SKILL.md:111`). `session-flow:keep-going` names one of four verdicts for another agent's trail (continue, ship the finished recommendation, ratify, restart) and reports what was inherited versus redone (`plugins/session-flow/skills/keep-going/SKILL.md:118-140`). Re-checked at 23e4138: holds. Re-checked at 88d47514b8: holds; the only change is the subagent model-rule line, machinery we drop. | none | | [`visual-parity`](https://github.com/cursor/plugins/blob/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/poteto-mode/playbooks/visual-parity.md) | [`testing:check-visual-parity`](../../plugins/testing/skills/check-visual-parity/SKILL.md), [`implementation:implement` refactor mode](../../plugins/implementation/skills/implement/context/refactor.md) | Adopted (new skill) | Taken: `testing:check-visual-parity` (`plugins/testing/skills/check-visual-parity/SKILL.md:19`, baseline never edited; `:95` compare) and refactor mode's parity step (`plugins/implementation/skills/implement/context/refactor.md:17`), with a `pixel_tolerance` map in testing.yaml. Re-checked at 23e4138: holds. Refactor mode never edits a test, recorded baseline or harness to turn a run green and asks the user instead (`plugins/implementation/skills/implement/context/refactor.md:21`). | none | | [`correct`](https://github.com/cursor/plugins/tree/88d47514b82e7c44f00f2b2a72ff6dd12158038c/pstack/skills/correct) | [`review:audit-enforceability`](../../plugins/review/skills/audit-enforceability/SKILL.md), the review plugin's [enforcement ladder](../../plugins/review/context/enforcement-ladder.md), `session-flow:retro` codify, `review:ratchet` | Not taken (skill omitted) | New at this pin. Decision: no skill, and nothing taken. Upstream reads a repository's history for mistakes agents keep repeating, groups them into classes once a class recurs, fixes each class at the strongest of five levels (structure, types, a lint whose message names the fix, tests, written rules last), and keeps a table that names the enforcing check beside every rule. Each part already has an owner here. The level order is our enforcement ladder, strongest first from `make-impossible` to `llm-only` (`plugins/review/context/enforcement-ladder.md:19-65`). `review:audit-enforceability` maps one recorded finding to the cheapest rung that can assert it, offers `make-impossible` first for an invalid state, and asks for error text that names the fix (`plugins/review/skills/audit-enforceability/SKILL.md:69-75,145-146`). Encoding a repeated correction is `session-flow:retro` codify's selection rule on the same ladder (`plugins/review/context/enforcement-ladder.md:91`), and failing a change only for new instances of a widespread pattern is `review:ratchet`'s count ceiling (`plugins/review/skills/ratchet/SKILL.md:2`). Not taken, with reasons: building and proving the fix inside the audit, because audit-enforceability proposes a rung and never builds one, leaving the build and its test to the rung's owner (`plugins/review/skills/audit-enforceability/SKILL.md:226`); a rule-to-enforcer table in the agent instructions, because our `AGENTS.md` lists only rules CI does not enforce (`AGENTS.md:93`) and prose that repeats what a check already shows is removed (`plugins/review/context/enforcement-ladder.md:104-111`); and mining commits and review comments as a second input to audit-enforceability, because its input is one findings file the operator names (`plugins/review/skills/audit-enforceability/SKILL.md:36-39`), while correction history belongs to `session-flow:retro` and `session-flow:audit-sessions`. Recheck when someone asks to classify repeated corrections across history with no findings file in hand. Re-checked at 88d47514b8 ([cursor/plugins#633](https://github.com/cursor/plugins/pull/633), landed by `99743e9c15`): holds; only the test level changed, which now fixes a test that passes when its behavior breaks or fails when only internals change (see the `principle-test-behavior-not-implementation` row). The five levels, the class grouping and the rule-to-enforcer table are unchanged, so the owners named above stand. | none | diff --git a/plugins/app-control/README.md b/plugins/app-control/README.md index 3a84466e7e4..1c366eac449 100644 --- a/plugins/app-control/README.md +++ b/plugins/app-control/README.md @@ -18,7 +18,7 @@ project's own control skill. Drive looks for project skills named `control-`. With none, it uses the bundled `run` skill when that skill resolves, else a project-type recipe. Its report says which. -[`reference/control-skill.md`](skills/drive/reference/control-skill.md) defines the shape of a +[`reference/control-skill.md`](reference/control-skill.md) defines the shape of a control skill, [`reference/evidence.md`](skills/drive/reference/evidence.md) the run directory and report, and [`reference/project-types.md`](skills/drive/reference/project-types.md) the fallbacks. diff --git a/plugins/app-control/evals/flat-legacy-feature-id-resolves/case.yaml b/plugins/app-control/evals/flat-legacy-feature-id-resolves/case.yaml new file mode 100644 index 00000000000..809138633fe --- /dev/null +++ b/plugins/app-control/evals/flat-legacy-feature-id-resolves/case.yaml @@ -0,0 +1,32 @@ +schema_version: "1.1" +name: flat-legacy-feature-id-resolves +description: A feature id with only a legacy flat file resolves to features/.md after the grouped folder is found missing, and the run launches nothing +tags: [drive, feature-resolution, legacy] +expected_outcome: "Drive reads the control-shop skill, finds no features/cart/README.md, resolves the id cart to .claude/skills/control-shop/features/cart.md, reads that file, names it in the answer, and launches nothing." +context: + scaffold_script: scaffold.sh +execution: + prompt: "/app-control:drive cart --unattended --out ./evidence. Only resolve the feature file and say which file you read and how many entry points it lists. Launch nothing and run nothing." + allowed_tools: [Read, Glob, Grep, Skill, Bash, Write] + max_turns: 20 + timeout_seconds: 600 +graders: + - name: reads-legacy-file + type: tool_used + tool: Read + input_match: 'features/cart\.md' + min: 1 + arm: both + - name: launches-nothing + type: tool_used + tool: Bash + input_match: 'shop/server\.py' + min: 0 + max: 0 + arm: both + - name: asks-nothing + type: tool_used + tool: AskUserQuestion + min: 0 + max: 0 + arm: both diff --git a/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/cart.md b/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/cart.md new file mode 100644 index 00000000000..541aaef9020 --- /dev/null +++ b/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/cart.md @@ -0,0 +1,21 @@ +# Cart + +A user collects items before paying. + +## Reset + +Delete `shop/data/carts.db` and restart the app. + +## States + +- empty: the basket shows `Your cart is empty` +- filled: the basket lists each item with a quantity + +## Entry points + +- the `Add to cart` button on a product page +- `POST /api/cart/items` + +## Drive + +- Open `/cart`, add the first item, open the basket. diff --git a/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/control-shop.md b/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/control-shop.md new file mode 100644 index 00000000000..82ea5160b5b --- /dev/null +++ b/plugins/app-control/evals/flat-legacy-feature-id-resolves/fixtures/control-shop.md @@ -0,0 +1,25 @@ +--- +description: "Launch, ready-check, capture and clean up the shop app." +--- + +## Launch + +`python3 shop/server.py` + +## Ready + +`curl -fsS http://127.0.0.1:8080/health` + +## Capture + +| Kind | Tool | +|---|---| +| logs | `tail -n 200 shop/server.log` | + +## Cleanup + +Stop the pid recorded at launch. + +## Features + +- Cart | features/cart.md | entry points: 2 diff --git a/plugins/app-control/evals/flat-legacy-feature-id-resolves/scaffold.sh b/plugins/app-control/evals/flat-legacy-feature-id-resolves/scaffold.sh new file mode 100755 index 00000000000..78b8143baea --- /dev/null +++ b/plugins/app-control/evals/flat-legacy-feature-id-resolves/scaffold.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# Seeds the shop app's control skill with one legacy flat feature file, cart. +set -euo pipefail + +here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +mkdir -p .claude/skills/control-shop/features +cp "$here/fixtures/control-shop.md" .claude/skills/control-shop/SKILL.md +cp "$here/fixtures/cart.md" .claude/skills/control-shop/features/cart.md diff --git a/plugins/app-control/evals/grouped-feature-id-resolves/case.yaml b/plugins/app-control/evals/grouped-feature-id-resolves/case.yaml new file mode 100644 index 00000000000..2673ee3fa22 --- /dev/null +++ b/plugins/app-control/evals/grouped-feature-id-resolves/case.yaml @@ -0,0 +1,39 @@ +schema_version: "1.1" +name: grouped-feature-id-resolves +description: A module-qualified feature id resolves to the grouped feature folder's README.md, and the run launches nothing +tags: [drive, feature-resolution] +expected_outcome: "Drive reads the control-shop skill, resolves the id billing/export to .claude/skills/control-shop/features/billing/export/README.md, reads that file, names it in the answer, and launches nothing." +context: + scaffold_script: scaffold.sh +execution: + prompt: "/app-control:drive billing/export --unattended --out ./evidence. Only resolve the feature file and say which file you read and how many entry points it lists. Launch nothing and run nothing." + allowed_tools: [Read, Glob, Grep, Skill, Bash, Write] + max_turns: 20 + timeout_seconds: 600 +graders: + - name: reads-grouped-readme + type: tool_used + tool: Read + input_match: 'features/billing/export/README\.md' + min: 1 + arm: both + - name: reads-no-legacy-file + type: tool_used + tool: Read + input_match: 'features/billing/export\.md|features/export\.md' + min: 0 + max: 0 + arm: both + - name: launches-nothing + type: tool_used + tool: Bash + input_match: 'shop/server\.py' + min: 0 + max: 0 + arm: both + - name: asks-nothing + type: tool_used + tool: AskUserQuestion + min: 0 + max: 0 + arm: both diff --git a/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/control-shop.md b/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/control-shop.md new file mode 100644 index 00000000000..b0d0d8bdd3d --- /dev/null +++ b/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/control-shop.md @@ -0,0 +1,25 @@ +--- +description: "Launch, ready-check, capture and clean up the shop app." +--- + +## Launch + +`python3 shop/server.py` + +## Ready + +`curl -fsS http://127.0.0.1:8080/health` + +## Capture + +| Kind | Tool | +|---|---| +| logs | `tail -n 200 shop/server.log` | + +## Cleanup + +Stop the pid recorded at launch. + +## Features + +- Export invoices | features/billing/export/README.md | entry points: 2 | sources: shop/billing/export/** diff --git a/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/export-README.md b/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/export-README.md new file mode 100644 index 00000000000..f894764061d --- /dev/null +++ b/plugins/app-control/evals/grouped-feature-id-resolves/fixtures/export-README.md @@ -0,0 +1,29 @@ +# Export invoices + +A user downloads their invoices as one CSV file. + +## Parts + +- range: the download covers the chosen date range +- format: the file is comma separated with a header row + +## Sub-features + +none + +## Entry points + +- the `Export` button on the billing page: driven +- `GET /api/invoices.csv`: not driven: the endpoint needs an API key this run lacks + +## Reset + +Delete `shop/data/invoices.db` and restart the app. + +## Drive + +- Open `/billing`, choose `Export`; a file named `invoices.csv` downloads. + +## Gotchas + +- The date range defaults to the current month; an empty month downloads a header-only file. diff --git a/plugins/app-control/evals/grouped-feature-id-resolves/scaffold.sh b/plugins/app-control/evals/grouped-feature-id-resolves/scaffold.sh new file mode 100755 index 00000000000..82b559faaa8 --- /dev/null +++ b/plugins/app-control/evals/grouped-feature-id-resolves/scaffold.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +# Seeds the shop app's control skill with one grouped feature, billing/export. +set -euo pipefail + +here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +mkdir -p .claude/skills/control-shop/features/billing/export +cp "$here/fixtures/control-shop.md" .claude/skills/control-shop/SKILL.md +cp "$here/fixtures/export-README.md" .claude/skills/control-shop/features/billing/export/README.md diff --git a/plugins/app-control/skills/drive/reference/control-skill.md b/plugins/app-control/reference/control-skill.md similarity index 84% rename from plugins/app-control/skills/drive/reference/control-skill.md rename to plugins/app-control/reference/control-skill.md index f66cf9e3a55..f135e6ebedd 100644 --- a/plugins/app-control/skills/drive/reference/control-skill.md +++ b/plugins/app-control/reference/control-skill.md @@ -21,8 +21,15 @@ same way. Drive reads it as data and runs a command only from the section the ac | `## Capture` | For each kind (`trace`, `cpu`, `heap`, `threads`, `screenshot`, `aria`, `video`, `logs`) the tool that records it, or nothing when the project has none | | `## Cleanup` | How to stop what a run started and nothing else | -Below them, an index with one line per `features/.md`: title, file name and entry-point -count. +Below them, an index with one line per feature file, in this form: + +```text +- | features/<module>/<feature>/README.md | entry points: <n> | sources: <glob>[, <glob>] +``` + +`<n>` is the number of lines under the feature's `## Entry points`; `sources` names the globs of +the files that implement the feature. A feature with no module drops that folder: +`features/<feature>/README.md`. ## Writing the Capture section @@ -90,14 +97,21 @@ Manuals, each record a pointer, as-of date and recheck trigger: ## Feature files -`features/<feature>.md`, written from the user's side: +`features/[<module>/]<feature>/README.md`, written from the user's side, with these six H2 +sections in this order: | Section | Holds | |---|---| +| `## Parts` | The distinct behaviors inside the feature, one short line each | +| `## Sub-features` | The features nested inside this one, each a pointer to its own feature file, or `none` | +| `## Entry points` | Where a user starts the feature, one line each. Each line ends `driven` or `not driven: <reason>` | | `## Reset` | How to return the app's own data to a known state | -| `## States` | The states the feature can be in and what shows each | -| `## Entry points` | Where a user starts the feature | | `## Drive` | The steps a user takes, one action per step | +| `## Gotchas` | What has made a run lie or fail before | + +A feature's id is `<feature>`, or `<module>/<feature>` when it sits in a module folder. Drive +resolves an id to `features/<id>/README.md`, then to the legacy `features/<id>.md`. The legacy +file keeps working as written, with its `## States` section, until someone regroups it. ## Driver commands diff --git a/plugins/app-control/skills/drive/SKILL.md b/plugins/app-control/skills/drive/SKILL.md index c5fba02e47b..08158d3bd07 100644 --- a/plugins/app-control/skills/drive/SKILL.md +++ b/plugins/app-control/skills/drive/SKILL.md @@ -46,7 +46,10 @@ keep going. in [reference/project-types.md](reference/project-types.md), found from the repository's own docs and manifests. The report then carries the line `No control skill: drive used <fallback>.` 3. Read no settings file. The shape a control skill follows is - [reference/control-skill.md](reference/control-skill.md). + [control-skill.md](../../reference/control-skill.md). +4. Resolve `<feature>` to its file by id, where the id is `<feature>` or `<module>/<feature>`: + `features/<id>/README.md` first, then the legacy `features/<id>.md`. Neither exists: say so and + stop that feature rather than guess a file. The bundled `run` skill and its deferral to a project skill are upstream specifics. Read them live at <https://code.claude.com/docs/en/skills#run-and-verify-your-app> (as of 2026-10-21; recheck when