{"owner":"obra","repo":"superpowers","hasSkills":true,"totalSkillsCount":81,"totalTokensCount":88483,"categories":["marketplace","plugin-manifest","root-instruction","anthropic-skill"],"hasMcp":false,"mcpConfig":null,"found":[".agents/plugins/marketplace.json",".antigravity-plugin/plugin.json",".claude-plugin/marketplace.json",".claude-plugin/plugin.json",".codex-plugin/plugin.json",".cursor-plugin/plugin.json",".devin-plugin/plugin.json",".kimi-plugin/plugin.json",".muse-plugin/marketplace.json",".muse-plugin/plugin.json","AGENTS.md","skills/brainstorming/SKILL.md","skills/brainstorming/builder-check-prompt.md","skills/brainstorming/visual-companion.md","skills/diagnosing-superpowers/SKILL.md","skills/diagnosing-superpowers/prompts/analyst-common.md","skills/diagnosing-superpowers/prompts/cost-and-time.md","skills/diagnosing-superpowers/prompts/plan-adherence.md","skills/diagnosing-superpowers/prompts/quality-evidence.md","skills/diagnosing-superpowers/prompts/repeated-work.md","skills/diagnosing-superpowers/prompts/request-conflicts.md","skills/diagnosing-superpowers/prompts/scrub-audit.md","skills/diagnosing-superpowers/prompts/scrub.md","skills/diagnosing-superpowers/prompts/similar-session.md","skills/diagnosing-superpowers/prompts/skill-timeline.md","skills/diagnosing-superpowers/prompts/stumbles.md","skills/diagnosing-superpowers/references/context-safety.md","skills/diagnosing-superpowers/references/github-issues.md","skills/diagnosing-superpowers/references/redaction-policy.md","skills/diagnosing-superpowers/references/session-discovery.md","skills/diagnosing-superpowers/templates/bundle-README.md","skills/diagnosing-superpowers/templates/case.md","skills/diagnosing-superpowers/templates/issue.md","skills/diagnosing-superpowers/templates/report.md","skills/dispatching-parallel-agents/SKILL.md","skills/executing-plans/SKILL.md","skills/finishing-a-development-branch/SKILL.md","skills/receiving-code-review/SKILL.md","skills/requesting-code-review/SKILL.md","skills/requesting-code-review/code-reviewer.md","skills/subagent-driven-development/SKILL.md","skills/subagent-driven-development/implementer-prompt.md","skills/subagent-driven-development/re-review-prompt.md","skills/subagent-driven-development/references/batching.md","skills/subagent-driven-development/references/cannot-verify.md","skills/subagent-driven-development/references/final-review.md","skills/subagent-driven-development/references/fix-loop.md","skills/subagent-driven-development/references/handling-reports.md","skills/subagent-driven-development/references/preflight.md","skills/subagent-driven-development/references/resuming.md","skills/subagent-driven-development/task-reviewer-prompt.md","skills/systematic-debugging/CREATION-LOG.md","skills/systematic-debugging/SKILL.md","skills/systematic-debugging/condition-based-waiting.md","skills/systematic-debugging/defense-in-depth.md","skills/systematic-debugging/root-cause-tracing.md","skills/systematic-debugging/test-academic.md","skills/systematic-debugging/test-pressure-1.md","skills/systematic-debugging/test-pressure-2.md","skills/systematic-debugging/test-pressure-3.md","skills/test-driven-development/SKILL.md","skills/test-driven-development/writing-good-tests.md","skills/using-git-worktrees/SKILL.md","skills/using-superpowers/SKILL.md","skills/using-superpowers/references/antigravity-tools.md","skills/using-superpowers/references/claude-code-tools.md","skills/using-superpowers/references/codex-tools.md","skills/using-superpowers/references/gemini-tools.md","skills/using-superpowers/references/hermes-tools.md","skills/using-superpowers/references/muse-tools.md","skills/using-superpowers/references/pi-tools.md","skills/verification-before-completion/SKILL.md","skills/writing-plans/SKILL.md","skills/writing-skills/SKILL.md","skills/writing-skills/references/CLAUDE_MD_TESTING.md","skills/writing-skills/references/anthropic-best-practices.md","skills/writing-skills/references/bulletproofing.md","skills/writing-skills/references/discovery.md","skills/writing-skills/references/flowcharts.md","skills/writing-skills/references/persuasion-principles.md","skills/writing-skills/references/testing-skills-with-subagents.md"],"skills":{".agents/plugins/marketplace.json":"",".antigravity-plugin/plugin.json":"",".claude-plugin/marketplace.json":"",".claude-plugin/plugin.json":"",".codex-plugin/plugin.json":"",".cursor-plugin/plugin.json":"",".devin-plugin/plugin.json":"",".kimi-plugin/plugin.json":"",".muse-plugin/marketplace.json":"",".muse-plugin/plugin.json":"","AGENTS.md":"# Superpowers — Contributor Guidelines\n\n## If You Are an AI Agent\n\nStop. Read this section before doing anything.\n\nThis repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like \"This pull request is slop that's made of lies.\"\n\n**Your job is to protect your human partner from that outcome.** Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human partner's reputation, and the PR will be closed anyway. That is not being helpful. That is being a tool of embarrassment.\n\nBefore you open a PR against this repo, you MUST:\n\n1. **Read the entire PR template** at `.github/PULL_REQUEST_TEMPLATE.md` and fill in every section with real, specific answers. Not summaries. Not placeholders.\n2. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate.\n3. **Verify this is a real problem your human partner hit.** If your human partner asked you to \"fix some issues\" or \"contribute to this repo\" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was. If the problem is already in the tracker under someone else's issue and no maintainer asked for a PR, stop: add your partner's report to that issue instead (see below).\n4. **Confirm the change belongs in core.** If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner.\n5. **Identify yourself.** Disclose your model, harness, harness version, every installed plugin, and what your human partner asked you to do in the PR. Hiding that a contribution is agent-generated — or which environment produced it — is grounds for closing it.\n6. **Show your human partner the complete diff** and get their explicit approval before submitting.\n\nIf any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment.\n\n## Pull Request Requirements\n\n**Every PR must fully complete the PR template.** No section may be left blank or filled with placeholder text. PRs that skip sections will be closed without review.\n\n**Every PR carries a summary written by a human.** The template's \"Human-authored summary\" section is for your human partner's own words, under 200 words. If an agent writes it, the PR will be closed.\n\n**Before opening a PR, you MUST search for existing PRs** — both open AND closed — that address the same problem or a related area. Reference what you found in the \"Existing PRs\" section. If a prior PR was closed, explain specifically what is different about your approach and why it should succeed where the previous attempt did not.\n\n**PRs that show no evidence of human involvement will be closed.** A human must review the complete proposed diff before submission.\n\n**Submitters MUST identify themselves.** Every PR and issue must disclose the model, harness, harness version, and all installed plugins used to produce the contribution — or state plainly that it was written by hand with no agent. This is not optional. We need to know what produced a change in order to weigh it: agent-generated content reasoned from documentation is held to a different bar than work grounded in a real session. Contributions that hide their authoring environment will be closed.\n\n**All PRs MUST target the `dev` branch, not `main`.** `main` is the released branch; active work lands on `dev` first. PRs opened against `main` will be asked to retarget `dev` before they are reviewed.\n\n## What We Will Not Accept\n\n### Third-party dependencies\n\nPRs that add optional or required dependencies on third-party projects will not be accepted unless they are adding support for a new harness (e.g., a new IDE or CLI tool). Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin.\n\n### \"Compliance\" changes to skills\n\nOur internal skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior. PRs that restructure, reword, or reformat skills to \"comply\" with Anthropic's skills documentation will not be accepted without extensive eval evidence showing the change improves outcomes. The bar for modifying behavior-shaping content is very high.\n\n### Project-specific or personal configuration\n\nSkills, hooks, or configuration that only benefit a specific project, team, domain, or workflow do not belong in core. Publish these as a separate plugin.\n\n### Fixes for issues filed by someone else\n\nWe do not accept agent-written PRs that fix issues filed by someone other than your human partner unless a maintainer asked for one. That holds when your human partner hit the same problem: add their report to the existing issue instead of opening a PR. An open issue in the tracker is not a request for a PR. If your human partner points you at someone else's issue, tell them the PR will be closed and stop.\n\n### Bulk or spray-and-pray PRs\n\nDo not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to \"fix things\" — will be closed. If you want to contribute, start from a problem your human partner actually hit, understand it deeply, and submit quality work.\n\n### Speculative or theoretical fixes\n\nEvery PR must solve a real problem that someone actually experienced. \"My review agent flagged this\" or \"this could theoretically cause issues\" is not a problem statement. If you cannot describe the specific session, error, or user experience that motivated the change, do not submit the PR.\n\n### Domain-specific skills\n\nSuperpowers core contains general-purpose skills that benefit all users regardless of their project. Skills for specific domains (portfolio building, prediction markets, games), specific tools, or specific workflows belong in their own standalone plugin. Ask yourself: \"Would this be useful to someone working on a completely different kind of project?\" If not, publish it separately.\n\n### Fork-specific changes\n\nIf you maintain a fork with customizations, do not open PRs to sync your fork or push fork-specific changes upstream. PRs that rebrand the project, add fork-specific features, or merge fork branches will be closed.\n\n### Fabricated content\n\nPRs containing invented claims, fabricated problem descriptions, or hallucinated functionality will be closed immediately. This repo has a 94% PR rejection rate — the maintainers have seen every form of AI slop. They will notice.\n\n### Bundled unrelated changes\n\nPRs containing multiple unrelated changes will be closed. Split them into separate PRs.\n\n## New Harness Support\n\nIf your PR adds support for a new harness (IDE, CLI tool, agent runner), you MUST include a session transcript proving the integration works end-to-end.\n\nA real integration loads the `using-superpowers` bootstrap at session start. The bootstrap is what causes skills to auto-trigger at the right moments. Without it, the skills are dead weight — present on disk but never invoked.\n\n**The acceptance test.** Open a clean session in the new harness and send exactly this user message:\n\n> Let's make a react todo list\n\nA working integration auto-triggers the `brainstorming` skill before any code is written. Paste the complete transcript in the PR.\n\n**These are not real integrations and will be closed:**\n\n- Manually copying skill files into the harness\n- Wrapping with `npx skills` or similar at-runtime shims\n- Anything that requires the user to opt in to skills per-session\n- Anything where `brainstorming` does not auto-trigger on the acceptance test above\n\nIf you are not sure whether your integration loads the bootstrap at session start, it does not.\n\n## Skill Changes Require Evaluation\n\nSkills are not prose — they are code that shapes agent behavior. If you modify skill content:\n\n- Use `superpowers:writing-skills` to develop and test changes\n- Run adversarial pressure testing across multiple sessions\n- Show before/after eval results in your PR\n- Do not modify carefully-tuned content (Red Flags tables, rationalization lists, \"human partner\" language) without evidence the change is an improvement\n\n## Eval harness\n\nSkill-behavior evals live in [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Quorum (the harness CLI, one part of that eval lab) drives real coding-agent CLIs — Claude Code, Codex, Gemini, and others — through a Gauntlet QA agent and grades them against scenario acceptance criteria plus deterministic post-checks. Plugin-infrastructure tests still live at `tests/`.\n\n## Understand the Project Before Contributing\n\nBefore proposing changes to skill design, workflow philosophy, or architecture, read existing skills and understand the project's design decisions. Superpowers has its own tested philosophy about skill design, agent behavior shaping, and terminology (e.g., \"your human partner\" is deliberate, not interchangeable with \"the user\"). Changes that rewrite the project's voice or restructure its approach without understanding why it exists will be rejected.\n\n## General\n\n- Read `.github/PULL_REQUEST_TEMPLATE.md` before submitting\n- One problem per PR\n- Test on at least one harness and report results in the environment table\n- Describe the problem you solved, not just what you changed\n","skills/brainstorming/SKILL.md":"---\nname: brainstorming\ndescription: \"You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).\"\n---\n\n# Brainstorming\n\nYou are very good at building. You build what you believe your human\npartner wants, and that belief is usually thinner than it feels. This\nskill is for finding out what they actually want, and why, before\nanything gets built.\n\nPeople often haven't finished working out what they want. Good questions\nhelp them think it through. When you understand the why, you make the\nhundred decisions they never mention the way they would have made them.\n\n## First: What Do You Actually Know?\n\nBefore you reply, ask yourself: what do I know about what they want, and\nwhy?\n\n- **Everything that matters is in the request** (\"make the icon cornflower\n blue\"). This is a quick, clear task. Do it, and say what you did.\n- **Something non-trivial is missing.** Start the conversation.\n\nBefore you start implementing, you must, in order:\n\n1. Lay out the approaches in a message of their own, and have your\n human partner pick one (see Lay out the approaches).\n2. Write the design doc, short or full (see Size the Work).\n3. Get their approval of that doc.\n4. Invoke the superpowers:writing-plans skill.\n\nTwo things aren't implementing: a spike they said yes to (see Spike to\nfeel things out), and doing what they asked once they've opted out of\nthe questions.\n\n## Look Before You Ask\n\nIn an existing project, or when they've given you context (a spec, a plan,\na handoff, files they pointed at, earlier conversation), dig in before your\nfirst message. Read what they referred to and the code or material it\nconnects to, and keep reading until you can explain how the relevant\nparts work today and what this change would touch. Never ask what the\nproject or their context already answers.\n\n## Your First Message\n\nMove the work forward, with one of these:\n\n- **They've already said what they want** (a spec, a plan, a detailed\n request): aim for about 200 words for the whole message. Echo their\n request back in your own words, so they can see whether you've got its\n shape: what they want, who it's for, and why, as far as they've said.\n Add what you found that bears on it: how the relevant parts work today\n and what the change would touch. If you found something they may not\n have considered that would change what they're asking for or how it\n has to be built, like a constraint, a conflict, or a cheaper path, say\n so plainly. How to build it comes later, once you understand what they\n want (see Lay out the approaches). End with one line inviting\n corrections, then one question about what they want: the thing their\n request leaves open whose answer would most change what gets built.\n Specs are often incomplete, so confirm before you build on one.\n- **They haven't:** one open question, in their own terms, about the\n biggest thing their request leaves unsettled. Say why you're asking:\n what the answer would change about what you build. For \"a website for\n my bakery\": \"If it's mostly for people deciding whether to stop by,\n I'd lead with hours and what's in the case today; taking orders is a\n different site. What do you want someone to do when they land on it?\"\n\nHow the message ends depends on whether their message asked for\nbrainstorming:\n\n- **They asked for it** (by name, by invoking it, or by asking for a\n design discussion): end with your question. They want this\n conversation.\n- **They didn't:** they may not want a conversation at all. After your\n question, add a light, one-line offer to just get going instead, like\n \"Or if you'd rather I just dive in, say so.\" If they take you up on\n it, this skill is done: state any significant how-it-gets-made choice\n (platform, language, medium) in one plain line, then do what they\n asked through the normal workflow.\n\nThat's the whole message.\n\n## The Conversation\n\nEach message ends with one question: a single sentence with no list of\nexample answers hanging off it. Use plain language, pitched just a little\nabove where your human partner is. Match their vocabulary; never use\nprocess jargon. You never need to quote this skill to your human\npartner.\n\nBe clear and concise. Lead with what matters. Avoid jargon. When you\nreport what you found, give them the most important findings and offer\nthe rest.\n\n**Get them describing.** Open questions come first. Their own words carry\nintent that your options can't. Offer a short menu only when they're\nstuck. When they say \"just guess\" or \"what do you think?\", propose\nsomething concrete.\n\n**How it gets made.** Every project rests on choices about medium, tools,\nmaterials, and resources: the platform, programming language, and\nlibraries for an app; the medium for a piece of art. Find out early which\nof those choices they want to make, which they're handing to you, and what\nthey already have to work with. Someone with strong views or skills will\nwant to talk it through. Someone counting on you needs sensible defaults,\nsaid in plain words. When there's existing work, build on what it already\nuses. Any choice you make goes in the design as your call, never as\nsomething they agreed to.\n\n**Ground to cover.** This is territory, not a script. Never read these\nout as questions:\n\n- what kind of thing this is, and what makes it special\n- why now, and what success looks like to them\n- goals, non-goals, and anti-goals (what would make this a failure even\n if it technically works)\n- prior art: what they've seen elsewhere, loved or hated\n- current state: what exists now, what they've tried\n- the details they care about\n\n**Make every question specific** to their project and what they've told\nyou. Ask Socratically, the way a sharp colleague would: build each\nquestion on their last answer or on something you found, so it helps\nthem think through a consequence or a case they may have missed\n(\"Voting closes before the meeting, and two members joined this month.\nDoes someone who joins mid-round get a vote?\"). When the reason isn't\nalready plain, say what you're hoping to learn or what the answer would\nchange. A proposal they can correct, plus your reason for it, often\nbeats a question.\n\n**Offer recon.** Once you have a bit of grounding and looking further\nwould help, offer to go look: deeper into their codebase or project,\ntheir own files and data, or the web. Say what you'd look for. They\ndecide whether you go.\n\n**Lay out the approaches.** Once you understand what they want, and\nbefore you write anything up, put the ways of building it in a message\nof its own. Come up with several real alternatives and drop the weak\nones, including any that work against why they want it and any the\nexisting work rules out. Present the two or three that remain, grounding\neach in what the project actually does and saying what it trades off.\nRecommend one and say why, then ask which way they want to go. When\nthere's genuinely one sensible way, say so and explain why the others\ndon't fit. This is for how it gets built; for what they want, get them\ndescribing first.\n\n**Show, don't tell.** Offer the visual companion (below) whenever seeing\nwould help more than reading:\n\n- something they'll look at: a screen, a page, a printout, a sign\n- a layout or arrangement: of a screen, a room, a schedule\n- a flow or a sequence of steps\n- options that would look different from each other\n- a structure that's easier to see than read: a diagram, a timeline, a map\n\nOnce they've accepted, use it for mockups to react to, side-by-side\noptions, and throwaway prototypes they can click.\n\n**Spike to feel things out.** Agentic work is waterfall, but very, very\nfast. A quick throwaway build is often the cheapest way to learn what\nthey want or whether something works. Offer one when it would help.\nWhen they just want to spike, get out of the way. Spikes get no tests\nor minimal ones, aren't bulletproof, and skip the plan, implementation,\nand review process. Bring what the spike taught you back into the\nconversation.\n\n## Play It Back\n\nPlay back as you go. As soon as you understand one part well enough to\ndescribe it (what it's for and who it serves, say, or how one piece\nbehaves), describe that part back in about 200-300 words, then return to\nquestions about the next part. Playback and questions alternate through\nthe whole conversation; the last chunk covers whatever is left.\n\nOnly what they said goes in as theirs. Anything you filled in goes in\nas your proposal, with your reason. End each chunk by asking what's wrong\nor missing.\n\nBefore you send a chunk, check it: does it describe something they'll\nlook at, like a page, a screen, a schedule, or a printout? If so, and\nthey haven't seen the visual companion offer yet, send the offer instead\n(its own message, below) and hold the chunk for the next message. Once\nthey've accepted, put a mockup next to the description.\n\n## Size the Work\n\nOnce you understand what they want and they've picked an approach, say\nhow big the work is in plain words. They can override it.\n\n| Size | The design doc |\n|------|----------------|\n| A small change | a short one: what you already covered together, written down |\n| A project | the full written design (below) |\n\nShort or full, the design doc has an **Approaches** part: the two or\nthree ways you considered building it, what each trades off, which one\nthey picked, and why. They pick in the conversation, before you write\nthe doc.\n\nIf it grows mid-task, stop, say so, and step up a size.\n\nIf this is really several independent projects, say so, agree on an\norder, and brainstorm them one at a time.\n\n## The Written Design\n\nWrite a plain document a talented builder in the domain could plan\nfrom without going back to your human partner. Cover:\n\n- intent and the why\n- goals, non-goals, anti-goals\n- constraints\n- approaches (above)\n- the parts of the how they decided, as they decided them\n- what's left to the builder\n\nFor a small change, the short design covers the same points in a line\nor two each and goes straight to your human partner, without the\nbuilder check.\n\n**Where it goes:** in a software repo,\n`docs/superpowers/specs/YYYY-MM-DD--design.md`, committed.\nOtherwise, ask. Your human partner's preferences override both.\n\n**Builder check** (for a project): dispatch a fresh subagent with\n`builder-check-prompt.md` in this directory. When you tell your human\npartner you're writing it up, say a reviewer will read it first and you\nmay come back once with a few questions. Don't hand over the document\nuntil the check is back. Sort what the builder asks into three piles:\n\n- **Answered already** by the conversation or the project: put the answer\n in the document.\n- **Minor:** a sensible builder could settle it without changing what gets\n built. Settle it yourself and mark it in the document as your call.\n- **Theirs:** only your human partner can answer it, and the answer changes\n what gets built.\n\nBring the \"theirs\" pile in one message, most important first. Update the\ndocument with their answers, then hand it over with a short list of the\ncalls you made so they can check those while reading. That's the only\nround of questions the check produces. Without a subagent tool, read the\ndocument as that builder yourself.\n\n\nNothing gets built until your human partner approves the design doc:\nthe short one for a small change, the full one for a project.\nBuilding includes writing product code, scaffolding, installing\ndependencies, creating projects, and invoking an implementation skill.\nReading and exploring are fine.\n\nTwo exceptions. If they opted out of the questions, the skill is done\nand the gate goes with it. A spike they said yes to may be built; it\nstays labeled throwaway, and keeping what it produced is a new request\nthat comes back through this gate.\n\nAfter the design doc is approved, the next step is the plan: invoke\nsuperpowers:writing-plans and no other skill.\n\n\n## Red Flags\n\n| Thought | Reality |\n|---------|---------|\n| \"I'll offer a menu of what they might want\" | Options steer. Ask them to describe it first. |\n| \"I'll fill in sensible defaults\" | Good. Say them out loud. A default they never heard is one they couldn't reject. |\n| \"I've answered their questions, so I'll write the doc\" | Lay out the approaches first, in a message of their own. |\n| \"I should explain the process first\" | Ask your question. The process shows itself. |\n| \"They said 'sounds good' to the idea\" | Approval covers what you showed them. A design doc you haven't written isn't approved. |\n| \"The spike works, I'll keep building on it\" | Keeping it is a new request. Back through the gate. |\n\n## Visual Companion\n\nA browser tab for showing mockups, diagrams, and prototypes. It's a\ntool, not a mode: accepting it doesn't send every question to the\nbrowser.\n\n**Offer it just-in-time.** Offer it the first time one of the moments\nabove comes up, never upfront. The offer is its own message with nothing\nelse in it:\n\n> \"This might be easier if I show you. Want me to open a browser tab with some mockups?\"\n\nIf they decline, stay in text and don't offer again unless they raise it.\n\n**Per question, ask: would they understand this better by seeing it?**\nMockups, layouts, diagrams, and side-by-side designs go in the browser.\nRequirements, scope, tradeoffs, and conceptual choices stay in text. A\nquestion about a UI topic isn't automatically a visual question.\n\nIf they accept, read `visual-companion.md` in this directory before\nstarting the server.\n","skills/brainstorming/builder-check-prompt.md":"# Builder Check Prompt\n\nDispatch a fresh general-purpose subagent with this prompt once the\nwritten design exists. Fill in the domain and the document path.\n\n```\nYou are a talented [DOMAIN, e.g. \"software engineer\", \"event planner\",\n\"bakery consultant\"]. You've been handed a design document and asked to\nput together a plan to build what it describes. You will not be able to\ntalk to the person who wrote it.\n\nRead [DOCUMENT_PATH].\n\nReport only the questions you'd still need answered before you could plan\nthis well: places where you'd have to guess and a wrong guess would\nmatter. For each, give the question and why the answer changes the plan.\nRank them by importance.\n\nSkip anything the document explicitly leaves to the builder, and anything\nyou could reasonably decide yourself. Skip nitpicks about wording.\n\nIf nothing important is left, say \"nothing important left\".\n```\n","skills/brainstorming/visual-companion.md":"# Visual Companion Guide\n\nBrowser-based visual brainstorming companion for showing mockups, diagrams, and options.\n\n## When to Use\n\nDecide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**\n\n**Use the browser** when the content itself is visual:\n\n- **UI mockups** — wireframes, layouts, navigation structures, component designs\n- **Architecture diagrams** — system components, data flow, relationship maps\n- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions\n- **Design polish** — when the question is about look and feel, spacing, visual hierarchy\n- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams\n\n**Use the terminal** when the content is text or tabular:\n\n- **Requirements and scope questions** — \"what does X mean?\", \"which features are in scope?\"\n- **Conceptual A/B/C choices** — picking between approaches described in words\n- **Tradeoff lists** — pros/cons, comparison tables\n- **Technical decisions** — API design, data modeling, architectural approach selection\n- **Clarifying questions** — anything where the answer is words, not a visual preference\n\nA question *about* a UI topic is not automatically a visual question. \"What kind of wizard do you want?\" is conceptual — use the terminal. \"Which of these wizard layouts feels right?\" is visual — use the browser.\n\n## How It Works\n\nThe server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.\n\n**Content fragments vs full documents:** If your HTML file starts with `/.superpowers/brainstorm/` for the session directory.\n\n**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.\n\n**Launching the server by platform:**\n\n**Claude Code:**\n```bash\n# Default mode works — the script backgrounds the server itself.\nbash scripts/start-server.sh --project-dir /path/to/project --open\n```\n\nOn Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.\n\n**Codex:**\n```bash\n# Codex reaps background processes. The script auto-detects CODEX_CI and\n# switches to foreground mode. Run it normally — no extra flags needed.\nbash scripts/start-server.sh --project-dir /path/to/project --open\n```\n\n**Gemini CLI:**\n```bash\n# Use --foreground and set is_background: true on your shell tool call\n# so the process survives across turns\nbash scripts/start-server.sh --project-dir /path/to/project --open --foreground\n```\n\n**Copilot CLI:**\n```bash\n# Start it with Copilot CLI's non-blocking/background shell mechanism so the\n# server survives across turns. Keep --foreground so the harness, not the\n# script, owns backgrounding. The launcher is a .sh, so invoke it via bash\n# (on Windows, call Git Bash's bash.exe from the PowerShell tool).\nbash scripts/start-server.sh --project-dir /path/to/project --open --foreground\n```\n\n**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.\n\nIf the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:\n\n```bash\nbash scripts/start-server.sh \\\n --project-dir /path/to/project \\\n --host 0.0.0.0 \\\n --url-host localhost\n```\n\nUse `--url-host` to control what hostname is printed in the returned URL JSON.\n\n## The Loop\n\n1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:\n - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a \"paused\" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).\n - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`\n - **Never reuse filenames** — each screen gets a fresh file\n - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)\n - Server automatically serves the newest file\n\n2. **Tell user what to expect and end your turn:**\n - Remind them of the URL (every step, not just first)\n - Give a brief text summary of what's on screen (e.g., \"Showing 3 layout options for the homepage\")\n - Ask them to respond in the terminal: \"Take a look and let me know what you think. Click to select an option if you'd like.\"\n\n3. **On your next turn** — after the user responds in the terminal:\n - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines\n - Merge with the user's terminal text to get the full picture\n - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data\n\n4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.\n\n5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:\n\n ```html\n \n
\n

Continuing in terminal...

\n
\n ```\n\n This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.\n\n6. Repeat until done.\n\n## Writing Content Fragments\n\nWrite just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, connection status, and all interactive infrastructure).\n\n**Minimal example:**\n\n```html\n

Which layout works better?

\n

Consider readability and visual hierarchy

\n\n
\n
\n
A
\n
\n

Single Column

\n

Clean, focused reading experience

\n
\n
\n
\n
B
\n
\n

Two Column

\n

Sidebar navigation with main content

\n
\n
\n
\n```\n\nThat's it. No ``, no CSS, no `