@locksmithdon/dons-flow 2.1.2 → 2.2.0

package/skills/dons-flow/SKILL.md

@@ -26,14 +26,13 @@ This skill is the map. It does not replace the skills it references — it helps
 
 ## Required installed packages
 
-This skill assumes the following are available:
+This skill assumes the following are installed with the package:
 
-- **Superpowers** — the upstream methodology. Installed as a harness plugin (Claude, Codex, Gemini, Cursor, Copilot, etc.), not via npm. See `setup-dons-flow` for per-harness commands. This is the only manual install step.
-- **RPIV** (`@juicesharp/rpiv-pi`) — the observable delivery pipeline. Peer dependency; auto-installed with npm 7+ when you install `@locksmithdon/dons-flow`.
-- **Pi subagent runtime** (`@tintinweb/pi-subagents`) — runtime used by RPIV. Peer dependency; auto-installed with npm 7+ when you install `@locksmithdon/dons-flow`.
-- **Don's Flow** (`@locksmithdon/dons-flow`) — this package, which adds closeout and discipline skills.
+- **Superpowers** skills — vendored into the package at `vendor/superpowers/skills/`.
+- **RPIV** skills and runtime extensions — installed as npm dependencies.
+- **Don's Flow** skills — this package's own skills in `skills/`.
 
-If RPIV or the subagent runtime is missing, install them explicitly. If Superpowers is missing, this package's ported skills still provide the closeout workflow, but you will not have access to the upstream Superpowers entry points like `brainstorming` or `test-driven-development`.
+There are no separate installs. If `@locksmithdon/dons-flow` is missing, run `pi install npm:@locksmithdon/dons-flow`.
 
 ## Before you start
 
@@ -43,7 +42,7 @@ If this repo has not been onboarded yet, run:
 /skill:setup-dons-flow
 ```
 
-That skill checks prerequisites, detects Superpowers, installs RPIV's sibling extensions via `/rpiv-setup`, and creates the repo-owned conventions (`docs/tabled.md`, `docs/status.md`, `docs/memory/`, `docs/changes/`, `docs/retros/`, `docs/runbooks/`, `AGENTS.md`).
+That skill checks that the package is installed and creates the repo-owned conventions (`docs/tabled.md`, `docs/status.md`, `docs/memory/`, `docs/changes/`, `docs/retros/`, `docs/runbooks/`, `AGENTS.md`).
 
 ## Three modes of working
 
@@ -175,7 +174,7 @@ Discover → Research → Design/Blueprint → Plan → Implement → Validate
 
 **What it produces:** `.rpiv/artifacts/reviews/<slug>_<scope>.md`
 
-**Integration note:** The `land` skill's step 1 (code review) can consume this artifact. Fix small findings now; table substantive ones to `docs/tabled/`.
+**Integration note:** The `land` skill's step 1 (code review) can consume this artifact. Fix small findings now; table substantive ones in `docs/tabled.md`.
 
 ### 8. Commit — atomic, logical commits
 
@@ -215,7 +214,7 @@ We intentionally deferred deciding how to track Superpowers long-term. Review mo
 - `docs/memory/monitor_upstream_evolution.md` — decision context and last review date
 - `docs/runbooks/monitor-upstream-evolution.md` — the check-in process
 
-After 2–3 projects, decide whether to keep the harness-plugin arrangement, fork Superpowers, or drop the peer dependency.
+After 2–3 projects, decide whether to keep vendoring Superpowers skills, fork Superpowers, or drop the Superpowers integration.
 
 ## Cross-cutting practices
 
@@ -243,8 +242,7 @@ Your codebase should contain these documents and folders. They are owned by the
 
 | Path | Purpose |
 |---|---|
-| `docs/tabled.md` | Working memory for epiphanies and deferred work |
-| `docs/tabled/` | Optional per-item tabled docs (resolved to empty each cycle) |
+| `docs/tabled.md` | Working memory for epiphanies and deferred work (resolved to empty each cycle) |
 | `docs/status.md` | Living status: Recently Completed, What's Next, etc. |
 | `docs/memory/` | Persistent project/session memory entries |
 | `docs/memory/MEMORY.md` | Index of memory entries |

package/skills/land/SKILL.md

@@ -30,7 +30,7 @@ Land has 10 ordered sub-steps. **Each sub-step is a conversation between agent a
 
 ### 1. Code review
 
-Comprehensive, back-and-forth review of all code that landed during this cycle. Find issues; fix small ones now, table substantive ones to `docs/tabled/`. Often a substantial conversation in itself.
+Comprehensive, back-and-forth review of all code that landed during this cycle. Find issues; fix small ones now, table substantive ones in `docs/tabled.md`. Often a substantial conversation in itself.
 
 ### 2. Architectural review
 
@@ -66,7 +66,7 @@ Reflect on the cycle. What went well, what was hard, patterns to capture, anti-p
 
 ### 9. Status review + tabled-items confirmation + next piece of work
 
-Walk through `docs/status.md` intentionally with the cycle's tabled items in hand. Decide what belongs in "Recently Completed," "What's Next," what to prune. **Resolve every tabled item** — either decide-now (document the decision and delete the tabled doc) or move-to-status (substance moves to "What's Next" and the tabled doc is deleted). `docs/tabled/` should end the cycle empty (just `.gitkeep`). Identify the next piece of work — usually the highest-priority moved-to-status item.
+Walk through `docs/status.md` intentionally with the cycle's tabled items in hand. Decide what belongs in "Recently Completed," "What's Next," what to prune. **Resolve every tabled item** — either decide-now (document the decision and remove the entry) or move-to-status (substance moves to "What's Next" and the entry is removed). `docs/tabled.md` should end the cycle empty (or near-empty). Identify the next piece of work — usually the highest-priority moved-to-status item.
 
 ### 10. Integrate
 

package/skills/setup-dons-flow/SKILL.md

@@ -1,37 +1,35 @@
 ---
 name: setup-dons-flow
-description: Use when installing or onboarding @locksmithdon/dons-flow in a repo — checks dependencies, detects Superpowers, and creates repo conventions
+description: Use when installing or onboarding @locksmithdon/dons-flow in a repo — checks the package and creates repo conventions
 ---
 
 # Setup Don's Flow
 
-Onboard a repo to the Don's Flow v2 triad: **Superpowers** + **RPIV** + **Don's closeout discipline**. This skill checks prerequisites, detects what is already installed, creates the repo-owned conventions, and tells you what still needs to be done.
+Onboard a repo to Don's Flow. This skill checks that the package is installed and creates the repo-owned conventions.
 
 ## Announce at start
 
-> "I'm using the `setup-dons-flow` skill to onboard this repo to Don's Flow v2."
+> "I'm using the `setup-dons-flow` skill to onboard this repo to Don's Flow."
 
 ## When to use
 
 - Right after installing `@locksmithdon/dons-flow` in a repo.
-- When you suspect prerequisites are missing.
 - When setting up a fresh repo for this workflow.
-- After switching to a new agent harness.
 
-## What Don's Flow needs
+## What Don's Flow installs
 
-| Component | What it is | How it is installed |
-|---|---|---|
-| **Superpowers** | Agentic methodology (brainstorming, TDD, subagent-driven development) | Harness plugin (Claude, Codex, Gemini, Cursor, etc.) |
-| **RPIV** | Observable delivery pipeline (`discover → ... → commit`) | `pi install npm:@juicesharp/rpiv-pi` |
-| **Pi subagent runtime** | Runtime used by RPIV | `pi install npm:@tintinweb/pi-subagents` |
-| **Don's Flow** | This package: closeout, scope control, learning capture | `pi install npm:@locksmithdon/dons-flow` |
+`pi install npm:@locksmithdon/dons-flow` brings everything with it:
 
-Superpowers is not an npm package and cannot be installed via `pi install` or `npm install`. It must be installed as a harness plugin.
+- **RPIV** skills (`discover`, `research`, `blueprint`, `implement`, `validate`, `code-review`, etc.)
+- **RPIV runtime extensions** (`rpiv-todo`, `rpiv-workflow`, etc.)
+- **Superpowers** skills (`brainstorming`, `writing-plans`, `test-driven-development`, `subagent-driven-development`, etc.)
+- **Don's Flow** skills (`land`, `epiphany-tabling`, `capturing-learnings`, etc.)
+
+There are no separate installs for RPIV or Superpowers.
 
 ## Process
 
-### Step 1: Detect installed Pi packages and install RPIV siblings
+### Step 1: Verify the package is installed
 
 Run:
 
@@ -39,104 +37,15 @@ Run:
 pi list
 ```
 
-Look for:
-
-| Package | Required? | If missing |
-|---|---|---|
-| `npm:@juicesharp/rpiv-pi` | Yes | Peer dependency; auto-installed with npm 7+ when you install `@locksmithdon/dons-flow`. If not, run `pi install npm:@juicesharp/rpiv-pi`. |
-| `npm:@tintinweb/pi-subagents` | Yes | Peer dependency; auto-installed with npm 7+ when you install `@locksmithdon/dons-flow`. If not, run `pi install npm:@tintinweb/pi-subagents`. |
-| `npm:@locksmithdon/dons-flow` | Yes | `pi install npm:@locksmithdon/dons-flow` |
-
-If RPIV is installed but its sibling extensions are missing, run RPIV's setup command automatically:
+Look for `npm:@locksmithdon/dons-flow`. If it is missing, install it:
 
 ```bash
-/rpiv-setup
+pi install npm:@locksmithdon/dons-flow
 ```
 
-This installs the sibling plugins:
-
-- `@juicesharp/rpiv-ask-user-question`
-- `@juicesharp/rpiv-todo`
-- `@juicesharp/rpiv-advisor`
-- `@juicesharp/rpiv-i18n`
-- `@juicesharp/rpiv-web-tools`
-- `@juicesharp/rpiv-args`
-- `@juicesharp/rpiv-workflow`
-
-After `/rpiv-setup` completes, **restart Pi** so the new extensions are loaded. Then re-run `/skill:setup-dons-flow` to continue onboarding.
-
-If you cannot restart Pi in this session, report the remaining siblings to the user and ask them to restart before proceeding.
-
-### Step 2: Detect Superpowers
-
-Superpowers is installed via your agent harness, not as a Pi npm package. Check the appropriate method for your harness:
-
-**Claude Code**
-```bash
-/plugin list
-```
-Look for `superpowers`. If missing:
-```bash
-/plugin install superpowers@claude-plugins-official
-```
-Or via the Superpowers marketplace:
-```bash
-/plugin marketplace add obra/superpowers-marketplace
-/plugin install superpowers@superpowers-marketplace
-```
-
-**Codex CLI / Codex App**
-```bash
-/plugins
-```
-Search for "Superpowers" and install it.
-
-**Gemini CLI**
-```bash
-gemini extensions list
-```
-If missing:
-```bash
-gemini extensions install https://github.com/obra/superpowers
-```
-
-**Factory Droid**
-```bash
-droid plugin list
-```
-If missing:
-```bash
-droid plugin marketplace add https://github.com/obra/superpowers
-droid plugin install superpowers@superpowers
-```
-
-**OpenCode**
-```bash
-# Fetch and follow instructions from:
-# https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
-```
-
-**Cursor**
-```bash
-/add-plugin superpowers
-```
-Or search "superpowers" in the plugin marketplace.
-
-**GitHub Copilot CLI**
-```bash
-copilot plugin list
-```
-If missing:
-```bash
-copilot plugin marketplace add obra/superpowers-marketplace
-copilot plugin install superpowers@superpowers-marketplace
-```
-
-If you are unsure which harness is active, ask the user. Do not guess.
-
-If Superpowers is not installed, explain that the closeout workflow in this package still works, but the upstream Superpowers entry points (`brainstorming`, `test-driven-development`, `subagent-driven-development`) will not be available.
+If RPIV emits a warning about missing sibling extensions, wait for the install to finish and then restart Pi. The package declares all required RPIV extensions as dependencies, so they install automatically.
 
-### Step 3: Check repo conventions
+### Step 2: Check repo conventions
 
 Check whether these project-owned files and folders exist:
 
@@ -149,7 +58,6 @@ Expected:
 | Path | Purpose |
 |---|---|
 | `docs/tabled.md` | Working memory for deferred ideas |
-| `docs/tabled/` | Optional per-item tabled docs |
 | `docs/status.md` | Living status |
 | `docs/memory/` | Persistent memory + `MEMORY.md` index |
 | `docs/changes/` | As-built documentation |
@@ -157,12 +65,12 @@ Expected:
 | `docs/runbooks/` | Multi-skill processes |
 | `AGENTS.md` | Repo-level agent guidance |
 
-### Step 4: Create missing conventions
+### Step 3: Create missing conventions
 
 If the user approves, create missing conventions:
 
 ```bash
-mkdir -p docs/{tabled,memory,changes,retros,runbooks}
+mkdir -p docs/{memory,changes,retros,runbooks}
 touch docs/tabled.md docs/status.md docs/memory/MEMORY.md AGENTS.md
 ```
 
@@ -196,30 +104,28 @@ Cross-session context for this project.
 _None yet._
 ```
 
-Seed `AGENTS.md` with a minimal entry pointing at this workflow:
+Seed `AGENTS.md` with a minimal entry:
 
 ```markdown
 # AGENTS.md
 
 This project uses the `@locksmithdon/dons-flow` workflow:
-- Superpowers for design, planning, TDD, and subagent-driven development.
 - RPIV pipeline for discovery, research, design/plan, implement, validate, review, commit.
+- Superpowers skills for brainstorming, planning, TDD, and subagent-driven development.
 - `land` skill for 10-step cycle closeout.
 
 See `docs/runbooks/` for detailed processes and `docs/memory/` for project context.
 ```
 
-### Step 5: Report status and next steps
+### Step 4: Report status and next steps
 
 Present a concise summary:
 
 ```
 Setup status for <repo>:
 
-✓ RPIV installed
-✗ @tintinweb/pi-subagents missing — run: pi install npm:@tintinweb/pi-subagents
+✓ @locksmithdon/dons-flow installed
 ✓ Repo conventions created
-✓ Superpowers detected (Claude Code plugin)
 
 Next step: /skill:dons-flow to see the workflow map.
 ```
@@ -227,11 +133,9 @@ Next step: /skill:dons-flow to see the workflow map.
 ## Anti-patterns
 
 - **Creating conventions without asking.** The repo belongs to the team; don't mutate its doc structure unilaterally.
-- **Guessing the harness.** Always detect or ask which agent harness is in use before giving Superpowers install instructions.
-- **Treating Superpowers as optional decoration.** It is one of the three pillars of this workflow. Detect it accurately and install it if possible.
-- **Installing packages without confirmation.** Present the install commands; let the human run them.
+- **Trying to install Superpowers or RPIV separately.** They ship with this package.
 
 ## Integration
 
 - Called automatically on first install if an extension hook is added later.
-- Should be re-run after major RPIV or Superpowers updates to refresh conventions.
+- Should be re-run after major Don's Flow updates to refresh conventions.

package/skills/sync-upstream/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: sync-upstream
+description: Run the upstream sync script to clone/pull Superpowers and RPIV, diff against last-synced hashes, and produce a decision report
+---
+
+# Sync Upstream
+
+Keep Don's Flow current with its two upstream partners: **Superpowers** and **RPIV**. This skill runs a script that:
+
+1. Clones or pulls `obra/superpowers` into `vendor/superpowers-source/`.
+2. Copies selected Superpowers skills into `vendor/superpowers/skills/` (the vendored copy that ships with the package).
+3. Clones or pulls `juicesharp/rpiv-mono` to review RPIV changes.
+4. Compares the current HEAD of each repo against the last-synced hash.
+5. Emits a dated report in `docs/memory/upstream-sync-YYYY-MM-DD.md`.
+6. Updates `docs/memory/.upstream-last-sync.json` so the next run only shows new changes.
+
+## Announce at start
+
+> "I'm using the `sync-upstream` skill to pull the latest Superpowers and RPIV changes and decide what to incorporate into Don's Flow."
+
+## When to use
+
+- Monthly, per `docs/runbooks/monitor-upstream-evolution.md`.
+- After a project closeout where upstream behavior felt different.
+- Before a new release of `@locksmithdon/dons-flow`.
+
+## Process
+
+### Step 1: Run the sync script
+
+```bash
+./scripts/sync-upstream.sh
+```
+
+The script requires:
+- `git`
+- `jq`
+- network access to GitHub
+
+If `jq` is missing, install it (`brew install jq` on macOS, `apt-get install jq` on Debian/Ubuntu).
+
+### Step 2: Read the report
+
+Open the generated report:
+
+```bash
+ls docs/memory/upstream-sync-*.md | tail -1
+```
+
+The report contains:
+- Last-synced and current commit hashes for both repos.
+- Commit log since last sync.
+- Diff stat since last sync.
+- Empty **Decisions** sections for Superpowers and RPIV.
+
+### Step 3: Decide what to incorporate
+
+For each upstream change, choose:
+
+- **Incorporate** — pull the change into Don's Flow now.
+- **Defer** — relevant but not urgent; note it for next cycle.
+- **Skip** — not relevant to Don's Flow.
+
+Edit the report in place with your decisions and impact notes.
+
+### Step 4: Apply incorporated changes
+
+Typical changes to make:
+
+- **Superpowers skills changed** — the sync script already copies the selected skills into `vendor/superpowers/skills/`. Review the diff and commit the updated vendored skills.
+- **Superpowers adds a new skill** — decide whether to add it to the vendored list in `scripts/sync-upstream.sh`.
+- **RPIV version changed** — bump the RPIV dependency versions in `package.json`.
+- **Workflow instructions changed** — update `README.md`, `skills/setup-dons-flow/SKILL.md`, and `skills/dons-flow/SKILL.md`.
+
+### Step 5: Release
+
+After applying changes:
+
+1. Update `docs/memory/monitor_upstream_evolution.md` with the decision summary.
+2. Bump `package.json` version.
+3. Commit and push.
+4. Publish to npm.
+
+## Anti-patterns
+
+- **Syncing without reviewing.** The script only surfaces changes; a human must decide what to do with them.
+- **Updating hashes without applying changes.** If you bump `.last-sync.json` but do not act on the diff, you lose track of what you skipped.
+- **Incorporating blindly.** Upstream changes may conflict with Don's Flow conventions. Review before copying.
+
+## See also
+
+- `docs/runbooks/monitor-upstream-evolution.md` — the monthly runbook
+- `docs/memory/monitor_upstream_evolution.md` — long-term decision context
+- `scripts/sync-upstream.sh` — the underlying script

package/vendor/superpowers/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/superpowers/skills/brainstorming/SKILL.md

@@ -0,0 +1,164 @@
+---
+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."
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. 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/superpowers/specs/YYYY-MM-DD-<topic>-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 {
+    "Explore project context" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message, no other content)" [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];
+
+    "Explore project context" -> "Visual questions ahead?";
+    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
+    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
+    "Offer Visual Companion\n(own message, no other content)" -> "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"];
+}
+```
+
+**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+
+## The 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
+
+**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
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-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 `<path>`. 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.
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## 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:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+
+**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`