capture-config

Propose a machine's hand-edits back into this repo, as a reviewed pull request.

scripts/setup.sh renders repo → machine. This is the inverse: machine → repo. Your job is to run it, read the classified change set with the user, and hand the result to pr-dev. You do not decide what is portable — the script classifies, and the user answers.

Why this is not automatic

Rendering only ever writes files this repo authored. Capture reads files a person edited, so a run can pick up a credential, a path that exists only on one laptop, or another tool's wiring. That is why nothing is adopted without an explicit answer, why secrets are refused rather than skipped, and why the result is a reviewed PR and never a commit on the default branch. Do not try to shortcut any of that.

When to offer it

Offer it — do not wait to be asked — when:

• you have just helped the user hand-edit ~/.claude/settings.json, ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.cursor/, ~/.gemini/ or ~/.config/opencode/, and the change reads like policy rather than a one-off
• scripts/doctor.sh or setup.sh plan reports repo/machine drift and the machine is the side that is right
• the user says a setting "keeps getting lost" between machines

Do not offer it for a repo-scoped .claude/settings.json, and do not offer it when the repo is right and the machine is stale — that is make setup.

The three steps

1. Look first, always

bash scripts/capture-config.sh detect

Never writes. Prints one line per difference with its classification. Read the table with the user before doing anything else. If everything is machine-local, secret or third-party, say so and stop — there is nothing to capture, and that is a good outcome, not a failure.

Add --targets claude (or a comma list) when the user names a platform, and --json when you need to reason about the change set programmatically.

2. Review and adopt

bash scripts/capture-config.sh review

This prompts per hunk on /dev/tty with [y/N/a/q/s], default skip.

If you are running in a session with no terminal, the command prints the change set and adopts nothing — that is correct, not an error. Do not work around it. Either surface the change set to the user and ask which ids they want, then pass them explicitly:

bash scripts/capture-config.sh review --adopt 3,7

…or tell the user to run make capture themselves in their terminal. Naming ids is a decision the user made; there is no --yes and you must not invent one.

Adopted hunks are staged into the canonical source — core/global-rules.md or platforms/<target>/settings.d/ — never into a platform's rendered file. The command then re-runs the renderers and prints the downstream diff, so the user sees what the change does on all five platforms before agreeing to a PR. Walk them through that section; it is the reason this tool exists.

3. Deliver

bash scripts/capture-config.sh deliver

Runs make validate, creates a new local branch capture/<date>-<slug>, makes one commit per platform touched, and writes a PR body naming what was captured, from which machine file, where it now renders, and what was skipped and why. The commits hold only the files review staged (the adoption record's sinks). It refuses, before touching git, when core/ or platforms/ carry any other edit, so an unrelated change can never ride in a capture commit. Anything else already in the index stays out of the commits too.

It does not push and does not open the PR. Show the user the printed gh pr create command, then hand off to /pr-dev if they want it driven. Never merge. Opening and merging are separate decisions.

Reading the classifications

A hunk marked blocked: IP scan hit is blocked on purpose and only that hunk is affected. Do not disable the scan. If the pattern is a false positive, say so and let the user decide; if their employer's name needs adding, point them at ~/.config/tamirs-superpowers/scan-patterns.txt.

Hard rules

• Never adopt on the user's behalf. No terminal means no adoption.
• Never print a refused value, in any form, including "just to confirm".
• Never commit by hand, and never merge. The only commits are the ones deliver makes, on its own new capture/ branch, holding only what review staged. It stops there and does not push. Opening and merging are the user's.
• Never edit a platform's rendered file to make a capture "work" — if a value has no canonical home, that is a gap to report, not to route around.
• Never disable a gate (--adopt is for selecting hunks, not for bypassing a block; a blocked hunk stays blocked).

Verify before reporting done

bash scripts/capture-config.sh detect --json | jq '.summary'
bash tests/test-capture.sh

Report the summary counts and what landed where. If nothing was adopted, say that plainly — a capture run that finds nothing worth keeping is a normal result.

Reference

• Full user guide: docs/user/capture.md
• Classification data per platform: platforms/<target>/capture.conf
• Test cases for this skill: evals/evals.json, evals/trigger-evals.json