[gregoryfoster]

Closes #62. Plan: docs/plans/2026-10-22-62-brainstorming-vendor-link.md. Per the hand-off from epic #24.

What changed

• skills/brainstorming is a symlink to ../skills-vendor/obra-superpowers/skills/brainstorming (v7, b739a8a), not the v6.4.2 copy. .claude/skills/brainstorming is unchanged. v7's builder-check-prompt.md is now reachable, and the dropped spec-document-reviewer-prompt.md is gone.
• AGENTS.md → Development Methodology → Brainstorming: the preferences v7's Where it goes defers to.
  • A behaviour change amends the spec (a dated Amended entry plus the sections it touches), as Take co-core's XML and feed extractors in step with Watcher, and re-run parity with a feed fixture #29–Co-core bump rule: resolve_dispatch_essence is notice, not coordination #57 did.
  • A design doc of its own only for work the spec doesn't cover: docs/specs/YYYY-MM-DD-<issue>-<topic>-design.md. That takes the coordinator's recommendation: the issue number first, as plans do, and -design kept.
  • superpowers:<name> means this repo's skills/<name>. So superpowers:writing-plans is gregoryfoster's writing-plans, which writes to docs/plans/, and superpowers:using-git-worktrees is gregoryfoster's too. Superpowers skills invoke both (3 times each).
  • The builder check runs as written (see below).
• docs/SKILLS.md: obra-superpowers now lists 12, brainstorming included. § Overrides says "none since Replace the brainstorming override with a vendor symlink and an AGENTS.md preference #62", with the history in one line, and keeps the override rule so a future override still has a home. Line 43 names superpowers:writing-plans and points at the AGENTS.md mapping.
• Stale mentions: AGENTS.md § Agent Skills and Detail Docs. Three more the issue didn't list: .socraticodeignore:6, .socraticodecontextartifacts.json:21 and docs/SOCRATICODE.md:203. Also tests/test_socraticode_config.py:74's comment. tests/test_drift.py:115 reads right as it is: skills/brainstorming is still a path that never runs, now a link.

The builder check against spec-first practice

No conflict. It writes no code. It dispatches a reader that can't talk to the author and asks what it would still have to guess. AGENTS.md already requires the spec to be "self-contained", and the check tests exactly that. The only local adjustment: most design work here is an amendment to the spec, not a new doc, so on an amendment you hand the builder the spec and name the amended sections. The Size the Work table's "full plan (for software: superpowers:writing-plans)" and the HARD-GATE's hand-off fit AGENTS.md's "plan in docs/plans/, reviewed before implementation".

Tests (red first, e0f563d)

• test_skills_md_inventory_matches_the_links now checks the obra-superpowers count too. It used to skip it because the heading read "11 + override". It was red on 11 == 12.
• New test_superpowers_invocations_resolve_here: every superpowers:<name> that a superpowers skill (link or override) invokes must be skills/<name>. Where that entry isn't superpowers', AGENTS.md must name superpowers:<name>. It was red on ['using-git-worktrees', 'writing-plans'].
• test_skills_are_vendor_links_or_declared_overrides and test_override_links_resolve are kept. They have nothing to check until the next override.

Known limit: the new test reads vendor text. If the daily hook's bump brings in an upstream skill that invokes a skill not linked here, CI on main fails. That's the signal we want, and it fails in the same place as the existing SKILL.md is_file check.

Evidence

git ls-files -s skills/brainstorming:

120000 c06b06b3e293d24b070aa9e5bf77f5b484bc8811 0	skills/brainstorming

bash .skills/doctor.sh, before (on origin/main 18deb3c, submodules initialised):

doctor: an override has fallen behind its vendor:
  skills/brainstorming overrides obra-superpowers/brainstorming: last synced at commit 8ca22dba9a94f28898bbce59f2537ff4d87c747d, vendor now at a vendor tree with SKILL.md, scripts/server.cjs, spec-document-reviewer-prompt.md changed since that commit
doctor: copy each override aside BEFORE merging, then re-sync by
doctor: reapplying the local deltas onto the newer upstream text —
doctor: never upstream changes onto the old fork — and bump the
doctor: override's version: AND synced-from: to what was just
doctor: synced — a synced-from: left at the old commit re-reports
doctor: the drift you just paid down.
doctor: Last, diff that copy against the merged file and account for
doctor: every removed line: a presence-only check cannot see a local
doctor: delta the merge dropped. Advisory: nothing is auto-merged.

After (this branch): no output, exit 0.

uv run ruff check . && uv run ruff format --check . && uv run pytest: All checks passed, 55 files already formatted, 697 passed, 14 skipped. The skips are environmental: production secrets aren't present in a worktree.

No deploy: nothing under src/, deploy/, scripts/deploy.sh, pyproject.toml or uv.lock changes.

Out of scope, for the operator to route: other cohort repos may carry the same Observo-pattern brainstorming override, and the same v7 deferral would retire it there.

🤖 Generated with Claude Code