From 0005e2e367d0ead6c973e78ed8abfc69b74e04e9 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Thu, 22 Oct 2026 21:03:25 +0000 Subject: [PATCH 1/4] =?UTF-8?q?#62=20docs:=20plan=20=E2=80=94=20the=20brai?= =?UTF-8?q?nstorming=20override=20becomes=20a=20vendor=20link=20and=20an?= =?UTF-8?q?=20AGENTS.md=20preference?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- ...2026-10-22-62-brainstorming-vendor-link.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs/plans/2026-10-22-62-brainstorming-vendor-link.md diff --git a/docs/plans/2026-10-22-62-brainstorming-vendor-link.md b/docs/plans/2026-10-22-62-brainstorming-vendor-link.md new file mode 100644 index 0000000..02e7a2e --- /dev/null +++ b/docs/plans/2026-10-22-62-brainstorming-vendor-link.md @@ -0,0 +1,39 @@ +--- +title: The brainstorming override becomes a vendor link and an AGENTS.md preference (#62) +date: 2026-10-22 +status: per #62's hand-off from epic #24 (2026-10-21) +--- + +# The brainstorming override becomes a vendor link + +## Problem + +`skills/brainstorming/` is a v6.4.2 copy (`8ca22db`), kept to change one path. The vendor is at v7 (`b739a8a`): `SKILL.md` rewritten, `spec-document-reviewer-prompt.md` gone, `builder-check-prompt.md` added and unlinked. The doctor reports the drift. v7 says "Your human partner's preferences override both" for where the design goes, so a stated preference does the fork's job with no re-sync. + +## Approach + +- `skills/brainstorming` → symlink `../skills-vendor/obra-superpowers/skills/brainstorming`. `.claude/skills/brainstorming` unchanged. +- AGENTS.md, a `### Brainstorming` preference under Development Methodology: + - a change to the service's behaviour amends the spec of record (a dated **Amended** entry plus the sections it touches), as #29–#57 did; + - a new design doc only for work the spec doesn't cover: `docs/specs/YYYY-MM-DD---design.md`, never `docs/superpowers/specs/`. Issue first, as plans; `-design` kept, as the spec, the override and v7; + - `superpowers:` means this repo's `skills/`: `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, the builder reads the spec's amended sections. +- docs/SKILLS.md: obra count 11 + override → 12, `brainstorming` in the list; § Overrides removed (its only row) but the rule kept in one line, so a future override still has a home; line 43's naming note points at AGENTS.md. +- Stale mentions: AGENTS.md Detail Docs and § Agent Skills, `.socraticodeignore:6`, `.socraticodecontextartifacts.json:21`, docs/SOCRATICODE.md:203, `tests/test_socraticode_config.py:74`. `tests/test_drift.py:115` stays: `skills/brainstorming` is still a non-runtime path. + +## Test + +`tests/test_skills.py`: +- `test_skills_md_inventory_matches_the_links` checks the obra count too (it skipped it for the "+ override" heading). Red now: the heading says 11, the list names 12. +- New: every `superpowers:` a linked superpowers skill's `SKILL.md` invokes resolves to `skills/`, and where that entry is not superpowers', AGENTS.md names `` `superpowers:` ``. Red now: AGENTS.md names neither. +- `test_skills_are_vendor_links_or_declared_overrides` and `test_override_links_resolve` stay, vacuous until the next override. + +Known limit: the new test reads vendor text, so an upstream bump that invokes an unlinked skill fails CI on `main` after the hook's push. That is the signal wanted, at the same place `SKILL.md is_file` already fails. + +## Ship + +Doctor before/after in the PR; `git ls-files -s skills/brainstorming` shows `120000`. PR (`Closes #62`) → `git pull --ff-only` → FF merge → `git pull --ff-only`. No deploy. + +## Open questions + +None. From e0f563dce6e504bb940b43df495f310bb6da2f58 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Thu, 22 Oct 2026 21:03:56 +0000 Subject: [PATCH 2/4] #62 test: superpowers invocations resolve here, and the obra count is checked Co-Authored-By: Claude Opus 5.5 --- tests/test_skills.py | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/tests/test_skills.py b/tests/test_skills.py index 0432a67..5624017 100644 --- a/tests/test_skills.py +++ b/tests/test_skills.py @@ -114,7 +114,34 @@ def test_skills_md_inventory_matches_the_links() -> None: ) names = {repo: set(re.findall(r"`([\w-]+)`", line)) for repo, _, line in heads} assert set().union(*names.values()) == set(_names(SKILLS)) - gf_count = next(int(n) for repo, n, _ in heads if repo == "gregoryfoster-skills") - assert gf_count == len(names["gregoryfoster-skills"]) + for repo, count, _ in heads: + assert int(count) == len(names[repo]), (repo, count, sorted(names[repo])) (not_linked,) = re.findall(r"^Not linked: (.*)$", doc, re.M) assert not set(re.findall(r"`([\w-]+)`", not_linked)) & set(_names(SKILLS)) + + +def _vendor_of(name: str) -> str: + """The ``-`` a ``skills/`` entry links into, or that its override names.""" + entry = SKILLS / name + if entry.is_symlink(): + return entry.readlink().parts[2] + return _frontmatter(entry / "SKILL.md")["overrides"].split("/")[0] + + +def test_superpowers_invocations_resolve_here() -> None: + """A superpowers skill's ``superpowers:`` is ``skills/``; AGENTS.md maps strays.""" + agents = (ROOT / "AGENTS.md").read_text() + ours = [n for n in _names(SKILLS) if _vendor_of(n) == "obra-superpowers"] + invoked = { + m + for n in ours + for m in re.findall(r"superpowers:([\w-]+)", (SKILLS / n / "SKILL.md").read_text()) + } + missing = sorted(n for n in invoked if not (SKILLS / n).exists()) + assert not missing, missing + unmapped = sorted( + n + for n in invoked + if _vendor_of(n) != "obra-superpowers" and f"`superpowers:{n}`" not in agents + ) + assert not unmapped, unmapped From 735b0250947816fbac39454195b6e595365f6ed4 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Thu, 22 Oct 2026 21:08:48 +0000 Subject: [PATCH 3/4] #62 refactor: skills/brainstorming is a vendor link, not a v6.4.2 override v7 defers the design-doc path to the partner's preferences, so the fork's one delta moves to AGENTS.md and nothing needs a re-sync. docs/SKILLS.md counts 12 superpowers links and keeps the override rule for the next one. Co-Authored-By: Claude Opus 5.5 --- .socraticodecontextartifacts.json | 2 +- .socraticodeignore | 4 +- docs/SKILLS.md | 10 +- docs/SOCRATICODE.md | 4 +- skills/brainstorming | 1 + skills/brainstorming/SKILL.md | 289 ------------------ skills/brainstorming/scripts | 1 - .../spec-document-reviewer-prompt.md | 49 --- skills/brainstorming/visual-companion.md | 1 - tests/test_socraticode_config.py | 4 +- 10 files changed, 12 insertions(+), 353 deletions(-) create mode 120000 skills/brainstorming delete mode 100644 skills/brainstorming/SKILL.md delete mode 120000 skills/brainstorming/scripts delete mode 100644 skills/brainstorming/spec-document-reviewer-prompt.md delete mode 120000 skills/brainstorming/visual-companion.md diff --git a/.socraticodecontextartifacts.json b/.socraticodecontextartifacts.json index ee1b319..517de8e 100644 --- a/.socraticodecontextartifacts.json +++ b/.socraticodecontextartifacts.json @@ -18,7 +18,7 @@ { "name": "skills-doc", "path": "./docs/SKILLS.md", - "description": "The vendored agent skills: inventory, the brainstorming override, the daily refresh hook, provisioning a worktree." + "description": "The vendored agent skills: inventory, overrides, the daily refresh hook, provisioning a worktree." }, { "name": "socraticode-doc", diff --git a/.socraticodeignore b/.socraticodeignore index 529cdcf..20d73a8 100644 --- a/.socraticodeignore +++ b/.socraticodeignore @@ -3,8 +3,8 @@ # graph only, never the context artifacts (docs/SOCRATICODE.md). # Vendored gregoryfoster/skills and obra/superpowers. skills/ and .claude/skills/ are -# symlinks into skills-vendor/, bar skills/brainstorming, an upstream copy with one -# path changed (docs/SKILLS.md); .skills/ holds the installed doctor.sh. Unexcluded +# symlinks into skills-vendor/, bar any upstream override (none since #62; +# docs/SKILLS.md); .skills/ holds the installed doctor.sh. Unexcluded # they outnumber processor's own files, and every sibling's includeLinked search # would serve them as processor. skills-vendor/ diff --git a/docs/SKILLS.md b/docs/SKILLS.md index e2aa3df..318de17 100644 --- a/docs/SKILLS.md +++ b/docs/SKILLS.md @@ -36,21 +36,19 @@ The first session in a fresh clone or worktree fails the hook with exit 127 (hoo **gregoryfoster-skills (13):** `auditing-ci-cost` (CI since #12), `coordinating-epics` (#24 since #52), `curating-context`, `enforcing-architecture` (`reviewing-architecture` delegates to it), `init-socraticode`, `managing-skills`, `orchestrating-issue-backlog`, `reviewing-architecture`, `reviewing-code-python-fastapi`, `shipping-work-python-fastapi`, `using-git-worktrees`, `using-mayfly-chat`, `writing-plans`. -**obra-superpowers (11 + override):** `dispatching-parallel-agents`, `executing-plans`, `finishing-a-development-branch`, `receiving-code-review`, `requesting-code-review`, `subagent-driven-development`, `systematic-debugging`, `test-driven-development`, `using-superpowers`, `verification-before-completion`, `writing-skills`; `brainstorming` as an override. +**obra-superpowers (12):** `brainstorming`, `dispatching-parallel-agents`, `executing-plans`, `finishing-a-development-branch`, `receiving-code-review`, `requesting-code-review`, `subagent-driven-development`, `systematic-debugging`, `test-driven-development`, `using-superpowers`, `verification-before-completion`, `writing-skills`. - **Review and ship are the `-python-fastapi` variants, though processor isn't FastAPI** (as broker). Their `pre-ship.sh` is processor's gate unmodified: `ruff check`, `ruff format --check`, `pytest` minus `integration`. The Alembic/route steps key on paths processor lacks; the `deploy/` review checks and the post-merge `systemctl restart processor` fit. - **`using-mayfly-chat` needs Node ≥ 18**; its wrapper exits 4 without it. co-processor has Node 24 LTS from NodeSource apt, installed 2026-09-30 (#6). Linked because the cohort adopts it together (gregoryfoster/skills#302). A channel URL is read/write/delete access: never commit one. -- **Superpowers' `using-git-worktrees` and `writing-plans` are not linked**: gregoryfoster's own, same-named, win. So brainstorming's hand-off to `writing-plans` lands plans in `docs/plans/`. Its filename is `YYYY-MM-DD-.md`: start the topic with the issue number, so the slug is AGENTS.md's `-` (e.g. `2026-09-29-1-processor-v1.md`). +- **Superpowers' `using-git-worktrees` and `writing-plans` are not linked**: gregoryfoster's own, same-named, win. So brainstorming's hand-off to `superpowers:writing-plans` lands plans in `docs/plans/` (AGENTS.md → *Brainstorming* maps the name; a test holds every `superpowers:` to a link or a mapping). Its filename is `YYYY-MM-DD-.md`: start the topic with the issue number, so the slug is AGENTS.md's `-` (e.g. `2026-09-29-1-processor-v1.md`). Not linked: `init-project-fastapi` (scaffolder), `vendoring-openapi-client` (no sibling HTTP API called), the other stack variants of review/ship, `diagnosing-superpowers` (no sibling links it). The daily refresh never adds symlinks, so a newly published skill is a manual link: diff `ls skills-vendor/*/skills/` against this list. ## Overrides -| Skill | Overrides | Delta | -|---|---|---| -| `brainstorming` | `obra-superpowers/brainstorming` | `docs/superpowers/specs/` → `docs/specs/`, in `SKILL.md` and `spec-document-reviewer-prompt.md`. Otherwise upstream verbatim; `visual-companion.md` and `scripts/` are vendor symlinks. Observo's pattern | +None since #62. `brainstorming` was one, synced from v6.4.2 to move the design doc to `docs/specs/`, until v7 deferred that path to the partner's preferences; AGENTS.md → *Brainstorming* states them. Where upstream defers, a stated preference beats an override: it needs no re-sync. -The doctor warns when the vendor moves past `synced-from:`. Re-sync by reapplying the delta onto the new upstream text (never the reverse), then bump `synced-from:`: `managing-skills` → *Updating a local override*. Kept minimal on purpose: the heavier cohort forks each needed re-sync issues. +An override is a regular directory in `skills/` whose `SKILL.md` names `overrides:` and `synced-from:` (tests/test_skills.py holds it to both). The doctor warns when the vendor moves past `synced-from:`. Re-sync by reapplying the delta onto the new upstream text (never the reverse), then bump `synced-from:`: `managing-skills` → *Updating a local override*. Kept minimal on purpose: the heavier cohort forks each needed re-sync issues. ## Worktrees diff --git a/docs/SOCRATICODE.md b/docs/SOCRATICODE.md index 59ea917..4ace1fb 100644 --- a/docs/SOCRATICODE.md +++ b/docs/SOCRATICODE.md @@ -200,8 +200,8 @@ extraction child volunteers at +1000. The peak that took broker down on Revisit if the service's resident memory grows into hundreds of MiB. **Index scope here.** `.socraticodeignore` drops `skills-vendor/`, `skills/`, -`.claude/skills/` and `.skills/` (vendored; `skills/brainstorming` is an upstream -copy with one path changed), both worktree roots, `.wheelhouse`, and +`.claude/skills/` and `.skills/` (vendored, or an upstream override; none since +#62), both worktree roots, `.wheelhouse`, and `docs/plans/`. Plans stay searchable as the `implementation-plans` artifact (scope a search to it with `artifactName`); out of the code index, a superseded plan cannot outrank the source. What remains is about 95 tracked files, 48 of diff --git a/skills/brainstorming b/skills/brainstorming new file mode 120000 index 0000000..c06b06b --- /dev/null +++ b/skills/brainstorming @@ -0,0 +1 @@ +../skills-vendor/obra-superpowers/skills/brainstorming \ No newline at end of file diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md deleted file mode 100644 index 7bfef77..0000000 --- a/skills/brainstorming/SKILL.md +++ /dev/null @@ -1,289 +0,0 @@ ---- -name: brainstorming -description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." -metadata: - overrides: obra-superpowers/brainstorming - synced-from: "obra-superpowers v6.4.2 (8ca22dba9a94f28898bbce59f2537ff4d87c747d)" - override-reason: "Redirects the design-doc path from upstream's docs/superpowers/specs/ to docs/specs/, where processor's service spec lives, everywhere the skill names it: SKILL.md's checklist and write step, and spec-document-reviewer-prompt.md's dispatch note. Observo's pattern. Everything else is upstream verbatim; visual-companion.md and scripts/ are vendor symlinks. Upstream ships no version:, so synced-from: is the doctor's only comparand." ---- - -# Brainstorming Ideas Into Designs - -Help turn ideas into fully formed designs and specs through natural collaborative dialogue. - -Start by classifying how much process the request needs, then work -through your path: understand the context, refine the idea, present a -design, and get your human partner's approval. - -## Establish Shared Understanding - -The outcome of brainstorming is an understanding your human partner can -recognize and correct, grounded in what they want to accomplish. - -1. **Discover intent.** Use the request and available context to identify - the intended outcome, who it is for, and what success looks like. When - that information is missing, ask one focused question about purpose or - intended use before proposing features or an approach. Knowing the app - genre does not tell you why your partner wants it. Gathering missing - requirements does not ask them to authorize the task again. -2. **Write back your understanding.** Summarize the intended outcome, - relevant constraints, and success criteria in a short note your partner - can assess. Separate what they said from assumptions. Invite correction - and incorporate their answer before treating this as the design brief. -3. **Carry intent into the design.** Preserve the agreed understanding in - the selected path's design artifact: the written spec for architectural - work, or the in-chat design/probe for bounded work and spikes. Check - proposed features and technical choices against that understanding. - -When the request already supplies the purpose and constraints, reflect -that understanding instead of asking the same questions again. Keep the -note concise; its accuracy and the opportunity to correct it matter. - - -Before taking any implementation action, including invoking an -implementation skill, writing product code, scaffolding, installing -product dependencies, or creating an external project, complete the -selected path's prerequisites: - -- Spike: the human partner approves the question and probe. -- Bounded: the human partner approves the short in-chat design. -- Architectural: the human partner reviews and approves the written spec, - then reviews the written implementation plan and selects its execution - method. Conversational design approval only permits writing the spec; - written-spec approval only permits invoking writing-plans. - -A reply approves the stage actually presented. Approval of an idea or -feature scope does not approve artifacts that do not exist yet. Resume -at the earliest incomplete stage; do not turn one approval into permission -to skip the rest of the selected path. Read-only project exploration is -allowed while those prerequisites remain incomplete. - - -## Three Paths - -Before your first question, classify the request and say the -classification out loud — "this looks bounded, so I'll present a short -design here rather than write a spec" — so your human partner can -override it: - -- **Spike** — a feasibility question ("can we...", "is it possible...", - "quick and dirty is fine") whose output is an answer, not code you - keep. Present the question and what you'll try in 2-3 sentences, get - a nod, then find out as cheaply as correctness allows. No design - doc, no spec file. Report findings as a recommendation; anything you - built stays labeled throwaway. -- **Bounded** — a well-scoped change to code that already exists in - this repo: a new flag, a small endpoint, a one-file fix. - Understanding the kind of app is not enough — bounded means the flow - you are changing is already here to read. If there is no existing - flow to change, the task is not bounded. Ask the clarifying - questions that matter, present a short design IN CHAT (a few - sentences to a few short paragraphs), and STOP. Implementation - starts only after your human partner says yes to that design — a - bounded task's approval is as hard a gate as an architectural - one. No spec file, no implementation plan document. -- **Architectural** — new projects, new subsystems, changes that - restructure how components fit together or alter interfaces others - depend on. Follow the full process: questions, approaches, sectioned - design, written spec, then the writing-plans skill. - -When in doubt between two paths, take the heavier one. The ratchet is -one-way: hidden complexity discovered mid-task upgrades the path — -stop, say so, and step up. Nothing downgrades mid-task. - -## Anti-Pattern: "Too Simple To Need Approval" - -Every path ends with your human partner approving the required design -before implementation. A bounded change may need only two sentences in -chat. A new todo-list project is architectural and requires the written -spec and planning handoffs. Scale the artifact to the selected path; -complete that path's reviews before implementation. - -## Red Flags - -| Thought | Reality | -|---------|---------| -| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. | -| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. | -| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. | -| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. | -| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. | -| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. | -| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. | - -## Checklist - -Classify first, announce the path, then create a task for each item on -your path and complete them in order. - -**Spike:** -1. **Explore project context** — enough to frame the probe -2. **Present question + probe plan** — 2-3 sentences -3. **Get approval** — a nod is enough -4. **Investigate** — as cheaply as correctness allows -5. **Report findings** — a recommendation; label anything built as throwaway - -**Bounded:** -1. **Explore project context** — check files, docs, recent commits -2. **Ask clarifying questions** — one at a time, the ones that matter -3. **Present short design in chat** — approach, files touched, testing -4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate -5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document - -**Architectural:** -1. **Explore project context** — check files, docs, recent commits -2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below. -3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria -4. **Propose 2-3 approaches** — with trade-offs and your recommendation -5. **Present design** — in sections scaled to their complexity, get user approval after each section -6. **Write design doc** — save to `docs/specs/YYYY-MM-DD--design.md` and commit -7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below) -8. **User reviews written spec** — ask user to review the spec file before proceeding -9. **Transition to implementation** — invoke writing-plans skill to create implementation plan - -## Process Flow - -```dot -digraph brainstorming { - "Classify: spike / bounded / architectural" [shape=diamond]; - "Present question + probe (2-3 sentences)" [shape=box]; - "Ask clarifying questions (bounded)" [shape=box]; - "Present short design in chat" [shape=box]; - "Human approves?" [shape=diamond]; - "Investigate; report recommendation" [shape=doublecircle]; - "Implement via normal workflow (no plan doc)" [shape=doublecircle]; - "Explore project context" [shape=box]; - "Ask clarifying questions" [shape=box]; - "Propose 2-3 approaches" [shape=box]; - "Present design sections" [shape=box]; - "User approves design?" [shape=diamond]; - "Write design doc" [shape=box]; - "Spec self-review\n(fix inline)" [shape=box]; - "User reviews spec?" [shape=diamond]; - "Invoke writing-plans skill" [shape=doublecircle]; - "Hidden complexity? Upgrade path" [shape=box]; - - "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"]; - "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"]; - "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"]; - "Present question + probe (2-3 sentences)" -> "Human approves?"; - "Ask clarifying questions (bounded)" -> "Present short design in chat"; - "Present short design in chat" -> "Human approves?"; - "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"]; - "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"]; - "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural"; - "Explore project context" -> "Ask clarifying questions"; - "Ask clarifying questions" -> "Propose 2-3 approaches"; - "Propose 2-3 approaches" -> "Present design sections"; - "Present design sections" -> "User approves design?"; - "User approves design?" -> "Present design sections" [label="no, revise"]; - "User approves design?" -> "Write design doc" [label="yes"]; - "Write design doc" -> "Spec self-review\n(fix inline)"; - "Spec self-review\n(fix inline)" -> "User reviews spec?"; - "User reviews spec?" -> "Write design doc" [label="changes requested"]; - "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"]; -} -``` - -**Terminal states are path-bound.** Architectural: the ONLY skill you -invoke after brainstorming is writing-plans — never frontend-design, -mcp-builder, or any other implementation skill. Bounded: after -approval, implementation proceeds directly through the normal -development workflow; no plan document. Spike: the terminal state is a -reported recommendation. - -## The Process - -The subsections below serve the bounded and architectural paths (a -spike stops at "present the probe, get a nod"). Sections from -**Exploring approaches** onward are architectural-path depth — for -bounded work, context plus a few questions plus a short in-chat design -is the whole process. - -**Understanding the idea:** - -- Check out the current project state first (files, docs, recent commits) -- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first. -- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle. -- For appropriately-scoped projects, ask questions one at a time to refine the idea -- Prefer multiple choice questions when possible, but open-ended is fine too -- Only one question per message - if a topic needs more exploration, break it into multiple questions -- Focus on understanding: purpose, constraints, success criteria - -**Exploring approaches:** - -- Propose 2-3 different approaches with trade-offs -- Present options conversationally with your recommendation and reasoning -- Lead with your recommended option and explain why -- YAGNI ruthlessly - remove unnecessary features from every approach and design - -**Presenting the design:** - -- Once you believe you understand what you're building, present the design -- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced -- Ask after each section whether it looks right so far -- Cover: architecture, components, data flow, error handling, testing -- Be ready to go back and clarify if something doesn't make sense - -**Design for isolation and clarity:** - -- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently -- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on? -- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work. -- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much. - -**Working in existing codebases:** - -- Explore the current structure before proposing changes. Follow existing patterns. -- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in. -- Don't propose unrelated refactoring. Stay focused on what serves the current goal. - -## After the Design (architectural path) - -**Documentation:** - -- Write the validated design (spec) to `docs/specs/YYYY-MM-DD--design.md` - - (User preferences for spec location override this default) -- Use elements-of-style:writing-clearly-and-concisely skill if available -- Commit the design document to git - -**Spec Self-Review:** -After writing the spec document, look at it with fresh eyes: - -1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them. -2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions? -3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition? -4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit. - -Fix any issues inline. No need to re-review — just fix and move on. - -**User Review Gate:** -After the spec review loop passes, ask the user to review the written spec before proceeding: - -> "Spec written and committed to ``. Please review it and let me know if you want to make any changes before we start writing out the implementation plan." - -Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves. - -**Implementation:** - -- Invoke the writing-plans skill to create a detailed implementation plan -- Do NOT invoke any other skill. writing-plans is the next step. - -## Visual Companion - -A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser. - -**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message: -> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you." - -**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it. - -**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?** - -- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs -- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions - -A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser. - -If they agree to the companion, read the detailed guide before proceeding: -`skills/brainstorming/visual-companion.md` diff --git a/skills/brainstorming/scripts b/skills/brainstorming/scripts deleted file mode 120000 index 914a0fe..0000000 --- a/skills/brainstorming/scripts +++ /dev/null @@ -1 +0,0 @@ -../../skills-vendor/obra-superpowers/skills/brainstorming/scripts \ No newline at end of file diff --git a/skills/brainstorming/spec-document-reviewer-prompt.md b/skills/brainstorming/spec-document-reviewer-prompt.md deleted file mode 100644 index 0cb45cb..0000000 --- a/skills/brainstorming/spec-document-reviewer-prompt.md +++ /dev/null @@ -1,49 +0,0 @@ -# Spec Document Reviewer Prompt Template - -Use this template when dispatching a spec document reviewer subagent. - -**Purpose:** Verify the spec is complete, consistent, and ready for implementation planning. - -**Dispatch after:** Spec document is written to docs/specs/ - -``` -Subagent (general-purpose): - description: "Review spec document" - prompt: | - You are a spec document reviewer. Verify this spec is complete and ready for planning. - - **Spec to review:** [SPEC_FILE_PATH] - - ## What to Check - - | Category | What to Look For | - |----------|------------------| - | Completeness | TODOs, placeholders, "TBD", incomplete sections | - | Consistency | Internal contradictions, conflicting requirements | - | Clarity | Requirements ambiguous enough to cause someone to build the wrong thing | - | Scope | Focused enough for a single plan — not covering multiple independent subsystems | - | YAGNI | Unrequested features, over-engineering | - - ## Calibration - - **Only flag issues that would cause real problems during implementation planning.** - A missing section, a contradiction, or a requirement so ambiguous it could be - interpreted two different ways — those are issues. Minor wording improvements, - stylistic preferences, and "sections less detailed than others" are not. - - Approve unless there are serious gaps that would lead to a flawed plan. - - ## Output Format - - ## Spec Review - - **Status:** Approved | Issues Found - - **Issues (if any):** - - [Section X]: [specific issue] - [why it matters for planning] - - **Recommendations (advisory, do not block approval):** - - [suggestions for improvement] -``` - -**Reviewer returns:** Status, Issues (if any), Recommendations diff --git a/skills/brainstorming/visual-companion.md b/skills/brainstorming/visual-companion.md deleted file mode 120000 index a1f7928..0000000 --- a/skills/brainstorming/visual-companion.md +++ /dev/null @@ -1 +0,0 @@ -../../skills-vendor/obra-superpowers/skills/brainstorming/visual-companion.md \ No newline at end of file diff --git a/tests/test_socraticode_config.py b/tests/test_socraticode_config.py index d416e4d..0906d74 100644 --- a/tests/test_socraticode_config.py +++ b/tests/test_socraticode_config.py @@ -71,8 +71,8 @@ #: (archiver), and notifier. Each has its own ``projectId`` collection on co-index. LINKED = {"../archiver", "../broker", "../notifier", "../replicator", "../watcher"} -#: gregoryfoster/skills content and its installed tooling; ``skills/brainstorming`` -#: is an upstream copy with one path changed (docs/SKILLS.md), so ``skills/`` goes whole. +#: Vendored skills and their installed tooling; nothing in ``skills/`` is first-party, +#: bar upstream overrides (none since #62, docs/SKILLS.md), so ``skills/`` goes whole. VENDORED = {"skills-vendor/", "skills/", ".claude/skills/", ".skills/"} #: using-git-worktrees' root and the harness's, both inside this tree. From 0312f7c7ae47cdf5fd0587e49b5983245c90fe82 Mon Sep 17 00:00:00 2001 From: gregoryfoster Date: Thu, 22 Oct 2026 21:08:48 +0000 Subject: [PATCH 4/4] #62 docs: AGENTS.md states the brainstorming preferences Spec amendments by default, docs/specs/YYYY-MM-DD---design.md otherwise; superpowers: is this repo's skills/, so superpowers:writing-plans is gregoryfoster's, writing to docs/plans/; the builder check runs as written. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ed3cdf3..33ad6c7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,6 +14,11 @@ Design of record: [docs/specs/2026-09-29-processor-service-design.md](docs/specs TDD required. Red → Green → Refactor. No production code without a failing test first. Non-trivial work gets a plan in `docs/plans/YYYY-MM-DD--.md`, reviewed before implementation. +**Brainstorming** (`skills/brainstorming`, superpowers' unmodified): these are the partner's preferences its *Where it goes* defers to. +- A change to the service's behaviour amends the spec: a dated **Amended** entry in its header, plus the sections it touches. A design doc of its own only for work the spec doesn't cover: `docs/specs/YYYY-MM-DD---design.md`, never `docs/superpowers/specs/`. +- `superpowers:` means this repo's `skills/`, whichever vendor it links. `superpowers:writing-plans` is gregoryfoster's `writing-plans`, which writes the plan above to `docs/plans/`; `superpowers:using-git-worktrees` is gregoryfoster's too (§ Conventions). +- The builder check runs as written. On an amendment, hand it the spec and name the amended sections. + ## Environment & Tooling Python 3.12, uv, hatchling src layout, pytest, ruff. @@ -56,7 +61,7 @@ find-links locks by filename, not hash, so either source satisfies the same `uv. ## Agent Skills -`gregoryfoster/skills` and `obra/superpowers` vendored under `skills-vendor/`, symlinked into `skills/` (agentskills.io) and `.claude/skills/` (Claude Code). Symlinks dangle until the submodules are initialised: `bash .skills/doctor.sh`. A `SessionStart` hook bumps them daily on `main` and pushes. Inventory, override, refresh: [docs/SKILLS.md](docs/SKILLS.md). +`gregoryfoster/skills` and `obra/superpowers` vendored under `skills-vendor/`, symlinked into `skills/` (agentskills.io) and `.claude/skills/` (Claude Code). Symlinks dangle until the submodules are initialised: `bash .skills/doctor.sh`. A `SessionStart` hook bumps them daily on `main` and pushes. Inventory, refresh, worktrees: [docs/SKILLS.md](docs/SKILLS.md). ## Environment Files @@ -96,7 +101,7 @@ scripts/deploy.sh [] # ship: CI green, then build a release - [docs/specs/2026-09-29-processor-service-design.md](docs/specs/2026-09-29-processor-service-design.md) — the spec: decisions, grants, runtime, failure table, versioning, cutover, testing, contract quick reference - [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) — prerequisites, the broker credential handoff, `/etc/processor/`, releases and `scripts/deploy.sh`, the drift check, liveness, containment, install and rollback, operate, co-core bumps, Tailscale DNS, Node.js - [docs/plans/](docs/plans/) — implementation plans -- [docs/SKILLS.md](docs/SKILLS.md) — vendored agent skills, the brainstorming override, the refresh hook +- [docs/SKILLS.md](docs/SKILLS.md) — vendored agent skills: inventory, overrides (none), the refresh hook, worktrees - [docs/SOCRATICODE.md](docs/SOCRATICODE.md) — semantic search: tools, the shared store, link stubs, the pin, the memory decision