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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -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/[<module>/]<feature>/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/<id>.md`.
2 changes: 1 addition & 1 deletion docs/upstream/cursor-pstack.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
2 changes: 1 addition & 1 deletion plugins/app-control/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ project's own control skill.

Drive looks for project skills named `control-<app>`. 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.

Expand Down
Original file line number Diff line number Diff line change
@@ -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/<id>.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
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
39 changes: 39 additions & 0 deletions plugins/app-control/evals/grouped-feature-id-resolves/case.yaml
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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/**
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
Expand Up @@ -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/<feature>.md`: title, file name and entry-point
count.
Below them, an index with one line per feature file, in this form:

```text
- <title> | 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

Expand Down Expand Up @@ -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

Expand Down
5 changes: 4 additions & 1 deletion plugins/app-control/skills/drive/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading