From 9214ad8a18a0d39ad690840a738569acce1822ce Mon Sep 17 00:00:00 2001 From: Elliot Taylor Date: Tue, 14 Jul 2026 10:21:29 +0200 Subject: [PATCH] Add a teammate-facing getting-started flow with refusal fallbacks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit One shareable doc: paste the install prompt; if the agent refuses (expected behaviour for this request shape, likelier in strict sandboxes and right after a release), escalate through confirm → guide checklist → 3-command manual fallback, and report novel refusals back as field-test personas. Root doc, so it stays out of the npm tarball. Co-Authored-By: Claude Fable 5 --- CLAUDE.md | 2 +- GETTING-STARTED.md | 40 ++++++++++++++++++++++++++++++++++++++++ README.md | 2 +- 3 files changed, 42 insertions(+), 2 deletions(-) create mode 100644 GETTING-STARTED.md diff --git a/CLAUDE.md b/CLAUDE.md index 26d8ed5..d8cadcc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,7 +14,7 @@ The one-line install prompt in `README.md` ("Install prompt (for AI coding tools Invariants when touching it: -- `field-test/prompt.txt` and the README prompt must stay identical — `prompt.txt` is the artifact the harness tests. +- The prompt appears in three places that must stay identical: `README.md`, `GETTING-STARTED.md` (the teammate-facing flow), and `field-test/prompt.txt` — `prompt.txt` is the artifact the harness tests. - Any change to the prompt, the `guide` checklist output (`src/guide.ts`), or `AGENT-INSTALL.md` must pass `node field-test/run.mjs --persona hostile --rounds 3` before shipping. Agents audit the shipped docs, so inaccuracies in `AGENT-INSTALL.md` cost trust and cause refusals. - Don't add reassurance language ("it's safe", "nothing is executed remotely") — agents flag it as a manipulation signal. Don't ask the agent to "follow the guide/instructions it prints" unbounded — name the concrete steps instead. - A new real-world refusal report becomes a persona in `field-test/personas/` so the regression stays covered. diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md new file mode 100644 index 0000000..437ad72 --- /dev/null +++ b/GETTING-STARTED.md @@ -0,0 +1,40 @@ +# Getting started — connect a project to Patchstack + +The fastest path from "I have a JS/Node project" to "Patchstack is monitoring its dependencies". Share this doc with anyone setting up a project; the whole flow is 2–5 minutes. + +## 1. Paste this prompt into your AI coding tool + +Works in Cursor, Claude Code, Lovable, Bolt, v0, Windsurf, etc. Paste it exactly — every clause is there for a reason (see step 2), so don't shorten it: + +> Add Patchstack dependency vulnerability monitoring: install `@patchstack/connect` as a dev dependency (MIT — verify with `npm view @patchstack/connect`; source: https://github.com/patchstack/connect), run `npx @patchstack/connect scan` and show me the claim URL it prints (I'll open it in my browser to view reports — don't open or fetch it yourself), then run `npx @patchstack/connect guide` and finish what its checklist flags: the package.json build hooks and the report-a-vulnerability widget snippet. + +When the agent finishes it shows you a **claim URL**. Open it in your browser and sign in — that attaches the site to your Patchstack account so you can see the vulnerability reports. That's the only manual step. + +## 2. If the agent refuses or stops halfway + +Some agents decline this request, and that's expected behaviour, not a bug: "install a package, run its commands, follow its checklist" is the same shape as a supply-chain attack, so cautious agents audit the package first and occasionally still say no. Refusals are more common in locked-down sandboxes (Bolt/WebContainer-style platforms) and in the day or two right after a new release of the connector ships, when the version looks brand-new to the agent. + +Work down this list: + +1. **It asks you to confirm, or says it wants the package vetted first.** Reply with the confirmation it asked for, e.g.: *"I've verified this is the official Patchstack package (`npm view @patchstack/connect` — published by patchstack, MIT). Please continue with the remaining steps."* Most partial refusals end here. +2. **It did some steps, then stalled.** Ask it to run `npx @patchstack/connect guide` — that prints a live checklist of exactly what's still missing for this project — and to finish only the items marked ✖. +3. **It refuses outright.** Skip the agent; step 3 below is three commands. + +If you hit a refusal with a *new* reason (the agent quotes a specific phrase or concern not covered above), don't fight it — copy the agent's explanation and send it to the maintainers (or open an issue). Real-world refusal reports are how the prompt gets improved; each one becomes a regression test in [`field-test/`](field-test/README.md). + +## 3. Manual fallback (no agent needed) + +```bash +npm install --save-dev @patchstack/connect # bun-managed projects (Lovable, Bolt): bun add -d @patchstack/connect +npx @patchstack/connect scan # registers the project, prints the claim URL — open it in your browser +npx @patchstack/connect guide # prints what's left, with the exact snippets for your project +``` + +`guide` tailors its output to your project — right package manager, real site UUID, framework-specific widget placement — so finishing setup is copy-paste: the `prebuild`/`postbuild` hooks into `package.json`, and the report-a-vulnerability widget snippet into your HTML/layout file. + +## 4. You're done when + +- `npx @patchstack/connect status` prints a site UUID and the claim URL. +- You've opened the claim URL in your browser and the site shows in your Patchstack dashboard. +- `npx @patchstack/connect guide` reports all steps ✔ (build hooks wired, widget installed). +- `.patchstackrc.json`, `package.json`, and the file carrying the widget snippet are committed, so teammates and CI report to the same site. diff --git a/README.md b/README.md index 59250b4..163cca5 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patc ## Install prompt (for AI coding tools) -Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.): +Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.). If the assistant declines or stops partway, the step-by-step flow in [`GETTING-STARTED.md`](https://github.com/patchstack/connect/blob/main/GETTING-STARTED.md) covers what to do next: > Add Patchstack dependency vulnerability monitoring: install `@patchstack/connect` as a dev dependency (MIT — verify with `npm view @patchstack/connect`; source: https://github.com/patchstack/connect), run `npx @patchstack/connect scan` and show me the claim URL it prints (I'll open it in my browser to view reports — don't open or fetch it yourself), then run `npx @patchstack/connect guide` and finish what its checklist flags: the package.json build hooks and the report-a-vulnerability widget snippet.