diff --git a/plugins-main/.cursor-plugin/marketplace.json b/plugins-main/.cursor-plugin/marketplace.json index f0c3bd3..e78d804 100644 --- a/plugins-main/.cursor-plugin/marketplace.json +++ b/plugins-main/.cursor-plugin/marketplace.json @@ -123,6 +123,11 @@ "source": "third_party/google-slides", "description": "Create, edit, and render presentations." }, + { + "name": "google-ads", + "source": "third_party/google-ads", + "description": "Report on campaigns, research keywords, and make previewed changes." + }, { "name": "gong", "source": "third_party/gong", @@ -388,6 +393,11 @@ "source": "third_party/x-ads", "description": "Manage ad campaigns, create ads, track conversions, and pull performance stats." }, + { + "name": "meta-ads", + "source": "third_party/meta-ads", + "description": "Manage campaigns, ads, audiences, and catalogs, and pull performance insights." + }, { "name": "attio", "source": "third_party/attio", @@ -572,6 +582,16 @@ "name": "gusto", "source": "third_party/gusto", "description": "Work with payroll, employees, contractors, time off, and reports." + }, + { + "name": "gopuff", + "source": "third_party/gopuff", + "description": "Shop Gopuff from Grok Bot through Gopuff's official MCP server. Sign in with your Gopuff account; Gopuff handles the sign-in, and your searches, carts, and orders go to Gopuff under that account, so any order you place is charged and delivered like a normal Gopuff order.", + "minClientVersions": { + "cursor": "never", + "grokbot": "0.49.0", + "sand": "0.49.0" + } } ] } diff --git a/plugins-main/README.md b/plugins-main/README.md index 8868499..17c115d 100644 --- a/plugins-main/README.md +++ b/plugins-main/README.md @@ -29,6 +29,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `google-docs` | [Google Docs](third_party/google-docs/) | Cursor | Productivity | Read, create, and edit documents. | | `google-sheets` | [Google Sheets](third_party/google-sheets/) | Cursor | Productivity | Read, write, and append spreadsheet data. | | `google-slides` | [Google Slides](third_party/google-slides/) | Cursor | Productivity | Create, edit, and render presentations. | +| `google-ads` | [Google Ads](third_party/google-ads/) | Cursor | Integrations | Report on campaigns, research keywords, and make previewed changes. | | `gong` | [Gong](third_party/gong/) | Cursor | Integrations | Pull account summaries, deal insights, and call briefs. | | `salesforce` | [Salesforce](third_party/salesforce/) | Cursor | Integrations | Query, create, and update records in your org. | | `salesforce-headless-360` | [Salesforce (Headless 360, Beta)](third_party/salesforce-headless-360/) | Cursor | Integrations | Manage records, users, and org setup across Salesforce. | @@ -74,6 +75,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `similarweb` | [Similarweb](third_party/similarweb/) | Cursor | Integrations | Analyze website traffic, audiences, and competitors. | | `xero` | [Xero](third_party/xero/) | Cursor | Integrations | Read and write invoices, contacts, reports, and payroll. | | `x-ads` | [X Ads](third_party/x-ads/) | Cursor | Integrations | Manage ad campaigns, create ads, track conversions, and pull performance stats. | +| `meta-ads` | [Meta Ads](third_party/meta-ads/) | Cursor | Integrations | Manage campaigns, ads, audiences, and catalogs, and pull performance insights. | | `attio` | [Attio](third_party/attio/) | Cursor | Integrations | Search and update CRM records, lists, notes, and tasks. | | `hunter` | [Hunter](third_party/hunter/) | Cursor | Integrations | Find and verify emails, discover companies, and save leads. | | `gamma` | [Gamma](third_party/gamma/) | Cursor | Integrations | Generate presentations, documents, and webpages. | @@ -105,6 +107,7 @@ Official Cursor plugins for popular developer tools, frameworks, and SaaS produc | `finary` | [Finary](third_party/finary/) | Cursor | Integrations | Read your net worth, accounts, holdings, spending, and budgets. | | `tiktok-for-business` | [TikTok for Business](third_party/tiktok-for-business/) | Cursor | Integrations | Manage TikTok ad campaigns, ad groups, ads, audiences, creatives, and reports. | | `gusto` | [Gusto](third_party/gusto/) | Cursor | Integrations | Work with payroll, employees, contractors, time off, and reports. | +| `gopuff` | [Gopuff](third_party/gopuff/) | Cursor | Integrations | Shop Gopuff from Grok Bot through Gopuff's official MCP server. Sign in with your Gopuff account; Gopuff handles the sign-in, and your searches, carts, and orders go to Gopuff under that account, so any order you place is charged and delivered like a normal Gopuff order. | Author values match each plugin’s `plugin.json` `author.name` (Cursor lists `plugins@cursor.com` in the manifest). ## Repository structure diff --git a/plugins-main/harness/pstack/claude-code/.claude-plugin/plugin.json b/plugins-main/harness/pstack/claude-code/.claude-plugin/plugin.json index 199469f..dc9927d 100644 --- a/plugins-main/harness/pstack/claude-code/.claude-plugin/plugin.json +++ b/plugins-main/harness/pstack/claude-code/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "pstack", - "version": "0.15.25", + "version": "0.15.27", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/plugins-main/harness/pstack/claude-code/README.md b/plugins-main/harness/pstack/claude-code/README.md index 8f9af1b..723a594 100644 --- a/plugins-main/harness/pstack/claude-code/README.md +++ b/plugins-main/harness/pstack/claude-code/README.md @@ -129,7 +129,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, pick it | [`/how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. | | [`/why`](./skills/why/SKILL.md) | you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse). | | [`/recall`](./skills/recall/SKILL.md) | you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief. | -| [`/ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in a few plain sentences and small visuals, with just enough context on each action item to make the call. | +| [`/ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long. | | [`/blast-radius`](./skills/blast-radius/SKILL.md) | you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted. | | [`/architect`](./skills/architect/SKILL.md) | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. | | [`/arena`](./skills/arena/SKILL.md) | you want N parallel attempts at the same thing, then to grab the best parts of each. | @@ -149,6 +149,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, pick it | [`/show-me-your-work`](./skills/show-me-your-work/SKILL.md) | you want a reviewable decision trail. logs decisions to a tsv you can commit. | | [`/create-verification-skill`](./skills/create-verification-skill/SKILL.md) | your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform. | | [`/maintain-verification-skill`](./skills/maintain-verification-skill/SKILL.md) | your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections. | +| [`/create-formal-verification-skill`](./skills/create-formal-verification-skill/SKILL.md) | tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change. | | [`/unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. | | [`/bro`](./skills/bro/SKILL.md) | you want the last message restated in plain human language, no jargon. | | [`/technical-writing`](./skills/technical-writing/SKILL.md) | layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages. | diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/01-setup.md b/plugins-main/harness/pstack/claude-code/docs/guide/01-setup.md index e28f5cb..2c2ef34 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/01-setup.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/01-setup.md @@ -12,6 +12,8 @@ In a Cursor chat, run: Cursor confirms the plugin is installed. +In Claude Code, run `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. Claude Code prefixes plugin commands, so each command in this guide takes a `pstack:` prefix there, such as `/pstack:setup-pstack`, which writes its model rule to `~/.claude/rules/pstack-models.md`. The [Claude Code adapter](../harness/claude-code.md) covers the other differences. + ## Pick your models Run: @@ -28,7 +30,7 @@ You only override what you care about. A role with no line in the rule keeps the You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm. -## Accept the verification offer, or don't +## Accept the verification offers, or don't At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). @@ -36,6 +38,8 @@ Say yes and it writes `.cursor/skills/verify-/`, a project-local skill that If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most. +Then setup offers once to generate a formal verification skill with [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md), unless the project already has one. Tests check the cases someone thought to write. A formal verification skill checks one key property of your code, such as "a job never runs twice at once", in every case within a stated scope. Say yes when your code has concurrency, retries, a state machine, or a parser, where a bug is costly and tests rarely reach the case that breaks. Otherwise say no, and run it later if that changes. [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers it. + After setup, start a new chat. The model rule applies to new sessions. ## Keep the cost in check diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/02-poteto-mode.md b/plugins-main/harness/pstack/claude-code/docs/guide/02-poteto-mode.md index 0e6568e..db16b5e 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/02-poteto-mode.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/02-poteto-mode.md @@ -25,7 +25,7 @@ flowchart TD J --> K ``` -The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set. +The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, opening a PR, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set. ## Say the goal, not the ceremony @@ -64,7 +64,15 @@ For a noisy report, such as a long thread or a vague bug, make the restatement t /poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. ``` -A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. +A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. For the restatement alone, with no playbook, run [`/in-your-own-words`](../../skills/in-your-own-words/SKILL.md). It restates what the agent thinks your goals are and what problem you're trying to solve. + +When you're unsure whether a task is aimed right, put [`/sharpen`](../../skills/sharpen/SKILL.md) in front of it: + +```text +/sharpen write a migration guide for the v2 config format. +``` + +Before it starts, the agent asks how a top expert would do the task, what you're really after, and whether the ask is over- or underspecified. It drops constraints that don't serve the goal as readily as it adds ones that do, leaves your choices open, and keeps one outside check that the result is right. Then it does the work. ## Follow up short diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/06-verify-and-ship.md b/plugins-main/harness/pstack/claude-code/docs/guide/06-verify-and-ship.md index 2fa0c8d..62a0a05 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/06-verify-and-ship.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/06-verify-and-ship.md @@ -1,6 +1,6 @@ # Verify the result and open a PR -"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, opening the PR, and driving it to merged. +"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, formally verifying a property tests rarely reach, opening the PR, and driving it to merged. Verification is the slowest step in most agent work, because it's the step that usually waits on a human. Make the agent able to do it, and you stop being the bottleneck. Skip it, and running more agents only gets you more unchecked work to review. @@ -58,7 +58,7 @@ The UI bullet above hides a real requirement. The agent needs a scripted way to [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) interviews the repository, not you. It works out what a user touches, how the app launches locally, what can drive it (an existing harness first, otherwise browser and CDP, a PTY, or plain HTTP), what evidence proves behavior, and whether two instances can run side by side. It asks you only what the code can't answer. -It writes `.cursor/skills/verify-/`, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, plus a feature map under `features/` that indexes what the app does and what result proves each feature works. The skill ships a [worked feature-map example](../../skills/create-verification-skill/references/feature-map-example/) with a README index and one file per feature using the four required H2s. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up. If that proof fails, don't use the output. +It writes `.cursor/skills/verify-/`, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, a Helpers section for any script it ships, plus a feature map under `features/` that indexes what the app does and what result proves each feature works. The skill ships a [worked feature-map example](../../skills/create-verification-skill/references/feature-map-example/) with a README index and one file per feature using the four required H2s. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up, then confirm the evidence survived the cleanup. If that proof fails, don't use the output. From then on, "verify it in the app" is a step any agent can execute, in this repo, with no setup conversation. Name it in the prompt when you want the proof in a specific form: @@ -93,6 +93,26 @@ Apps change, and feature maps go out of date. Run this at least once a day, idea [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means one PR of proven corrections, confined to the verification skill's own directory. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of hiding it with a doc edit. +## Prove a property with a formal verification skill + +A verification skill proves the paths you drive. Some bugs live on paths nobody drives: two retries that overlap, a lock that expires mid-write, a state change that arrives out of order. Tests rarely reach those cases. For code where such a bug is costly, run: + +```text +/create-formal-verification-skill +``` + +[`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md) picks the target from the code: a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. It picks the strongest target, not the easiest to verify. Name an area or a bug to start there instead: + +```text +/create-formal-verification-skill the job lease and retry logic. a job must never run twice at once. +``` + +The question picks the tool. Whether events can happen in a bad order suits a model checker over a small model of the design. Whether the code behaves for every input suits a verifier that runs on the code. A property that must hold at every size can need a proof. The agent tells you which tool it chose and why. + +It verifies one property and shows that property failing on a broken variant of the code, because a check you've never seen fail proves nothing. When the current code already breaks the property, you get the counterexample as a short sequence of steps in your code's terms. The property stays as stated, so the finding stays a finding. Product code doesn't change unless you ask. + +It writes a project-local skill that tells the next agent whether a change touches the verified code, how to run the check with one command, and how to tell a real bug from a modeling error. Before handing it over, the generator follows that skill once on a scratch change that breaks the property, and the check must catch it. The handoff says what was verified, with which tool and bounds, what the check found, and what it doesn't cover. A pass covers the model or the bound, not the whole system. + ## Open the PR ```text @@ -109,7 +129,7 @@ An open PR starts collecting blockers immediately. Checks fail, reviewers commen /poteto-mode babysit this pr. get it green. ``` -Babysit watches the PR with a bundled watcher and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop: +Babysit watches the PR, with a bundled watcher on GitHub or the Origin CLI when it's available, and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop: ```text /poteto-mode check on pr 123. anything outstanding? diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/07-overnight.md b/plugins-main/harness/pstack/claude-code/docs/guide/07-overnight.md index 043ea51..9484667 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/07-overnight.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/07-overnight.md @@ -67,6 +67,8 @@ When you're back, ask for the run in review form: Before the skill hands back its summary, it spawns a reviewer on a different model family to read the trail and the transcript, and the reply ends with an Attention section listing what deserves your scrutiny. Read that section first, then the log rows it points at. You're auditing decisions, not re-reading the whole night. +For a quick status instead of an audit, run [`/ketchup`](../../skills/ketchup/SKILL.md) in the chat that ran the work. It reads only, and tells you in plain words what changed since your last message, with the screenshots and small diagrams the work produced. Then it lists each call waiting on you, such as a merge, an approval, or a choice between options, with its pick, the evidence, and the risk, so you can decide from the reply alone. + ## When the night holds a queue, not a task The contract above drives one task to one finish condition. Some nights hold more, a queue of independent changes or a whole program. Three playbooks scale the same trust up. diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/09-make-it-yours.md b/plugins-main/harness/pstack/claude-code/docs/guide/09-make-it-yours.md index cb3c201..457341a 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/09-make-it-yours.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/09-make-it-yours.md @@ -59,7 +59,7 @@ When you already know the workflow you want to capture: Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md), which routes through Cursor's built-in `create-skill`, validates the frontmatter and links, and ships the result through the Opening a PR playbook. Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction some future agent follows. Let the playbook hold that bar rather than writing a `SKILL.md` freehand. -One special case has its own generator. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both. +Two special cases have their own generators. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. A skill that checks a property of your code with a model checker, a proof, or another verifier is a formal verification skill, so use [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md). [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both kinds. ## Write docs to a standard with `/technical-writing` diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/10-recipes-and-pitfalls.md b/plugins-main/harness/pstack/claude-code/docs/guide/10-recipes-and-pitfalls.md index 6d2ef46..fb4743c 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/10-recipes-and-pitfalls.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/10-recipes-and-pitfalls.md @@ -18,7 +18,15 @@ Mechanics first, history second. Each skill's report tells you which sources it /poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. ``` -A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. +A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. `/in-your-own-words` asks for the restatement alone, with no playbook. + +## Aim a task before it starts + +```text +/sharpen write the onboarding doc for the new billing service. +``` + +The agent asks how an expert would do the task, what you're really after, and whether the ask says too much or too little. It keeps one outside check that the result is right, then does the work. ## Prototype before you pick @@ -76,6 +84,14 @@ The qualifiers do real work. "don't change anything yet" keeps it read-only, and "if it repros on main" lets the run stop early when the bug is already gone. The video lets you check the fix before you read the diff. +## Prove a property tests rarely reach + +```text +/create-formal-verification-skill the retry queue. a message must never be delivered twice. +``` + +You get one property checked in every case within a stated scope, a counterexample in your code's terms if the code already breaks it, and a project skill the next agent runs on any change to that code. + ## Vet a number before you post it ```text @@ -134,6 +150,14 @@ You rarely need more words. You need the right name, and [the principles page](. That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last message like one human talking to another, no jargon, shorter. Use it when a reply is technically thorough and you still don't know what it said. +## Catch up on a chat you left running + +```text +/ketchup +``` + +[`/ketchup`](../../skills/ketchup/SKILL.md) tells you in plain words what changed since your last message, then lists each call waiting on you with its pick, evidence, and risk. It changes nothing while it reports. + ## The pitfalls - **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default. diff --git a/plugins-main/harness/pstack/claude-code/docs/guide/README.md b/plugins-main/harness/pstack/claude-code/docs/guide/README.md index 627bfb2..17422b9 100644 --- a/plugins-main/harness/pstack/claude-code/docs/guide/README.md +++ b/plugins-main/harness/pstack/claude-code/docs/guide/README.md @@ -9,7 +9,7 @@ Here's what you'll learn: 3. [Understand the code](./03-understand.md). A read-only investigation, then `/how`, `/why`, `/teach`, and `/recall` before you edit anything. 4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, `/interrogate`, prototypes, and plans before code locks in a shape. 5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`. -6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged. +6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, formally verify what tests rarely reach, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged. 7. [Run work while you sleep](./07-overnight.md). Trust before loops, an overnight contract, a decision log you can audit, and Projects and automations that scale past one agent. 8. [Steer with principle names](./08-principles.md). The 24 names that redirect an agent mid-task. 9. [Make it yours](./09-make-it-yours.md). Your own mode, `/correct` for repeated mistakes, and how to test a skill change. diff --git a/plugins-main/harness/pstack/claude-code/plugin.json b/plugins-main/harness/pstack/claude-code/plugin.json index 199469f..dc9927d 100644 --- a/plugins-main/harness/pstack/claude-code/plugin.json +++ b/plugins-main/harness/pstack/claude-code/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "pstack", - "version": "0.15.25", + "version": "0.15.27", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/plugins-main/harness/pstack/claude-code/skills/create-formal-verification-skill/SKILL.md b/plugins-main/harness/pstack/claude-code/skills/create-formal-verification-skill/SKILL.md new file mode 100644 index 0000000..21fd169 --- /dev/null +++ b/plugins-main/harness/pstack/claude-code/skills/create-formal-verification-skill/SKILL.md @@ -0,0 +1,41 @@ +--- +name: create-formal-verification-skill +description: "Generate a project-local skill that formally verifies the code where a bug costs the most and tests reach the least, in any language, with whichever verification tool fits. Use for /create-formal-verification-skill, \"model-check this race\", \"prove this invariant\", or when concurrency, retries, state machines, parsers, or unsafe code need more than tests." +disable-model-invocation: true +--- + +# Create a formal verification skill + +A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language. + +## Choose the target from the code + +Answer from the codebase, and ask the user only what you cannot observe. If the user named an area or a bug, start there. + +A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify. + +## Let the question choose the tool + +Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. Whether events can happen in a bad order usually suits a model checker over a small model of the design. Whether the code itself behaves for every input, as with memory safety, overflow, or a data-structure invariant, usually suits a verifier that runs on the code. A property that must hold at every size, where a bound is not enough, can need a proof. For concurrent and distributed designs, TLA+ is often the most useful place to start. Prefer a tool that the repo's developers can install and run, and tell the user why you chose it. + +## What makes it good + +- **True to the code.** Every part of the model or proof points to code that a reviewer can open. What the verification treats as one indivisible step is one indivisible step in the code. Names come from this repo. +- **Able to fail.** A check that you have never seen fail proves nothing. Show each property failing on a broken variant of the code it guards, such as a removed check or a reordered step. +- **Findings stay findings.** When the current code breaks the property, report it with the counterexample in the code's terms. Do not weaken the property or the model until it passes, and do not change product code unless the user asks. +- **Honest about scope.** Say what is verified, under which bounds and assumptions, and what is left out. A pass covers the model or the bound, not the whole system. +- **Readable without the tool.** State the property and the harm in one plain sentence each. Tell a counterexample as a short sequence of steps in the code's words. +- **Cheap to rerun.** One command, a reproducible tool version, and a run short enough that the next agent will use it on every relevant change. +- **Kept in step with the code.** When verified code changes, something tells the next agent that the verification needs another look. + +## Generate the verify skill + +Write a project-local skill with frontmatter that names the area and says when to use it. Without frontmatter, the skill never registers. From the skill alone, the next agent must be able to tell whether a change touches the verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Use this repo's real commands, paths, and nouns, and leave no placeholders. + +## Prove it before you hand off + +Follow the generated skill once, as the next agent would, on a scratch change that breaks the property in the real code. It must catch the break. Then drop the scratch change and confirm that the check is back where it started: passing, or failing only on the findings you will report. A verify skill that was never run is a draft. If the skill misses the break or a step does not run, fix the skill or the verification, not the scratch change. + +## Hand off + +Tell the user what you verified, which tool you used and why, the bounds, what the check found in plain words, how to run it, and what it does not cover. Suggest a second target only if you found a close one. diff --git a/plugins-main/harness/pstack/claude-code/skills/ketchup/SKILL.md b/plugins-main/harness/pstack/claude-code/skills/ketchup/SKILL.md index ebc3e94..9eef27f 100644 --- a/plugins-main/harness/pstack/claude-code/skills/ketchup/SKILL.md +++ b/plugins-main/harness/pstack/claude-code/skills/ketchup/SKILL.md @@ -1,12 +1,12 @@ --- name: ketchup -description: "Catch the user up on what changed in this chat since their last message, in a few plain sentences and small visuals. Give each action item just enough context to make the call. Use for /ketchup." +description: "Catch the user up on what changed in this chat since their last message, in plain words and small visuals. List every item waiting on them with what they need to decide it from the reply alone. Use for /ketchup." disable-model-invocation: true --- # Ketchup -Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it. +Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Then lay out every call waiting on them so they can make it from your reply alone. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it. Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out. @@ -14,24 +14,30 @@ Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentence Keep this turn read-only. Make visuals only from what you already have: do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched. Check each number you will show against the facts it comes from, and say so when you correct one. -An action item is a decision or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one action line, no visual, and skip what happens if the user does not answer. +An action item is a call or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one line and no visual. + +One call can cover many items, such as each PR in a set awaiting merge. For each item, collect its link, what it changes for users, the evidence behind your pick, its risk, and your pick. Write "unknown" for a fact the call needs that you do not know. Leave out a link you do not have. ## Write the reply -Keep the whole reply well under 150 words, not counting visuals. When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list or boxes with nothing connecting them. Never give a fact twice, in text or across visuals. Leave out work that changed nothing for the user. When words run short, cut from what happened before you cut from the action items. +Spend words on the calls, not on the story. Keep what happened under 100 words, not counting pictures, and shorter when less happened. Leave out work that changed nothing for the user. Give each item about 30 words. The reply grows with the number of items: two items need well under 150 words in all, not counting pictures, and thirty need far more. Never cut items or shrink them to stay under a word count: no count in place of a list, and no link in place of an item. A link can add depth, but the reply alone must be enough to decide. -Open with one sentence that says how many things need the user, or that nothing does. If nothing happened and nothing waits on the user, say so and stop. +Open with one short sentence that names what waits on the user, or says nothing does. The action items give the detail. If nothing happened and nothing waits on the user, say so and stop. Then show what happened, pictures first. Embed inline the screenshots and videos the work produced, then any diagram that explains a change. Then sum up in one short bullet per thing the user asked for: what came of it, and whether it is done, still running, failed, or not checked. Write each line the way you would say it out loud: "Search was slow from a missing index", not "Search review: done" or "Slow search: missing index". Name any bug found and fixed on the way. Each line must stay true when read alone. Never mark something done that still waits on the user, and leave out anything the action items say. Under the summary, give at most three short lines that change what the user knows or must do. Then name in one line any work left that you can do yourself. -Then list the action items as plain bullets, never as a diagram or box. Give each two lines, or one for an unasked irreversible step: the decision with your recommendation and why, then what happens if the user does not answer. Ask the call the user owns, such as merge, approve, or pick. A step you would take first goes in your recommendation. So does anything that must happen first, and anything that cannot be undone. Write "unknown" for a part you do not know. Link to the detail. +Then list the action items. Ask the call the user owns, such as merge, approve, or pick, and give your pick. A step you would take first goes in your pick. So does anything that must happen first, and anything that cannot be undone. Give the number or link of each PR, issue, or agent a call is about, also in a call between options. + +Fit the shape to the call. A call about one item is one bullet: the call, your pick, what it changes for users, the evidence behind your pick, and its risk, with the item named once. When items share a call, write the call and your pick once, then give each item its own bullet, riskiest first: its link and name, what it changes for users, the evidence behind your pick, and its risk. Name an item's pick only where it differs from the call's. Give each item's risk even when it is low, such as "Low risk: only the colors change." Say what waiting costs only when it is more than a delay, such as a deadline or lost data. -Show a choice after the list. If the screenshots above already show its options, write each option's gain and cost under its screenshot instead of drawing a new visual; otherwise, compare the options side by side, with the current state when there is one. Give every option the work weighed, each with what it gets the user and what it costs. Keep them out of the rest of the text. +For a call between options, give every option the work weighed, each with what it gets the user and what it costs, and the current state when there is one. Those costs are the call's risk, so add no separate risk line. When the screenshots above show the options, write each option's gain and cost under its screenshot. ## Visuals A visual is a picture: a screenshot, a video, a Mermaid diagram, a chart or diagram from `/visualize`, or a generated image. A Markdown table is not a visual, even with before and after columns. +When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list, a list of action items, or boxes with nothing connecting them. Never give a fact twice, in text or across visuals. + Keep each visual small enough to read at a glance: at most six boxes, with at most eight words in each. Write labels as plain words a person would say, not tags like "Tests: pass". A fact that needs a sentence belongs in the text, or nowhere. Embed screenshots and videos inline when the change is visible, not only as links. If a visible change has none, mark its summary line "No screenshot yet," and say there what changed on screen. Draw diagrams and charts from facts you have: a Mermaid diagram for how things connect and a `/visualize` chart for numbers. Never invent a number, and never draw or generate a picture of a screen you did not capture. Link only artifacts that exist. diff --git a/plugins-main/harness/pstack/claude-code/skills/poteto-help/SKILL.md b/plugins-main/harness/pstack/claude-code/skills/poteto-help/SKILL.md index 04a5c3e..fc89d3b 100644 --- a/plugins-main/harness/pstack/claude-code/skills/poteto-help/SKILL.md +++ b/plugins-main/harness/pstack/claude-code/skills/poteto-help/SKILL.md @@ -28,6 +28,7 @@ Check the state that changes the answer, and mention it only when it does: - No `~/.cursor/rules/pstack-models.mdc` means `/setup-pstack` hasn't run for this user, so every role uses its default model. - No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works. +- No formal verification skill in the project means no property is checked past what tests reach. Mention `/create-formal-verification-skill` when the question is about a race, an invariant, or another case tests rarely hit. When the model rule is missing and it matters, ask whether the user wants to pick a model for each role and a reasoning budget now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices: @@ -37,14 +38,16 @@ When the model rule is missing and it matters, ask whether the user wants to pic ## Get set up 1. Install with `/add-plugin pstack` in chat, or from Customize in the sidebar. -2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats. +2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one. 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail. Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md). If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on Auto or a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor. -pstack is built for Cursor. Its skills use the Agent Skills format, so other tools can read them. But most workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, spawn Cursor subagents with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there. +pstack is built for Cursor, and it also installs in Claude Code with `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. There, each command takes a `pstack:` prefix, such as `/pstack:poteto-mode`. The [Claude Code adapter](../../docs/harness/claude-code.md) maps the Cursor names, and a step that needs a Cursor-only feature, such as Bugbot or Automations, is skipped with a one-line note. + +Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, spawn Cursor subagents with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there. ## Start a task with `/poteto-mode` @@ -71,7 +74,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste | Know why code is shaped this way, or where a number came from | [`/why`](../why/SKILL.md) | | Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) | | Catch up on their own recent work on a topic | [`/recall`](../recall/SKILL.md) | -| Catch up on what changed in this chat since their last message, in a few plain sentences and small visuals, with enough context to decide each action item | [`/ketchup`](../ketchup/SKILL.md) | +| Catch up on what changed in this chat since their last message, in plain words and small visuals, with every item waiting on them listed and decidable from the reply alone | [`/ketchup`](../ketchup/SKILL.md) | | Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) | | Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) | | Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) | @@ -85,6 +88,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste | Hear the last reply again in plain words | [`/bro`](../bro/SKILL.md) | | Give agents a scripted way to drive the app and prove behavior | [`/create-verification-skill`](../create-verification-skill/SKILL.md) | | Bring a verification skill and its feature map back in line with the app | [`/maintain-verification-skill`](../maintain-verification-skill/SKILL.md) | +| Formally verify a race, invariant, or other property that tests rarely reach | [`/create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md) | | Vet a performance number before reporting or acting on it | [`/benchmark-checklist`](../benchmark-checklist/SKILL.md) | | Run a large or cross-cutting change, or one to review after stepping away | [`/figure-it-out`](../figure-it-out/SKILL.md) | | Keep a decision log during a run, and review it afterward | [`/show-me-your-work`](../show-me-your-work/SKILL.md) | diff --git a/plugins-main/harness/pstack/claude-code/skills/poteto-help/references/recipes.md b/plugins-main/harness/pstack/claude-code/skills/poteto-help/references/recipes.md index d13da3a..2d78576 100644 --- a/plugins-main/harness/pstack/claude-code/skills/poteto-help/references/recipes.md +++ b/plugins-main/harness/pstack/claude-code/skills/poteto-help/references/recipes.md @@ -34,6 +34,7 @@ Swap in the real paths, skills, and done checks. Informal wording works. ## Review and ship - `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's a real bug or regression.` Read the dismissals too. +- `/create-formal-verification-skill prove holds in , even when interleave or retry.` - `/swarm check every package under against its check script. one worker per package. one report.` - `/poteto-mode open the pr. small ordered commits, evidence in the description.` - `/poteto-mode babysit this pr. get it green.` For status only: `/poteto-mode check on pr . anything outstanding?` @@ -43,6 +44,7 @@ Swap in the real paths, skills, and done checks. Informal wording works. - `/poteto-mode im going to bed. in a fresh worktree off . done means . keep a decision log. don't ask me before committing. /loop until done. if you're truly stuck after a few hours, stop and write up why.` - `/show-me-your-work catch me up on what you did last night.` Read its Attention section first. +- `/ketchup` catches you up on this chat since your last message and lists every call that waits on you. - `/poteto-mode full autopilot on this queue. each item is independent.` - `/poteto-mode autopilot these changes but stack them, don't ship. i'll land the stack.` - `/reflect capture what we learned so the next run doesn't repeat it.` Approve only edits that change a future decision. diff --git a/plugins-main/harness/pstack/claude-code/skills/setup-pstack/SKILL.md b/plugins-main/harness/pstack/claude-code/skills/setup-pstack/SKILL.md index 4b657c2..672bb4b 100644 --- a/plugins-main/harness/pstack/claude-code/skills/setup-pstack/SKILL.md +++ b/plugins-main/harness/pstack/claude-code/skills/setup-pstack/SKILL.md @@ -74,3 +74,7 @@ Tell the user the rule was written and that it applies to new sessions. Re-runni ### 7. Offer a verification skill (optional) Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing. + +### 8. Offer a formal verification skill (optional) + +Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke `/create-formal-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing. diff --git a/plugins-main/harness/pstack/claude-code/skills/sharpen/SKILL.md b/plugins-main/harness/pstack/claude-code/skills/sharpen/SKILL.md index 4f9bb4a..c1cfebe 100644 --- a/plugins-main/harness/pstack/claude-code/skills/sharpen/SKILL.md +++ b/plugins-main/harness/pstack/claude-code/skills/sharpen/SKILL.md @@ -4,4 +4,4 @@ description: "Sharpen a task before starting: the expert approach, what the user disable-model-invocation: true --- -Before starting, ask how a top expert would approach this task (their raw sources, their real methods, an outside check that the result is right), what the user is really after, and whether the task is over- or underspecified. Loosen constraints that don't serve the goal as readily as you add ones that do, and leave choices that are the user's to make open instead of deciding them. Fold in only what makes the work better, not bigger, but always keep one outside check that the result is right, without narrating the framing, then do the work. Don't hand back a rewritten prompt. +Before starting, ask how a top expert would approach this task (their raw sources, their real methods, an outside check that the result is right), what the user is really after, and whether the task is over- or underspecified. Loosen constraints that don't serve the goal as readily as you add ones that do, and leave choices that are the user's to make open instead of deciding them. Fold in only what makes the work better, not bigger, but always keep one outside check that the result is right, without narrating the framing, then do the work. diff --git a/plugins-main/pstack/.cursor-plugin/plugin.json b/plugins-main/pstack/.cursor-plugin/plugin.json index 9172fd0..1b0f0e4 100644 --- a/plugins-main/pstack/.cursor-plugin/plugin.json +++ b/plugins-main/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.15.25", + "version": "0.15.27", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/plugins-main/pstack/README.md b/plugins-main/pstack/README.md index b7ccf6e..40026a5 100644 --- a/plugins-main/pstack/README.md +++ b/plugins-main/pstack/README.md @@ -129,7 +129,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, pick it | [`/how`](./skills/how/SKILL.md) | you want a walkthrough of how a subsystem works. | | [`/why`](./skills/why/SKILL.md) | you want to know why something was built this way. discovers available MCPs at run time and queries each evidence category in parallel (source control, issue tracker, long-form docs, real-time chat, infra observability, error tracking, analytics warehouse). | | [`/recall`](./skills/recall/SKILL.md) | you're starting or resuming work and want your recent context on a topic rebuilt from your own chat history and the shared record, handed back as a tight current-state brief. | -| [`/ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in a few plain sentences and small visuals, with just enough context on each action item to make the call. | +| [`/ketchup`](./skills/ketchup/SKILL.md) | you want what changed in this chat since your last message, in plain words and small visuals, with every item waiting on you listed and decidable from the reply alone, even when that makes the reply long. | | [`/blast-radius`](./skills/blast-radius/SKILL.md) | you have a small-looking change and want to know what else it could break, with the one fact it's safe because of proven by running code, not asserted. | | [`/architect`](./skills/architect/SKILL.md) | you're about to write code that crosses a function boundary and want the caller's usage, types, and module shape settled first. | | [`/arena`](./skills/arena/SKILL.md) | you want N parallel attempts at the same thing, then to grab the best parts of each. | @@ -149,6 +149,7 @@ to keep [`/poteto-mode`](./skills/poteto-mode/SKILL.md) on across turns, pick it | [`/show-me-your-work`](./skills/show-me-your-work/SKILL.md) | you want a reviewable decision trail. logs decisions to a tsv you can commit. | | [`/create-verification-skill`](./skills/create-verification-skill/SKILL.md) | your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform. | | [`/maintain-verification-skill`](./skills/maintain-verification-skill/SKILL.md) | your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections. | +| [`/create-formal-verification-skill`](./skills/create-formal-verification-skill/SKILL.md) | tests can't reach the case that breaks a race, retry, state machine, parser, or unsafe code. verifies one property with the tool that fits and generates a project-local skill to recheck it on every change. | | [`/unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. | | [`/bro`](./skills/bro/SKILL.md) | you want the last message restated in plain human language, no jargon. | | [`/technical-writing`](./skills/technical-writing/SKILL.md) | layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages. | diff --git a/plugins-main/pstack/docs/guide/01-setup.md b/plugins-main/pstack/docs/guide/01-setup.md index e28f5cb..2c2ef34 100644 --- a/plugins-main/pstack/docs/guide/01-setup.md +++ b/plugins-main/pstack/docs/guide/01-setup.md @@ -12,6 +12,8 @@ In a Cursor chat, run: Cursor confirms the plugin is installed. +In Claude Code, run `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. Claude Code prefixes plugin commands, so each command in this guide takes a `pstack:` prefix there, such as `/pstack:setup-pstack`, which writes its model rule to `~/.claude/rules/pstack-models.md`. The [Claude Code adapter](../harness/claude-code.md) covers the other differences. + ## Pick your models Run: @@ -28,7 +30,7 @@ You only override what you care about. A role with no line in the rule keeps the You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm. -## Accept the verification offer, or don't +## Accept the verification offers, or don't At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). @@ -36,6 +38,8 @@ Say yes and it writes `.cursor/skills/verify-/`, a project-local skill that If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most. +Then setup offers once to generate a formal verification skill with [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md), unless the project already has one. Tests check the cases someone thought to write. A formal verification skill checks one key property of your code, such as "a job never runs twice at once", in every case within a stated scope. Say yes when your code has concurrency, retries, a state machine, or a parser, where a bug is costly and tests rarely reach the case that breaks. Otherwise say no, and run it later if that changes. [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers it. + After setup, start a new chat. The model rule applies to new sessions. ## Keep the cost in check diff --git a/plugins-main/pstack/docs/guide/02-poteto-mode.md b/plugins-main/pstack/docs/guide/02-poteto-mode.md index 0e6568e..db16b5e 100644 --- a/plugins-main/pstack/docs/guide/02-poteto-mode.md +++ b/plugins-main/pstack/docs/guide/02-poteto-mode.md @@ -25,7 +25,7 @@ flowchart TD J --> K ``` -The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set. +The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, opening a PR, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue or a stack on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set. ## Say the goal, not the ceremony @@ -64,7 +64,15 @@ For a noisy report, such as a long thread or a vague bug, make the restatement t /poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. ``` -A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. +A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix. For the restatement alone, with no playbook, run [`/in-your-own-words`](../../skills/in-your-own-words/SKILL.md). It restates what the agent thinks your goals are and what problem you're trying to solve. + +When you're unsure whether a task is aimed right, put [`/sharpen`](../../skills/sharpen/SKILL.md) in front of it: + +```text +/sharpen write a migration guide for the v2 config format. +``` + +Before it starts, the agent asks how a top expert would do the task, what you're really after, and whether the ask is over- or underspecified. It drops constraints that don't serve the goal as readily as it adds ones that do, leaves your choices open, and keeps one outside check that the result is right. Then it does the work. ## Follow up short diff --git a/plugins-main/pstack/docs/guide/06-verify-and-ship.md b/plugins-main/pstack/docs/guide/06-verify-and-ship.md index 2fa0c8d..62a0a05 100644 --- a/plugins-main/pstack/docs/guide/06-verify-and-ship.md +++ b/plugins-main/pstack/docs/guide/06-verify-and-ship.md @@ -1,6 +1,6 @@ # Verify the result and open a PR -"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, opening the PR, and driving it to merged. +"It compiles" is not evidence. The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) makes the agent check the real artifact before it reports success, and your job is to make "the real artifact" checkable. This page covers stating a finish condition, vetting a measured number, generating a verification skill for your app, formally verifying a property tests rarely reach, opening the PR, and driving it to merged. Verification is the slowest step in most agent work, because it's the step that usually waits on a human. Make the agent able to do it, and you stop being the bottleneck. Skip it, and running more agents only gets you more unchecked work to review. @@ -58,7 +58,7 @@ The UI bullet above hides a real requirement. The agent needs a scripted way to [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) interviews the repository, not you. It works out what a user touches, how the app launches locally, what can drive it (an existing harness first, otherwise browser and CDP, a PTY, or plain HTTP), what evidence proves behavior, and whether two instances can run side by side. It asks you only what the code can't answer. -It writes `.cursor/skills/verify-/`, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, plus a feature map under `features/` that indexes what the app does and what result proves each feature works. The skill ships a [worked feature-map example](../../skills/create-verification-skill/references/feature-map-example/) with a README index and one file per feature using the four required H2s. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up. If that proof fails, don't use the output. +It writes `.cursor/skills/verify-/`, agent-facing instructions with exact Launch, Doctor, Drive, Evidence, and Cleanup sections, a Helpers section for any script it ships, plus a feature map under `features/` that indexes what the app does and what result proves each feature works. The skill ships a [worked feature-map example](../../skills/create-verification-skill/references/feature-map-example/) with a README index and one file per feature using the four required H2s. Before handing it over, the generator proves the skill once end to end: launch, doctor check, drive one feature, capture evidence, clean up, then confirm the evidence survived the cleanup. If that proof fails, don't use the output. From then on, "verify it in the app" is a step any agent can execute, in this repo, with no setup conversation. Name it in the prompt when you want the proof in a specific form: @@ -93,6 +93,26 @@ Apps change, and feature maps go out of date. Run this at least once a day, idea [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) audits the generated skill: one read-only source reader per feature in parallel, then one live pass that drives every mapped feature. It ends in exactly one of three outcomes. `clean` means full coverage and nothing to ship. `changed` means one PR of proven corrections, confined to the verification skill's own directory. `blocked` names the blocker. It never edits product code. If the live pass catches a product regression, it reports the regression instead of hiding it with a doc edit. +## Prove a property with a formal verification skill + +A verification skill proves the paths you drive. Some bugs live on paths nobody drives: two retries that overlap, a lock that expires mid-write, a state change that arrives out of order. Tests rarely reach those cases. For code where such a bug is costly, run: + +```text +/create-formal-verification-skill +``` + +[`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md) picks the target from the code: a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. It picks the strongest target, not the easiest to verify. Name an area or a bug to start there instead: + +```text +/create-formal-verification-skill the job lease and retry logic. a job must never run twice at once. +``` + +The question picks the tool. Whether events can happen in a bad order suits a model checker over a small model of the design. Whether the code behaves for every input suits a verifier that runs on the code. A property that must hold at every size can need a proof. The agent tells you which tool it chose and why. + +It verifies one property and shows that property failing on a broken variant of the code, because a check you've never seen fail proves nothing. When the current code already breaks the property, you get the counterexample as a short sequence of steps in your code's terms. The property stays as stated, so the finding stays a finding. Product code doesn't change unless you ask. + +It writes a project-local skill that tells the next agent whether a change touches the verified code, how to run the check with one command, and how to tell a real bug from a modeling error. Before handing it over, the generator follows that skill once on a scratch change that breaks the property, and the check must catch it. The handoff says what was verified, with which tool and bounds, what the check found, and what it doesn't cover. A pass covers the model or the bound, not the whole system. + ## Open the PR ```text @@ -109,7 +129,7 @@ An open PR starts collecting blockers immediately. Checks fail, reviewers commen /poteto-mode babysit this pr. get it green. ``` -Babysit watches the PR with a bundled watcher and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop: +Babysit watches the PR, with a bundled watcher on GitHub or the Origin CLI when it's available, and takes blockers in order: conflicts, then review threads, then CI. Every known fix batches into one push, so the checks restart once instead of after every fix. The comment triage is skeptical, because humans and bots file real catches and noise in the same list. A real finding gets a fix, and noise gets dismissed with the disproof posted on the thread. When all you want is status, ask smaller and Babysit answers without starting the loop: ```text /poteto-mode check on pr 123. anything outstanding? diff --git a/plugins-main/pstack/docs/guide/07-overnight.md b/plugins-main/pstack/docs/guide/07-overnight.md index 625144b..dd4230d 100644 --- a/plugins-main/pstack/docs/guide/07-overnight.md +++ b/plugins-main/pstack/docs/guide/07-overnight.md @@ -67,6 +67,8 @@ When you're back, ask for the run in review form: Before the skill hands back its summary, it spawns a reviewer on a different model family to read the trail and the transcript, and the reply ends with an Attention section listing what deserves your scrutiny. Read that section first, then the log rows it points at. You're auditing decisions, not re-reading the whole night. +For a quick status instead of an audit, run [`/ketchup`](../../skills/ketchup/SKILL.md) in the chat that ran the work. It reads only, and tells you in plain words what changed since your last message, with the screenshots and small diagrams the work produced. Then it lists each call waiting on you, such as a merge, an approval, or a choice between options, with its pick, the evidence, and the risk, so you can decide from the reply alone. + ## When the night holds a queue, not a task The contract above drives one task to one finish condition. Some nights hold more, a queue of independent changes or a whole program. Three playbooks scale the same trust up. diff --git a/plugins-main/pstack/docs/guide/09-make-it-yours.md b/plugins-main/pstack/docs/guide/09-make-it-yours.md index cb3c201..457341a 100644 --- a/plugins-main/pstack/docs/guide/09-make-it-yours.md +++ b/plugins-main/pstack/docs/guide/09-make-it-yours.md @@ -59,7 +59,7 @@ When you already know the workflow you want to capture: Writing a skill matches the [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md), which routes through Cursor's built-in `create-skill`, validates the frontmatter and links, and ships the result through the Opening a PR playbook. Agent-facing prose has a higher bar than human prose, because an unhelpful sentence becomes an instruction some future agent follows. Let the playbook hold that bar rather than writing a `SKILL.md` freehand. -One special case has its own generator. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both. +Two special cases have their own generators. A skill that must drive your app and prove behavior is a verification skill, so use [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md) and [`/maintain-verification-skill`](../../skills/maintain-verification-skill/SKILL.md) instead. A skill that checks a property of your code with a model checker, a proof, or another verifier is a formal verification skill, so use [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md). [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers both kinds. ## Write docs to a standard with `/technical-writing` diff --git a/plugins-main/pstack/docs/guide/10-recipes-and-pitfalls.md b/plugins-main/pstack/docs/guide/10-recipes-and-pitfalls.md index 6d2ef46..fb4743c 100644 --- a/plugins-main/pstack/docs/guide/10-recipes-and-pitfalls.md +++ b/plugins-main/pstack/docs/guide/10-recipes-and-pitfalls.md @@ -18,7 +18,15 @@ Mechanics first, history second. Each skill's report tells you which sources it /poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet. ``` -A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. +A misreading shows up in the restatement, where it costs one message to correct. Keep your own theory to yourself until the agent has stated its own. `/in-your-own-words` asks for the restatement alone, with no playbook. + +## Aim a task before it starts + +```text +/sharpen write the onboarding doc for the new billing service. +``` + +The agent asks how an expert would do the task, what you're really after, and whether the ask says too much or too little. It keeps one outside check that the result is right, then does the work. ## Prototype before you pick @@ -76,6 +84,14 @@ The qualifiers do real work. "don't change anything yet" keeps it read-only, and "if it repros on main" lets the run stop early when the bug is already gone. The video lets you check the fix before you read the diff. +## Prove a property tests rarely reach + +```text +/create-formal-verification-skill the retry queue. a message must never be delivered twice. +``` + +You get one property checked in every case within a stated scope, a counterexample in your code's terms if the code already breaks it, and a project skill the next agent runs on any change to that code. + ## Vet a number before you post it ```text @@ -134,6 +150,14 @@ You rarely need more words. You need the right name, and [the principles page](. That's the whole prompt. [`/bro`](../../skills/bro/SKILL.md) restates the last message like one human talking to another, no jargon, shorter. Use it when a reply is technically thorough and you still don't know what it said. +## Catch up on a chat you left running + +```text +/ketchup +``` + +[`/ketchup`](../../skills/ketchup/SKILL.md) tells you in plain words what changed since your last message, then lists each call waiting on you with its pick, evidence, and risk. It changes nothing while it reports. + ## The pitfalls - **Enumerating skills in the prompt.** "use /how then /architect then /arena" reorders steps the playbook already sequences. State the goal and constraints. Name a skill only to override a default. diff --git a/plugins-main/pstack/docs/guide/README.md b/plugins-main/pstack/docs/guide/README.md index 627bfb2..17422b9 100644 --- a/plugins-main/pstack/docs/guide/README.md +++ b/plugins-main/pstack/docs/guide/README.md @@ -9,7 +9,7 @@ Here's what you'll learn: 3. [Understand the code](./03-understand.md). A read-only investigation, then `/how`, `/why`, `/teach`, and `/recall` before you edit anything. 4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, `/interrogate`, prototypes, and plans before code locks in a shape. 5. [Build and clean the change](./05-build-and-clean.md). The build playbooks, `/tdd`, `/unslop`, and `/no-comments`. -6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged. +6. [Verify and ship](./06-verify-and-ship.md). Prove behavior on the real app, formally verify what tests rarely reach, vet numbers with `/benchmark-checklist`, then open a focused PR and drive it to merged. 7. [Run work while you sleep](./07-overnight.md). Trust before loops, an overnight contract, a decision log you can audit, and Projects and automations that scale past one agent. 8. [Steer with principle names](./08-principles.md). The 24 names that redirect an agent mid-task. 9. [Make it yours](./09-make-it-yours.md). Your own mode, `/correct` for repeated mistakes, and how to test a skill change. diff --git a/plugins-main/pstack/plugin.json b/plugins-main/pstack/plugin.json index 199469f..dc9927d 100644 --- a/plugins-main/pstack/plugin.json +++ b/plugins-main/pstack/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "pstack", - "version": "0.15.25", + "version": "0.15.27", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/plugins-main/pstack/skills/create-formal-verification-skill/SKILL.md b/plugins-main/pstack/skills/create-formal-verification-skill/SKILL.md new file mode 100644 index 0000000..21fd169 --- /dev/null +++ b/plugins-main/pstack/skills/create-formal-verification-skill/SKILL.md @@ -0,0 +1,41 @@ +--- +name: create-formal-verification-skill +description: "Generate a project-local skill that formally verifies the code where a bug costs the most and tests reach the least, in any language, with whichever verification tool fits. Use for /create-formal-verification-skill, \"model-check this race\", \"prove this invariant\", or when concurrency, retries, state machines, parsers, or unsafe code need more than tests." +disable-model-invocation: true +--- + +# Create a formal verification skill + +A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language. + +## Choose the target from the code + +Answer from the codebase, and ask the user only what you cannot observe. If the user named an area or a bug, start there. + +A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify. + +## Let the question choose the tool + +Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. Whether events can happen in a bad order usually suits a model checker over a small model of the design. Whether the code itself behaves for every input, as with memory safety, overflow, or a data-structure invariant, usually suits a verifier that runs on the code. A property that must hold at every size, where a bound is not enough, can need a proof. For concurrent and distributed designs, TLA+ is often the most useful place to start. Prefer a tool that the repo's developers can install and run, and tell the user why you chose it. + +## What makes it good + +- **True to the code.** Every part of the model or proof points to code that a reviewer can open. What the verification treats as one indivisible step is one indivisible step in the code. Names come from this repo. +- **Able to fail.** A check that you have never seen fail proves nothing. Show each property failing on a broken variant of the code it guards, such as a removed check or a reordered step. +- **Findings stay findings.** When the current code breaks the property, report it with the counterexample in the code's terms. Do not weaken the property or the model until it passes, and do not change product code unless the user asks. +- **Honest about scope.** Say what is verified, under which bounds and assumptions, and what is left out. A pass covers the model or the bound, not the whole system. +- **Readable without the tool.** State the property and the harm in one plain sentence each. Tell a counterexample as a short sequence of steps in the code's words. +- **Cheap to rerun.** One command, a reproducible tool version, and a run short enough that the next agent will use it on every relevant change. +- **Kept in step with the code.** When verified code changes, something tells the next agent that the verification needs another look. + +## Generate the verify skill + +Write a project-local skill with frontmatter that names the area and says when to use it. Without frontmatter, the skill never registers. From the skill alone, the next agent must be able to tell whether a change touches the verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Use this repo's real commands, paths, and nouns, and leave no placeholders. + +## Prove it before you hand off + +Follow the generated skill once, as the next agent would, on a scratch change that breaks the property in the real code. It must catch the break. Then drop the scratch change and confirm that the check is back where it started: passing, or failing only on the findings you will report. A verify skill that was never run is a draft. If the skill misses the break or a step does not run, fix the skill or the verification, not the scratch change. + +## Hand off + +Tell the user what you verified, which tool you used and why, the bounds, what the check found in plain words, how to run it, and what it does not cover. Suggest a second target only if you found a close one. diff --git a/plugins-main/pstack/skills/ketchup/SKILL.md b/plugins-main/pstack/skills/ketchup/SKILL.md index ebc3e94..9eef27f 100644 --- a/plugins-main/pstack/skills/ketchup/SKILL.md +++ b/plugins-main/pstack/skills/ketchup/SKILL.md @@ -1,12 +1,12 @@ --- name: ketchup -description: "Catch the user up on what changed in this chat since their last message, in a few plain sentences and small visuals. Give each action item just enough context to make the call. Use for /ketchup." +description: "Catch the user up on what changed in this chat since their last message, in plain words and small visuals. List every item waiting on them with what they need to decide it from the reply alone. Use for /ketchup." disable-model-invocation: true --- # Ketchup -Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it. +Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Then lay out every call waiting on them so they can make it from your reply alone. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it. Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out. @@ -14,24 +14,30 @@ Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentence Keep this turn read-only. Make visuals only from what you already have: do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched. Check each number you will show against the facts it comes from, and say so when you correct one. -An action item is a decision or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one action line, no visual, and skip what happens if the user does not answer. +An action item is a call or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one line and no visual. + +One call can cover many items, such as each PR in a set awaiting merge. For each item, collect its link, what it changes for users, the evidence behind your pick, its risk, and your pick. Write "unknown" for a fact the call needs that you do not know. Leave out a link you do not have. ## Write the reply -Keep the whole reply well under 150 words, not counting visuals. When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list or boxes with nothing connecting them. Never give a fact twice, in text or across visuals. Leave out work that changed nothing for the user. When words run short, cut from what happened before you cut from the action items. +Spend words on the calls, not on the story. Keep what happened under 100 words, not counting pictures, and shorter when less happened. Leave out work that changed nothing for the user. Give each item about 30 words. The reply grows with the number of items: two items need well under 150 words in all, not counting pictures, and thirty need far more. Never cut items or shrink them to stay under a word count: no count in place of a list, and no link in place of an item. A link can add depth, but the reply alone must be enough to decide. -Open with one sentence that says how many things need the user, or that nothing does. If nothing happened and nothing waits on the user, say so and stop. +Open with one short sentence that names what waits on the user, or says nothing does. The action items give the detail. If nothing happened and nothing waits on the user, say so and stop. Then show what happened, pictures first. Embed inline the screenshots and videos the work produced, then any diagram that explains a change. Then sum up in one short bullet per thing the user asked for: what came of it, and whether it is done, still running, failed, or not checked. Write each line the way you would say it out loud: "Search was slow from a missing index", not "Search review: done" or "Slow search: missing index". Name any bug found and fixed on the way. Each line must stay true when read alone. Never mark something done that still waits on the user, and leave out anything the action items say. Under the summary, give at most three short lines that change what the user knows or must do. Then name in one line any work left that you can do yourself. -Then list the action items as plain bullets, never as a diagram or box. Give each two lines, or one for an unasked irreversible step: the decision with your recommendation and why, then what happens if the user does not answer. Ask the call the user owns, such as merge, approve, or pick. A step you would take first goes in your recommendation. So does anything that must happen first, and anything that cannot be undone. Write "unknown" for a part you do not know. Link to the detail. +Then list the action items. Ask the call the user owns, such as merge, approve, or pick, and give your pick. A step you would take first goes in your pick. So does anything that must happen first, and anything that cannot be undone. Give the number or link of each PR, issue, or agent a call is about, also in a call between options. + +Fit the shape to the call. A call about one item is one bullet: the call, your pick, what it changes for users, the evidence behind your pick, and its risk, with the item named once. When items share a call, write the call and your pick once, then give each item its own bullet, riskiest first: its link and name, what it changes for users, the evidence behind your pick, and its risk. Name an item's pick only where it differs from the call's. Give each item's risk even when it is low, such as "Low risk: only the colors change." Say what waiting costs only when it is more than a delay, such as a deadline or lost data. -Show a choice after the list. If the screenshots above already show its options, write each option's gain and cost under its screenshot instead of drawing a new visual; otherwise, compare the options side by side, with the current state when there is one. Give every option the work weighed, each with what it gets the user and what it costs. Keep them out of the rest of the text. +For a call between options, give every option the work weighed, each with what it gets the user and what it costs, and the current state when there is one. Those costs are the call's risk, so add no separate risk line. When the screenshots above show the options, write each option's gain and cost under its screenshot. ## Visuals A visual is a picture: a screenshot, a video, a Mermaid diagram, a chart or diagram from `/visualize`, or a generated image. A Markdown table is not a visual, even with before and after columns. +When something is easier to grasp as a picture than as sentences, draw it: how a design or system works, a PR stack or dependency chain with each PR's state, a before and after of a fix, or options side by side. Never draw a status list, a list of action items, or boxes with nothing connecting them. Never give a fact twice, in text or across visuals. + Keep each visual small enough to read at a glance: at most six boxes, with at most eight words in each. Write labels as plain words a person would say, not tags like "Tests: pass". A fact that needs a sentence belongs in the text, or nowhere. Embed screenshots and videos inline when the change is visible, not only as links. If a visible change has none, mark its summary line "No screenshot yet," and say there what changed on screen. Draw diagrams and charts from facts you have: a Mermaid diagram for how things connect and a `/visualize` chart for numbers. Never invent a number, and never draw or generate a picture of a screen you did not capture. Link only artifacts that exist. diff --git a/plugins-main/pstack/skills/poteto-help/SKILL.md b/plugins-main/pstack/skills/poteto-help/SKILL.md index dc44364..7e83474 100644 --- a/plugins-main/pstack/skills/poteto-help/SKILL.md +++ b/plugins-main/pstack/skills/poteto-help/SKILL.md @@ -26,6 +26,7 @@ Check the state that changes the answer, and mention it only when it does: - No `~/.cursor/rules/pstack-models.mdc` means `/setup-pstack` hasn't run for this user, so every role uses its default model. - No `verify-*` skill or other app harness in the project means agents have no scripted way to drive the app. Mention `/create-verification-skill` when the question is about proving a change works. +- No formal verification skill in the project means no property is checked past what tests reach. Mention `/create-formal-verification-skill` when the question is about a race, an invariant, or another case tests rarely hit. When the model rule is missing and it matters, ask whether the user wants to pick a model for each role and a reasoning budget now. It matters when the user is new, the question is about setup or cost, or the answer depends on which models run. Ask at most once per chat. If the need is also unclear, ask both questions together. Offer two choices: @@ -35,14 +36,16 @@ When the model rule is missing and it matters, ask whether the user wants to pic ## Get set up 1. Install with `/add-plugin pstack` in chat, or from Customize in the sidebar. -2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats. +2. Run [`/setup-pstack`](../setup-pstack/SKILL.md). It asks for a reasoning budget, maps a model to each role, and writes a rule. The rule applies to new chats. Then it offers once each to generate a verification skill and a formal verification skill for the project, unless the project already has one. 3. Start a real task with `/poteto-mode`, a goal, and a check that can pass or fail. Installing changes nothing until the user invokes a skill. Only `/setup-pstack` loads from the user's words. The [README](../../README.md) and [guide page 1](../../docs/guide/01-setup.md) have the details. Offer to word their first prompt with them, per [`references/prompting.md`](references/prompting.md). If cost is the worry, say where the tokens go and how to spend fewer. pstack spends extra tokens on subagents and review panels. Rerun `/setup-pstack` and pick a smaller budget or cheaper models. A role set to `auto` or `inherit-parent` runs on the chat's model, which saves tokens when the chat runs on Auto or a cheaper model. A shorter panel list runs fewer subagents, one for each entry. Save `/poteto-mode` for work that needs rigor. -pstack is built for Cursor. Its skills use the Agent Skills format, so other tools can read them. But most workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, spawn Cursor subagents with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there. +pstack is built for Cursor, and it also installs in Claude Code with `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. There, each command takes a `pstack:` prefix, such as `/pstack:poteto-mode`. The [Claude Code adapter](../../docs/harness/claude-code.md) maps the Cursor names, and a step that needs a Cursor-only feature, such as Bugbot or Automations, is skipped with a one-line note. + +Other tools can read the skills, because they use the Agent Skills format. But most workflow skills, including `/poteto-mode`, `/how`, `/why`, and `/teach`, spawn Cursor subagents with per-role models, and Custom Modes and `/loop` are Cursor features, so those parts may not work there. ## Start a task with `/poteto-mode` @@ -69,7 +72,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste | Know why code is shaped this way, or where a number came from | [`/why`](../why/SKILL.md) | | Understand a change or subsystem, explained plainly | [`/teach`](../teach/SKILL.md) | | Catch up on their own recent work on a topic | [`/recall`](../recall/SKILL.md) | -| Catch up on what changed in this chat since their last message, in a few plain sentences and small visuals, with enough context to decide each action item | [`/ketchup`](../ketchup/SKILL.md) | +| Catch up on what changed in this chat since their last message, in plain words and small visuals, with every item waiting on them listed and decidable from the reply alone | [`/ketchup`](../ketchup/SKILL.md) | | Know what a small diff could break outside itself | [`/blast-radius`](../blast-radius/SKILL.md) | | Settle types and module shape before code that crosses a function boundary | [`/architect`](../architect/SKILL.md) | | Get several attempts at one brief, merged into the best one | [`/arena`](../arena/SKILL.md) | @@ -83,6 +86,7 @@ The default answer is `/poteto-mode`, which runs most of the others when its ste | Hear the last reply again in plain words | [`/bro`](../bro/SKILL.md) | | Give agents a scripted way to drive the app and prove behavior | [`/create-verification-skill`](../create-verification-skill/SKILL.md) | | Bring a verification skill and its feature map back in line with the app | [`/maintain-verification-skill`](../maintain-verification-skill/SKILL.md) | +| Formally verify a race, invariant, or other property that tests rarely reach | [`/create-formal-verification-skill`](../create-formal-verification-skill/SKILL.md) | | Vet a performance number before reporting or acting on it | [`/benchmark-checklist`](../benchmark-checklist/SKILL.md) | | Run a large or cross-cutting change, or one to review after stepping away | [`/figure-it-out`](../figure-it-out/SKILL.md) | | Keep a decision log during a run, and review it afterward | [`/show-me-your-work`](../show-me-your-work/SKILL.md) | diff --git a/plugins-main/pstack/skills/poteto-help/references/recipes.md b/plugins-main/pstack/skills/poteto-help/references/recipes.md index d13da3a..2d78576 100644 --- a/plugins-main/pstack/skills/poteto-help/references/recipes.md +++ b/plugins-main/pstack/skills/poteto-help/references/recipes.md @@ -34,6 +34,7 @@ Swap in the real paths, skills, and done checks. Informal wording works. ## Review and ship - `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's a real bug or regression.` Read the dismissals too. +- `/create-formal-verification-skill prove holds in , even when interleave or retry.` - `/swarm check every package under against its check script. one worker per package. one report.` - `/poteto-mode open the pr. small ordered commits, evidence in the description.` - `/poteto-mode babysit this pr. get it green.` For status only: `/poteto-mode check on pr . anything outstanding?` @@ -43,6 +44,7 @@ Swap in the real paths, skills, and done checks. Informal wording works. - `/poteto-mode im going to bed. in a fresh worktree off . done means . keep a decision log. don't ask me before committing. /loop until done. if you're truly stuck after a few hours, stop and write up why.` - `/show-me-your-work catch me up on what you did last night.` Read its Attention section first. +- `/ketchup` catches you up on this chat since your last message and lists every call that waits on you. - `/poteto-mode full autopilot on this queue. each item is independent.` - `/poteto-mode autopilot these changes but stack them, don't ship. i'll land the stack.` - `/reflect capture what we learned so the next run doesn't repeat it.` Approve only edits that change a future decision. diff --git a/plugins-main/pstack/skills/setup-pstack/SKILL.md b/plugins-main/pstack/skills/setup-pstack/SKILL.md index 90a9e57..cb61b8d 100644 --- a/plugins-main/pstack/skills/setup-pstack/SKILL.md +++ b/plugins-main/pstack/skills/setup-pstack/SKILL.md @@ -72,3 +72,7 @@ Tell the user the rule was written and that it applies to new sessions. Re-runni ### 7. Offer a verification skill (optional) Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing. + +### 8. Offer a formal verification skill (optional) + +Check whether the project already has a formal verification skill (a project skill that runs a model checker, a proof, or another verifier against the code). If not, offer once: "want a formal verification skill, so agents can prove a key property of your code holds in every case in scope, not only the cases tests reach? I can generate one with /create-formal-verification-skill." On yes, invoke `/create-formal-verification-skill` (resolves wherever pstack is installed: workspace, user, or plugin). On no, move on without pushing. diff --git a/plugins-main/pstack/skills/sharpen/SKILL.md b/plugins-main/pstack/skills/sharpen/SKILL.md index 4f9bb4a..c1cfebe 100644 --- a/plugins-main/pstack/skills/sharpen/SKILL.md +++ b/plugins-main/pstack/skills/sharpen/SKILL.md @@ -4,4 +4,4 @@ description: "Sharpen a task before starting: the expert approach, what the user disable-model-invocation: true --- -Before starting, ask how a top expert would approach this task (their raw sources, their real methods, an outside check that the result is right), what the user is really after, and whether the task is over- or underspecified. Loosen constraints that don't serve the goal as readily as you add ones that do, and leave choices that are the user's to make open instead of deciding them. Fold in only what makes the work better, not bigger, but always keep one outside check that the result is right, without narrating the framing, then do the work. Don't hand back a rewritten prompt. +Before starting, ask how a top expert would approach this task (their raw sources, their real methods, an outside check that the result is right), what the user is really after, and whether the task is over- or underspecified. Loosen constraints that don't serve the goal as readily as you add ones that do, and leave choices that are the user's to make open instead of deciding them. Fold in only what makes the work better, not bigger, but always keep one outside check that the result is right, without narrating the framing, then do the work. diff --git a/plugins-main/third_party/google-ads/.cursor-plugin/plugin.json b/plugins-main/third_party/google-ads/.cursor-plugin/plugin.json new file mode 100644 index 0000000..baf0f41 --- /dev/null +++ b/plugins-main/third_party/google-ads/.cursor-plugin/plugin.json @@ -0,0 +1,36 @@ +{ + "name": "google-ads", + "displayName": "Google Ads", + "version": "1.0.0", + "minClientVersions": { + "cursor": "never", + "grokbot": "0.30.0", + "sand": "0.30.0" + }, + "description": "Report on campaigns, research keywords, and make previewed changes.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://github.com/cursor/plugins/tree/main/third_party/google-ads", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "logo": "assets/logo.svg", + "keywords": [ + "google-ads", + "ads", + "advertising", + "google", + "campaigns", + "keywords", + "mcp" + ], + "category": "integrations", + "tags": [ + "google-ads", + "ads", + "advertising", + "mcp" + ], + "mcpServers": "./mcp.json" +} diff --git a/plugins-main/third_party/google-ads/CHANGELOG.md b/plugins-main/third_party/google-ads/CHANGELOG.md new file mode 100644 index 0000000..f25f2ad --- /dev/null +++ b/plugins-main/third_party/google-ads/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to this plugin will be documented here. + +## 1.0.0 - initial release + +- Logo: official Google Ads product icon on a padded white tile. +- Added the `google-ads` MCP server pointing at `https://api.cursor.com/rest-mcp/google-ads/mcp`. diff --git a/plugins-main/third_party/google-ads/LICENSE b/plugins-main/third_party/google-ads/LICENSE new file mode 100644 index 0000000..ca2bba7 --- /dev/null +++ b/plugins-main/third_party/google-ads/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cursor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins-main/third_party/google-ads/README.md b/plugins-main/third_party/google-ads/README.md new file mode 100644 index 0000000..6c34f90 --- /dev/null +++ b/plugins-main/third_party/google-ads/README.md @@ -0,0 +1,39 @@ +# Google Ads + +Cursor plugin that connects Grok Bot to [Google Ads](https://ads.google.com) through Cursor's remote [Model Context Protocol](https://modelcontextprotocol.io/) server. + +Report on accounts and campaigns with GAQL, research keywords and audiences, and make campaign changes. Every change is checked with `validate_mutate` (`validateOnly`) before `mutate` applies it. + +## Install + +1. Open **Grok Bot Settings → Plugins**. +2. Search for **Google Ads**. +3. Click **Install**, then complete the Google sign-in prompt. + +## MCP + +```json +{ + "mcpServers": { + "google-ads": { + "type": "http", + "url": "https://api.cursor.com/rest-mcp/google-ads/mcp" + } + } +} +``` + +Auth is OAuth 2.0 against Google with the `https://www.googleapis.com/auth/adwords` scope. Grok Bot prompts for Google sign-in when the plugin connects. + +## Tools + +- **Reporting:** `list_accessible_customers`, `search`, `search_fields`, `list_billing`, `get_operation` +- **Planning:** `keyword_planner`, `reach_planner`, `audience_insights`, `benchmarks`, `suggest`, `generate_assets` +- **Changes:** `validate_mutate`, `mutate`, `recommendation_action`, `experiment_action`, `upload_conversions` + +## Docs + +- Google Ads API: https://developers.google.com/google-ads/api/docs/start +- GAQL: https://developers.google.com/google-ads/api/docs/query/overview + +Logo is the official Google Ads product icon, placed on a white tile with padding so it reads well in the UI. diff --git a/plugins-main/third_party/google-ads/assets/logo.svg b/plugins-main/third_party/google-ads/assets/logo.svg new file mode 100644 index 0000000..9252bfa --- /dev/null +++ b/plugins-main/third_party/google-ads/assets/logo.svg @@ -0,0 +1 @@ + diff --git a/plugins-main/third_party/google-ads/mcp.json b/plugins-main/third_party/google-ads/mcp.json new file mode 100644 index 0000000..730b3c5 --- /dev/null +++ b/plugins-main/third_party/google-ads/mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "google-ads": { + "type": "http", + "url": "https://api.cursor.com/rest-mcp/google-ads/mcp" + } + } +} diff --git a/plugins-main/third_party/gopuff/.cursor-plugin/plugin.json b/plugins-main/third_party/gopuff/.cursor-plugin/plugin.json new file mode 100644 index 0000000..5af5aaf --- /dev/null +++ b/plugins-main/third_party/gopuff/.cursor-plugin/plugin.json @@ -0,0 +1,36 @@ +{ + "name": "gopuff", + "displayName": "Gopuff", + "version": "1.0.0", + "minClientVersions": { + "cursor": "never", + "grokbot": "0.49.0", + "sand": "0.49.0" + }, + "description": "Shop Gopuff from Grok Bot through Gopuff's official MCP server. Sign in with your Gopuff account; Gopuff handles the sign-in, and your searches, carts, and orders go to Gopuff under that account, so any order you place is charged and delivered like a normal Gopuff order.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://www.gopuff.com", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "logo": "assets/logo.png", + "keywords": [ + "gopuff", + "delivery", + "grocery", + "convenience", + "shopping", + "grok", + "mcp" + ], + "category": "integrations", + "tags": [ + "shopping", + "delivery", + "grok", + "mcp" + ], + "mcpServers": "./mcp.json" +} diff --git a/plugins-main/third_party/gopuff/CHANGELOG.md b/plugins-main/third_party/gopuff/CHANGELOG.md new file mode 100644 index 0000000..4053044 --- /dev/null +++ b/plugins-main/third_party/gopuff/CHANGELOG.md @@ -0,0 +1,5 @@ +# Changelog + +## 1.0.0 + +- Initial release: MCP config for Gopuff's official server at `https://mcp.gopuff.com/mcp`, placed on the server so Grok Bot can dial it, signing in with Gopuff's public OAuth client `mcp-grok-bot`, and listed for Grok Bot only. diff --git a/plugins-main/third_party/gopuff/LICENSE b/plugins-main/third_party/gopuff/LICENSE new file mode 100644 index 0000000..ca2bba7 --- /dev/null +++ b/plugins-main/third_party/gopuff/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cursor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins-main/third_party/gopuff/README.md b/plugins-main/third_party/gopuff/README.md new file mode 100644 index 0000000..be14cea --- /dev/null +++ b/plugins-main/third_party/gopuff/README.md @@ -0,0 +1,15 @@ +# Gopuff + +Connects Grok Bot to Gopuff's official MCP server at +`https://mcp.gopuff.com/mcp`. + +## About this connector + +- **Sign-in:** you sign in with your Gopuff account through Gopuff's own + OAuth server (`https://goauth.gopuff.com`, email magic link or one-time + code). Grok Bot never sees your Gopuff credentials. +- **What you share:** searches, carts, and orders go to Gopuff under your + account. An order you place is charged and delivered like any other Gopuff + order. +- **Disconnect anytime:** remove the account from the plugin's Accounts + section in Grok Bot. diff --git a/plugins-main/third_party/gopuff/assets/logo.png b/plugins-main/third_party/gopuff/assets/logo.png new file mode 100644 index 0000000..12318e4 Binary files /dev/null and b/plugins-main/third_party/gopuff/assets/logo.png differ diff --git a/plugins-main/third_party/gopuff/mcp.json b/plugins-main/third_party/gopuff/mcp.json new file mode 100644 index 0000000..a4be301 --- /dev/null +++ b/plugins-main/third_party/gopuff/mcp.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "gopuff": { + "type": "http", + "url": "https://mcp.gopuff.com/mcp", + "placement": "server", + "auth": { + "CLIENT_ID": "mcp-grok-bot" + } + } + } +} diff --git a/plugins-main/third_party/meta-ads/.cursor-plugin/plugin.json b/plugins-main/third_party/meta-ads/.cursor-plugin/plugin.json new file mode 100644 index 0000000..49bb44d --- /dev/null +++ b/plugins-main/third_party/meta-ads/.cursor-plugin/plugin.json @@ -0,0 +1,38 @@ +{ + "name": "meta-ads", + "displayName": "Meta Ads", + "version": "1.0.0", + "minClientVersions": { + "cursor": "3.13.0" + }, + "description": "Manage campaigns, ads, audiences, and catalogs, and pull performance insights.", + "author": { + "name": "Cursor", + "email": "plugins@cursor.com" + }, + "homepage": "https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-get-started", + "repository": "https://github.com/cursor/plugins", + "license": "MIT", + "logo": "assets/logo.png", + "keywords": [ + "meta", + "facebook", + "instagram", + "ads", + "advertising", + "campaigns", + "audiences", + "catalog", + "insights", + "mcp" + ], + "category": "integrations", + "tags": [ + "meta", + "facebook", + "ads", + "advertising", + "mcp" + ], + "mcpServers": "./mcp.json" +} diff --git a/plugins-main/third_party/meta-ads/CHANGELOG.md b/plugins-main/third_party/meta-ads/CHANGELOG.md new file mode 100644 index 0000000..11f43a2 --- /dev/null +++ b/plugins-main/third_party/meta-ads/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +All notable changes to this plugin will be documented here. + +## 1.0.0 — initial release + +- Added the `meta-ads` MCP server pointing at `https://mcp.facebook.com/ads`. +- OAuth sign-in through Facebook Login for Business using Cursor's Meta app ID as a pre-registered client, because Meta's authorization server does not accept dynamic client registration from Cursor. +- Logo: Meta's mark in Meta blue, on a white tile. diff --git a/plugins-main/third_party/meta-ads/LICENSE b/plugins-main/third_party/meta-ads/LICENSE new file mode 100644 index 0000000..ca2bba7 --- /dev/null +++ b/plugins-main/third_party/meta-ads/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Cursor + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins-main/third_party/meta-ads/README.md b/plugins-main/third_party/meta-ads/README.md new file mode 100644 index 0000000..66e0530 --- /dev/null +++ b/plugins-main/third_party/meta-ads/README.md @@ -0,0 +1,69 @@ +# Meta Ads + +Cursor plugin that connects agents to [Meta's ads platform](https://www.facebook.com/business/ads) through Meta's official hosted [Model Context Protocol](https://modelcontextprotocol.io/) server at `https://mcp.facebook.com/ads`. + +This plugin signs you in with Facebook Login for Business and works with the business portfolios and ad accounts you choose to share. Agents can manage campaigns, ad sets, ads, audiences, and catalogs, and pull performance insights across Facebook and Instagram. + +## Install + +1. Open **Cursor Settings → Plugins**. +2. Search for **Meta Ads**. +3. Click **Install**, then complete the Facebook sign-in when prompted. + +Or run `/add-plugin meta-ads` in chat. + +## MCP + +```json +{ + "mcpServers": { + "meta-ads": { + "type": "http", + "url": "https://mcp.facebook.com/ads", + "auth": { + "CLIENT_ID": "1854843612533787" + } + } + } +} +``` + +## What agents can do + +| Category | Capabilities | +| --- | --- | +| Accounts | Read the ad accounts and business portfolios you shared | +| Insights | Pull performance insights | +| Campaigns | Create, update, and read campaigns | +| Ad sets | Create, update, and read ad sets | +| Ads & creatives | Create and manage ads and creatives | +| Audiences | Read and manage audiences | +| Datasets & pixels | Read and manage datasets and pixels | +| Catalogs | Read and manage product catalogs | + +The hosted server is the source of truth for tool names and schemas. + +## Setup + +No token to paste. The plugin ships Cursor's Meta app ID, because Meta does not accept dynamic client registration from Cursor. A Meta app ID is public, and the plugin needs no client secret. + +On first use, Cursor opens a browser window for Facebook Login for Business. Sign in, pick the business portfolios and ad accounts to share, and approve access. Requests run as you, against only the assets you shared. + +You can revoke access at any time on Facebook under **Settings → Business Integrations**. + +## Notes + +- Meta calls the server beta and rolls it out per ad account and per tool. If a tool reports `is_ads_mcp_enabled = false`, that ad account does not have access yet. +- The server can write, including creating campaigns and changing budgets. Review every tool call before you approve it. +- Calls share the Marketing API's rate limits for each ad account. + +## Docs + +- Ads MCP server, get started: https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-get-started +- Meta Business Help Center: https://www.facebook.com/business/help/1456422242197840 + +Logo is Meta's mark from [Simple Icons](https://simpleicons.org/), in Meta blue (`#0081FB`) on a white tile. + +## License + +MIT diff --git a/plugins-main/third_party/meta-ads/assets/logo.png b/plugins-main/third_party/meta-ads/assets/logo.png new file mode 100644 index 0000000..eed6a88 Binary files /dev/null and b/plugins-main/third_party/meta-ads/assets/logo.png differ diff --git a/plugins-main/third_party/meta-ads/mcp.json b/plugins-main/third_party/meta-ads/mcp.json new file mode 100644 index 0000000..c40760d --- /dev/null +++ b/plugins-main/third_party/meta-ads/mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "meta-ads": { + "type": "http", + "url": "https://mcp.facebook.com/ads", + "auth": { + "CLIENT_ID": "1854843612533787" + } + } + } +} diff --git a/plugins-main/third_party/zoom/.cursor-plugin/plugin.json b/plugins-main/third_party/zoom/.cursor-plugin/plugin.json index 7a0ac4f..9f630f8 100644 --- a/plugins-main/third_party/zoom/.cursor-plugin/plugin.json +++ b/plugins-main/third_party/zoom/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "zoom", "displayName": "Zoom", - "version": "1.0.1", + "version": "1.0.2", "description": "Search meetings, pull transcripts, and work with Zoom Docs.", "author": { "name": "Cursor", @@ -30,13 +30,13 @@ "properties": { "CLIENT_ID": { "type": "string", - "title": "Zoom Client ID", - "description": "Public Client ID (recommended) or Client ID from your Zoom App Marketplace General app → Basic Information → App Credentials. The Public Client ID appears after turning on Use Public Client OAuth." + "title": "Zoom Client ID or Public Client ID", + "description": "A Client Secret is required along with the Client ID. A Public Client ID takes no secret; it appears after turning on Use Public Client OAuth. Copy either from your Zoom App Marketplace General app → Basic Information → App Credentials." }, "CLIENT_SECRET": { "type": "string", - "title": "Zoom Client Secret", - "description": "Optional. Leave blank with a Public Client ID; Cursor then signs in with PKCE and no secret. Only set it alongside the confidential Client ID from the same app." + "title": "Zoom Client Secret (needed with the Client ID)", + "description": "Required along with the Client ID, from the same app's App Credentials. Leave it blank only with a Public Client ID; Cursor then signs in with PKCE and no secret." } }, "required": [ diff --git a/plugins-main/third_party/zoom/CHANGELOG.md b/plugins-main/third_party/zoom/CHANGELOG.md index 20f86f1..5e28457 100644 --- a/plugins-main/third_party/zoom/CHANGELOG.md +++ b/plugins-main/third_party/zoom/CHANGELOG.md @@ -2,6 +2,12 @@ All notable changes to this plugin will be documented here. +## 1.0.2 + +- Setup copy now leads with the Client Secret being required along with the Client ID. Zoom rejects a Client ID sent without its secret with `invalid_client` at the token exchange. +- Retitled the variables "Zoom Client ID or Public Client ID" and "Zoom Client Secret (needed with the Client ID)", and dropped "Optional." from the secret's description. +- README: the setup steps offer the Client ID and Client Secret first and the Public Client ID as the no-secret option, and note that a regenerated secret must be entered again in Cursor. + ## 1.0.1 - Made `CLIENT_SECRET` optional so a Zoom Public Client ID signs in with PKCE and no secret, which is what Zoom requires for the desktop loopback redirect. diff --git a/plugins-main/third_party/zoom/README.md b/plugins-main/third_party/zoom/README.md index 46c1108..a964912 100644 --- a/plugins-main/third_party/zoom/README.md +++ b/plugins-main/third_party/zoom/README.md @@ -8,7 +8,7 @@ Search meetings and recordings, pull summaries and transcripts, and work with Zo 1. Open **Cursor Settings → Plugins**. 2. Search for **Zoom**. -3. Click **Install**, then set the client ID (below) and complete the Zoom sign-in prompt. +3. Click **Install**, then set the Client ID and the Client Secret it requires, or a Public Client ID (below), and complete the Zoom sign-in prompt. Or run `/add-plugin zoom` in chat. @@ -38,13 +38,13 @@ Zoom's MCP servers only support manual client registration — Dynamic Client Re 3. Under **Basic Information → OAuth Information**, register both redirect URIs: - Desktop: `http://127.0.0.1:8787/callback` - Web and Cloud Agents: `https://www.cursor.com/agents/mcp/oauth/callback` -4. Under **Basic Information → App Credentials**, turn on **Use Public Client OAuth** and copy the **Public Client ID**. -5. In **Dashboard → Plugins → Configure**, set **Zoom Client ID** to that Public Client ID and leave **Zoom Client Secret** blank. +4. Under **Basic Information → App Credentials**, copy the **Client ID** and **Client Secret**. A Client Secret is required along with the Client ID. To sign in without a secret instead, turn on **Use Public Client OAuth** and copy the **Public Client ID**. +5. In **Dashboard → Plugins → Configure**, set **Zoom Client ID or Public Client ID** and **Zoom Client Secret** to the values you copied. Leave the secret blank only with the Public Client ID. 6. Complete the Zoom OAuth login when Cursor prompts. -Zoom only accepts a loopback redirect such as `http://127.0.0.1:8787/callback` for a public client, and rejects `localhost` outright. A public client proves each sign-in with PKCE instead of a shared secret, so there is no secret to store or leak. The confidential Client ID and Client Secret pair still works for Web and Cloud Agents, but Zoom refuses its desktop loopback redirect. +If you regenerate the Client Secret in Zoom, enter the new one in Cursor too. Desktop sign-ins through the loopback redirect need the Public Client ID: Zoom accepts `http://127.0.0.1:8787/callback` only for a public client, and rejects `localhost` outright. -Each member needs a license for the Zoom products they want to reach. On a team marketplace an admin sets the client ID once for everyone; each member still completes their own Zoom OAuth login, so tool calls run with that member's Zoom permissions. +Each member needs a license for the Zoom products they want to reach. On a team marketplace an admin sets the credentials once for everyone; each member still completes their own Zoom OAuth login, so tool calls run with that member's Zoom permissions. ## Other Zoom MCP servers