docs: show output path override example

[YOMXXX]

What problem are you trying to solve?

Issue #939 reports that users can define custom output paths in CLAUDE.md, but agents often still follow the concrete defaults in the Superpowers skills and write design specs to docs/superpowers/specs/ and plans to docs/superpowers/plans/.

The maintainer direction in the issue was that the right fix is a README example showing how to override the default. A prior PR (#1020) tried to address this by editing skill behavior text and README together, but it was closed as hacky and untested.

This PR follows the maintainer direction more narrowly: document the workaround in README without changing skill behavior.

What does this PR change?

Adds a Customizing Output Paths section to README.md that shows users how to put an explicit Output Paths section in their project agent instruction file, including the imperative sentence from the working #939 workaround.

It also adds a static README regression check so the example remains present.

Is this change appropriate for the core library?

Yes. This is general user-facing documentation for configuring where Superpowers writes its core artifacts. It is not project-specific, does not add a third-party dependency, and does not change skill behavior or harness integration.

What alternatives did you consider?

I considered editing skills/brainstorming/SKILL.md and skills/writing-plans/SKILL.md to prioritize output path overrides directly, but that repeats the risky part of #1020: behavior-shaping skill edits without eval evidence. The maintainer comment on #939 specifically asked for a README example instead.

I also considered documenting only the table, but the issue reporter's workaround showed that the table alone was not enough. The README example includes both the table and the explicit imperative sentence so users have the tested form.

Does this PR contain multiple unrelated changes?

No. The README section, static README test, and implementation plan all address one documentation gap: how to override the default spec and plan output paths.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: fix(brainstorming): honor CLAUDE.md Output Paths before defaults #1020

PR #1020 is the direct prior attempt. It was closed because it bundled skill text edits with README changes, ignored the PR template, and lacked testing. This PR does not edit skills and includes a static regression test for the README example. I also searched open and closed PRs for Output Paths CLAUDE README override; no open duplicate was found.

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
Local shell tests	zsh on macOS Darwin 24.6.0	n/a	n/a

New harness support (required if this PR adds a new harness)

Not applicable. This PR does not add support for a new harness.

Clean-session transcript for "Let's make a react todo list"

Not applicable: no new harness support is added by this PR.

Evaluation

• Initial prompt/problem source: Brainstorming skill ignores CLAUDE.md Output Paths, always writes to docs/superpowers/specs/ #939 and maintainer comment recommending a README example.
• RED test before README edit: bash tests/docs/test-readme-output-paths.sh failed with 6 missing README assertions.
• GREEN test after README edit: bash tests/docs/test-readme-output-paths.sh passed all assertions.

Verification run locally:

bash tests/docs/test-readme-output-paths.sh
# STATUS: PASSED

bash -n tests/docs/test-readme-output-paths.sh
git diff --check
git diff --cached --check
# no output

Rigor

• If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (paste results below)
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

This is not a skills change. The first checkbox is intentionally not checked. The PR deliberately avoids editing behavior-shaping skill content and instead documents the maintainer-recommended README example.

Human review

• A human has reviewed the COMPLETE proposed diff before submission

[YOMXXX]

Reviewer note

This PR is one of six small, independent PRs opened from the same triage pass. They can be reviewed and merged independently:

• fix: keep SDD writes inside active worktree #1588 worktree write boundary
• fix: guard EnterWorktree core.bare parent checkout #1589 EnterWorktree core.bare guard
• fix: escape SessionStart JSON control characters #1590 SessionStart JSON control escaping
• fix: make visual companion script paths skill-relative #1591 visual companion skill-relative script paths
• fix: align windows lifecycle test with server layout #1592 windows lifecycle test drift
• docs: show output path override example #1593 README Output Paths override example

Focus for this PR: address #939 using the maintainer-suggested direction: document an Output Paths override example in README instead of editing behavior-shaping skill text.

Review surface: README section plus a static README check. This deliberately avoids the skill edits that caused #1020 to be closed.

Verification: README static test failed before the README edit with six missing assertions, then passed after the example was added; bash -n, git diff --check, and git diff --cached --check were clean.

Risk to check: whether the example should mention additional harness instruction filenames beyond CLAUDE.md, AGENTS.md, and GEMINI.md, or whether that is enough for the README.