backpressured-config

Backpressured — Config

Overview

This is the setup step for the backpressure loop, not the loop itself. Its job is to produce a good BACKPRESSURE.md (the file the [[backpressured]] loop reads as authoritative project customization) and to make sure the MCP servers that loop relies on are installed and healthy.

Run only when the user types /backpressured:config. Do not start it from a /goal, a "backpressure" mention, or your own initiative — that is what disable-model-invocation enforces, and you must honor it.

You detect, then confirm — never silently guess and write. The user owns every value that lands in BACKPRESSURE.md.

What you produce

1. A BACKPRESSURE.md at the project root (created, or edited if one exists).
2. A verified Playwright MCP, plus any auxiliary MCP servers the user opts into, registered in the project's .mcp.json.

Keep the user oriented

This is an interactive setup, so the user should always know what you're doing and why — but don't make them read your work. Give one short, high-level note per phase, framed as conclusions, not process:

• Do: "Scanning the project to find its lint, test, and run commands…" · "Found it — tests run with pnpm test, the app starts via docker compose up. Confirm or correct each below." · "Setting up the Linear MCP — you'll finish sign-in with /mcp after."
• Don't: paste raw file contents, list every path you grepped, narrate each tool call, or think out loud. Report what you concluded, not how you searched.
• Keep secrets, .env contents, and long command output out of the chat — refer to them, never echo them.
• Present findings as a short, confirmable summary and ask in plain language; when you take an action (install an MCP, write the file), say what you did in one line.

Step 1 — Create or edit?

Check for BACKPRESSURE.md at the project root.

• Absent → create mode: run detection (Step 2) and build the file from scratch.
• Present → edit mode (this is also how you "refresh"): read it, summarize back to the user what it currently says, and ask what they want to change. Also re-run detection and the project survey to surface anything new since last time — added scripts, new CI jobs or hooks, new project skills, MCP servers — and offer those as additions. Then edit in place: change only what's new or what the user asks for, and never clobber sections they already approved.

Step 2 — Detect, then confirm (create mode)

Scan the repo and draft proposed values; then walk the user through each, letting them confirm or edit. Ask plainly for anything you cannot detect. Do not write the file until the user has confirmed. If the user confirms nothing worth recording (or cancels), writing no file is a fine outcome — the [[backpressured]] loop treats an absent BACKPRESSURE.md as "use the defaults", so don't manufacture one to feel complete.

What to capture	Where to look
lint command	package.json scripts, Makefile, CI config
test command + how to check coverage	package.json scripts, test runner config, CI
typecheck / verification scripts	package.json scripts, Makefile, a commit_check.sh-style script, CI
benchmark suite(s) + what counts as a regression	bench dirs/scripts, package.json, CI
how to run the app locally (frontend / backend / deps)	docker-compose*, framework markers, README / CONTRIBUTING run instructions, Makefile, existing run skills
how to seed or reset local data	seed scripts (seed, db:seed), fixtures, README / docs/, Makefile, existing skills
credentials/secrets needed to run, seed, or authorize the app, and how to obtain each	.env.example / .env.sample / .env.template, docker-compose environment: / env_file:, README / CONTRIBUTING
shipping convention (open a PR vs. merge from local)	CI config, repo signals — otherwise ask

Gate on reality: no benchmark suite → no benchmark section; no app to run → no run section; not a git/GitHub repo → no shipping section.

The table is a starting point, not a closed list — stay open-minded. Any repeatable check that produces a clear pass/fail is candidate backpressure, even if it isn't named above. Look for project-specific gates in CI workflows (read each job), pre-commit / git hooks (.pre-commit-config.yaml, husky, lint-staged), and Makefile / package.json scripts — e.g. formatting, schema/migration checks, security or dependency scans, accessibility or i18n checks, mutation or contract tests, dead-code or bundle-size budgets, spell-check, license checks. When you spot one, recommend it to the user — what it gates and how to run it — and add the ones they want. The goal is to put every "no" a machine can produce into the loop, not just the usual ones.

If the project has end-to-end (E2E) tests, ask whether they should replace manual testing. The [[backpressured]] loop runs manual testing (Phase 3 — booting the real app and driving it like a user) on every goal by default, and treats a green test suite — E2E included — as no substitute. But some projects have an E2E suite that genuinely drives the running app end-to-end, and the user may prefer to lean on it instead. When you detect one (Playwright, Cypress, Selenium, a test:e2e / make e2e target, etc.), surface it and ask plainly: should this E2E suite replace the loop's manual testing, or run in addition to it? Make the trade-off explicit — opting out means no human-like run of the app per goal. If they opt out, record it in the Skip section in terms the loop recognizes (e.g. "skip manual testing — the make e2e suite covers it end-to-end"); otherwise leave manual testing on. Default to keeping it on unless the user clearly opts out.

Credentials are worth asking about explicitly. Manual testing (Phase 3 of the loop) breaks when seeding, login, or a third-party API needs a key the loop doesn't have. Infer the likely names from the scan above (e.g. env vars in .env.example), then ask the user to confirm what's actually required and how to obtain each — which env var or file it belongs in, and where it comes from (a vault, a teammate, a signup/console page, a seed script). Record what is needed and how to get it — never paste real secret values into BACKPRESSURE.md; it is plain text the loop reads and may be committed. For local test credentials, point to a local .env / .env.local (gitignored) rather than inlining them.

Prefer reusing what already documents this — don't re-derive from scratch. Beyond config files, read the project's narrative instructions: README / CONTRIBUTING / docs/ sections on running locally, seeding, and testing, plus Makefile targets. Also look for existing skills that already teach these steps — in the project (.claude/skills/, a skills/ directory, plugin skills) and your personal/global (~/.claude/skills/) — plus CLAUDE.md, e.g. named skills that run the backend/frontend, seed data, or run tests. When a good doc or skill already exists, point BACKPRESSURE.md at it (reference the skill or doc path) instead of copying its content, and confirm with the user that it's the right source to rely on.

Survey skills and setup — project and global — and bring recommendations. Don't wait to stumble on these — actively enumerate what's available across both locations: project (.claude/skills/, plugin skills, a skills/ dir) and personal/global (~/.claude/skills/), plus agent setup (CLAUDE.md, AGENTS.md), Makefile targets, and package.json scripts / scripts/. Always list the contents of both skills directories; don't assume the project folder is the only one.

Two kinds of skill matter, for different parts of the loop:

• Workflow skills — running the app, seeding, testing. Reference these for the run/seed/test steps above.
• Standards skills — ones that encode best practices, design/style guidelines, or domain conventions (e.g. react-best-practices, design-skills, an accessibility or API-style guide). These are review criteria: recommend wiring them into the loop's review step so its reviewer applies them, and record them in BACKPRESSURE.md.

Form concrete suggestions and put them to the user — e.g. "You have a seed-db skill and a make e2e target (run/seed), and react-best-practices + design-skills skills I'd have the loop's reviewer apply — want all of these referenced in BACKPRESSURE.md?" The user accepts, rejects, or edits each; you add only what they approve.

Step 3 — Verify Playwright (bundled)

Playwright ships with this plugin's .mcp.json, so you verify it rather than install it:

• Run claude mcp list (and claude mcp get playwright) to confirm it is registered and connected.
• Confirm browser binaries exist; if a run fails for missing browsers, offer to run npx playwright install (or npx playwright install chromium).
• If the server is absent (e.g. the plugin is disabled), tell the user how to enable it rather than re-adding it.

Step 4 — Offer auxiliary MCP servers

Ask which of these the project uses (multi-select). For each chosen one, run the claude mcp add command below — --scope project writes the project's .mcp.json so the team shares the config — then tell the user to run /mcp to complete OAuth (you cannot log in for them).

Server	Command	Notes
Linear	claude mcp add --transport http linear https://mcp.linear.app/mcp --scope project	OAuth via /mcp
Notion	claude mcp add --transport http notion https://mcp.notion.com/mcp --scope project	OAuth via /mcp (no bearer token)
Atlassian / Jira	claude mcp add --transport http atlassian https://mcp.atlassian.com/v1/mcp --scope project	OAuth via /mcp; one server covers Jira + Confluence. Verify the endpoint against current Atlassian docs — the form (/v1/mcp vs /v1/mcp/authv2) and the legacy /v1/sse retirement have changed recently.
Figma (remote)	claude mcp add --transport http figma https://mcp.figma.com/mcp --scope project	OAuth via /mcp
Figma (local Dev Mode)	claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp --scope project	Needs the Figma desktop app with Dev Mode + "Enable MCP server" on; no auth

Offer Figma's local Dev Mode server as the alternative for users who prefer the desktop app over the remote one.

Step 5 — Final open-ended questions, then write

After installing, ask for each server: "How should the backpressure loop use this?"

• If the user gives guidance, capture it in their own words in BACKPRESSURE.md.
• If they have nothing specific, install and move on. Do not invent MCP boilerplate — an installed server with no instructions gets no section.

Then, as the last thing before you write, ask the closing open-ended questions — this is required. By now the user has seen what you detected and set up; this is their chance to add what the repo couldn't tell you. Ask it as one scannable batch, and do not write BACKPRESSURE.md until you have:

Last thing before I write this — anything on these? (skip any that don't apply)

• Any flaky or non-blocking CI/GitHub checks I should treat as ignorable?
• Anything I should know about testing this project? (slow suites, services that must be running, order- or environment-sensitive tests)
• Anything you always do to validate a change that isn't captured in a script?
• Any step that looks optional but is actually required to run or trust the app?
• Anything here that's easy to get wrong?

Fold their answers into the right section — flaky → Skip, ritual → Checks / free-form, gotcha → Running the app.

Then write (or edit) BACKPRESSURE.md. It is plain English; organize the parts you captured under predictable headings, omitting any that don't apply:

• Checks — lint / test / coverage / verification commands, benchmark suite(s) + regression criteria.
• Review — project or personal standards skills the loop's reviewer should also apply (e.g. react-best-practices, design-skills), referenced by name/path.
• Running the app — frontend / backend / dependencies / DB seed, plus any credentials needed to run/seed/authorize it and how to obtain each (references and sources, not secret values).
• Shipping — PR vs. local-merge convention.
• Skip — mechanisms to disable, in terms the loop recognizes (e.g. "don't open a PR, we merge from local branches", "skip the visual review — no design specs", "skip manual testing — the make e2e suite covers it end-to-end").
• (Free-form) — any user-provided guidance on how the loop should use installed MCP servers.

Step 6 — Hand off

When you're done (file written, or edit-mode changes applied), close with a short, friendly note covering two things:

• Re-run /backpressured:config any time to update or refresh — it re-detects, re-surveys the project, and edits the existing BACKPRESSURE.md in place. That's the intended way to change a check, add an MCP, or pick up new project setup; it never starts over or discards what you approved.
• Start running with /backpressured:goal <goal> — that's the loop itself. This skill only sets it up; it doesn't run the loop.

Quick Reference

Step	Action
1	Create vs. edit — read an existing BACKPRESSURE.md and ask what to change
2	Detect commands + survey project and ~/.claude/skills/; confirm every value before writing
3	Verify the bundled Playwright MCP (and browser binaries)
4	Offer + claude mcp add --scope project the auxiliary servers the user picks; they run /mcp for OAuth
5	How the loop should use each MCP (optional) → ask the closing open-ended questions (required) → write/edit BACKPRESSURE.md
6	Tell the user they can re-run /backpressured:config to refresh, and start runs with /backpressured:goal

Common Mistakes

Mistake	Reality
Writing BACKPRESSURE.md from detection without confirming	Detection is a draft. The user confirms every value before it lands.
Overwriting an existing BACKPRESSURE.md	Edit mode: change only what the user asks; preserve the rest.
Re-adding Playwright	It's bundled. Verify it; don't claude mcp add it.
Templating "Design source: Figma" because Figma was installed	Installed ≠ documented. Only the user's own guidance goes in the file.
Auto-running on a /goal or "backpressure" mention	This skill runs only on explicit /backpressured:config.
Pasting raw scan output, file contents, or a tool-by-tool transcript into the chat	Narrate at a high level — conclusions, one note per phase. Keep secrets and noise out.
Waiting to stumble on the project's own skills/setup	Actively survey them and bring recommendations for what belongs in BACKPRESSURE.md.

Red Flags — STOP

• About to run because of a /goal or the word "backpressure" — this skill is /backpressured:config only.
• About to write BACKPRESSURE.md before the user confirmed the detected values.
• About to clobber an existing BACKPRESSURE.md instead of editing it.
• About to claim an MCP server is "connected" without checking claude mcp list.
• About to dump raw file contents, secrets, or a tool-by-tool transcript into the chat instead of a high-level note.
• About to write BACKPRESSURE.md (or finish) without having asked the open-ended questions.
• Only looked at the project's .claude/skills/ and forgot your personal ~/.claude/skills/.