Replace the brainstorming override with a vendor symlink and an AGENTS.md preference #62

Activity

1. gregoryfoster commented on Oct 21, 2026

   

   gregoryfoster

   on Oct 21, 2026

   ContributorAuthor

   More actions

   Hand-off from the burn-down epic #24, 2026-10-21. This is next, and the last open item before the epic returns to a parking lot (#54). Agent tooling, size S, no deploy. The pre-flight is against origin/main (18deb3c).

   The coordinator checked the issue's facts, and they hold:

   • skills/brainstorming/ is a real directory, the only one among the 25 skills/ entries (the other 24 are links). It holds SKILL.md, spec-document-reviewer-prompt.md, visual-companion.md and scripts.
   • The vendor is at b739a8a (v7.0.0-1). Its brainstorming/ has builder-check-prompt.md and no spec-document-reviewer-prompt.md.
   • v7's SKILL.md:156-158 reads: "Where it goes: in a software repo, docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md, committed. Otherwise, ask. Your human partner's preferences override both." So a stated preference replaces the fork.

   Two points the issue doesn't cover:

   1. v7's hand-off names a skill that isn't linked here. SKILL.md:192 says "for software, invoke superpowers:writing-plans and no other skill", where the override (v6.4.2) said plain "writing-plans skill" (skills/brainstorming/SKILL.md:142). Here, superpowers' writing-plans is deliberately not linked, and gregoryfoster's same-named skill wins (docs/SKILLS.md:43). So the AGENTS.md preference must say so: "superpowers:writing-plans means this repo's writing-plans, which writes to docs/plans/." Without that, a brainstorming session either can't find the skill or goes looking for the unlinked one.
   2. The design-doc filename. The issue proposes docs/specs/YYYY-MM-DD-<issue>-<slug>.md. The existing spec (2026-09-29-processor-service-design.md), the override and v7 all end in -design. The coordinator recommends docs/specs/YYYY-MM-DD-<issue>-<topic>-design.md: the issue number first, as plans do, and the suffix kept. It's your call, but state it once in AGENTS.md and keep docs/SKILLS.md:43's plan-naming note consistent with it.

   The change (the issue's steps 1–4, with the two points above):

   • Replace skills/brainstorming/ with a symlink to ../skills-vendor/obra-superpowers/skills/brainstorming. .claude/skills/brainstorming stays as it is.
   • Add the AGENTS.md brainstorming preferences: the design-doc path and name, plans in docs/plans/ by this repo's writing-plans, and point 1. Also check v7's builder check against the spec-first practice here, and say whether it runs as written. The coordinator sees no conflict.
   • In docs/SKILLS.md, remove the § Overrides row (and the section, if it ends up empty), change line 39's "11 + override" to 12, and update AGENTS.md's Detail Docs line ("the brainstorming override").
   • Keep test_skills_are_vendor_links_or_declared_overrides and test_override_links_resolve, so a future override is still held to the rule. Update the comment at tests/test_socraticode_config.py:74, and check that tests/test_drift.py:115 still reads right.

   Traps:

   1. .skills/doctor.sh must report clean afterwards. Run it in the worktree, and paste the before (the override-drift warning) and the after.
   2. Turning a directory into a symlink in git is a delete of the tracked files plus a new symlink entry. Check git ls-files -s skills/brainstorming shows mode 120000 before pushing.
   3. The SessionStart hook bumps submodules daily on main and pushes. Pull --ff-only right before the merge, so the hook's push and yours don't collide (AGENTS.md § Workflow).

   Done when:

   • skills/brainstorming is a symlink, and the doctor is clean;
   • AGENTS.md states the preferences, including the superpowers:writing-plans mapping;
   • docs/SKILLS.md has no stale override text;
   • the full suite and ruff pass, with CI green on the PR and main push runs.

   No deploy: skills/, docs/, tests/ and AGENTS.md aren't runtime.

   Out of scope: other cohort repos' copies of the same pattern. Note it in the closing comment if useful; the operator routes it.

   Ship: issue → branch in a worktree → plan (short) → PR (Closes #62) → FF merge → git pull --ff-only. The closing comment gives each box with its evidence, the known limits, and the follow-ups (or "none").

   Kickoff prompt:

   Pick up processor#62. Read its hand-off comment from epic #24 first.
2. gregoryfoster

   closed this as completedin #63on Oct 22, 2026
3. gregoryfoster commented on Oct 22, 2026

   

   gregoryfoster

   on Oct 22, 2026

   ContributorAuthor

   More actions

   Shipped in #63, FF-merged to main as 0312f7c (2026-10-22T21:14Z). No deploy: nothing that runs changed.

   Done when:

   • skills/brainstorming is a symlink, and the doctor is clean. git ls-files -s skills/brainstorming gives 120000 c06b06b…, pointing at ../skills-vendor/obra-superpowers/skills/brainstorming. Before, bash .skills/doctor.sh warned "an override has fallen behind its vendor … last synced at commit 8ca22db…". After, it prints nothing and exits 0, in both the worktree and this checkout after the pull. The full before output is in #62 Replace the brainstorming override with a vendor link and an AGENTS.md preference #63.
   • AGENTS.md states the preferences, including the superpowers:writing-plans mapping. They're under Development Methodology → Brainstorming:
     • a change to the service's behaviour amends the spec;
     • otherwise a design doc goes in docs/specs/YYYY-MM-DD-<issue>-<topic>-design.md;
     • superpowers:<name> means skills/<name>, so superpowers:writing-plans is gregoryfoster's writing-plans, writing to docs/plans/ (superpowers:using-git-worktrees likewise);
     • the builder check runs as written. On an amendment, hand it the spec and name the amended sections. It doesn't conflict with spec-first practice: it tests the self-containment AGENTS.md already requires.
   • docs/SKILLS.md has no stale override text. It lists 12 superpowers links. § Overrides reads "none since Replace the brainstorming override with a vendor symlink and an AGENTS.md preference #62" and keeps the rule for a future override. Line 43 names superpowers:writing-plans. Three more mentions the issue didn't list are fixed too: .socraticodeignore, .socraticodecontextartifacts.json and docs/SOCRATICODE.md. tests/test_drift.py:115 reads right as it is.
   • Suite, ruff and CI. Locally: ruff clean, 697 passed, 14 skipped (environmental: production secrets aren't present in a worktree). CI by job: on the PR, run 39854917310 passed lint and test. On the main push of 0312f7c, run 39855558610 passed lint and test.

   Tests: written red first (e0f563d).

   • The inventory test now checks the superpowers count as well. It was red on 11 vs 12.
   • New test_superpowers_invocations_resolve_here: a superpowers:<name> must resolve to a skills/ link, and AGENTS.md must map it when it isn't superpowers'. It was red on writing-plans and using-git-worktrees.
   • Both override tests are kept, though they have nothing to check for now.

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

   Follow-ups: none in this repo. For the operator to route: other cohort repos with the same Observo-pattern brainstorming override can retire it the same way.
4. gregoryfoster commented on Oct 22, 2026

   

   gregoryfoster

   on Oct 22, 2026

   ContributorAuthor

   More actions

   Review round 1 shipped in #64, FF-merged to main as 68bfee1..57fc8a3. CI on the main push: run 39869123577 passed lint and test. No deploy.

   • CR 1 (38317fb): AGENTS.md Brainstorming now covers v7's "small change" path. A small change that is non-trivial still gets a plan, and every change goes issue → branch → PR.
   • CR 2 (d276d7e): test_superpowers_invocations_resolve_here scans every *.md in a superpowers skill, not just SKILL.md: 36 references instead of 30, all resolving.
   • CR 3 (57a74cb): the same test fails with the doctor hint on a dangling link. After CR 2, an uninitialised submodule had made it pass on an empty scan. Checked by pointing one link at a missing target.
   • CR 4 (57fc8a3): the worktree pointer reads § Conventions → Workflow.

   Separately, 68bfee1 is the hook's rolled-back gregoryfoster-skills bump (0c32ebc → b8c54db), pushed by hand ahead of this round.

   Follow-ups: none.