📦 deps(skills): sync superpowers
Update Third-party Superpowers / Update thirdparty/skill snapshot (push) Successful in 1m25s
Details
Update Third-party Superpowers / Update thirdparty/skill snapshot (push) Successful in 1m25s
Details
This commit is contained in:
ci-bot
parent
7b84daf3bd
commit
00a07e58db
|
|
@ -5,44 +5,135 @@ description: "You MUST use this before any creative work - creating features, bu
|
||||||
|
|
||||||
# Brainstorming Ideas Into Designs
|
# Brainstorming Ideas Into Designs
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
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 in small sections (200-300 words), checking after each section whether it looks right so far.
|
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 review loop** — dispatch spec-document-reviewer subagent with precisely crafted review context (never your session history); fix issues and re-dispatch until approved (max 5 iterations, then surface to human)
|
||||||
|
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 review loop" [shape=box];
|
||||||
|
"Spec review passed?" [shape=diamond];
|
||||||
|
"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 review loop";
|
||||||
|
"Spec review loop" -> "Spec review passed?";
|
||||||
|
"Spec review passed?" -> "Spec review loop" [label="issues found,\nfix and re-dispatch"];
|
||||||
|
"Spec review passed?" -> "User reviews spec?" [label="approved"];
|
||||||
|
"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
|
## The Process
|
||||||
|
|
||||||
**Understanding the idea:**
|
**Understanding the idea:**
|
||||||
|
|
||||||
- Check out the current project state first (files, docs, recent commits)
|
- Check out the current project state first (files, docs, recent commits)
|
||||||
- Ask questions one at a time to refine the idea
|
- 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
|
- 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
|
- Only one question per message - if a topic needs more exploration, break it into multiple questions
|
||||||
- Focus on understanding: purpose, constraints, success criteria
|
- Focus on understanding: purpose, constraints, success criteria
|
||||||
|
|
||||||
**Exploring approaches:**
|
**Exploring approaches:**
|
||||||
|
|
||||||
- Propose 2-3 different approaches with trade-offs
|
- Propose 2-3 different approaches with trade-offs
|
||||||
- Present options conversationally with your recommendation and reasoning
|
- Present options conversationally with your recommendation and reasoning
|
||||||
- Lead with your recommended option and explain why
|
- Lead with your recommended option and explain why
|
||||||
|
|
||||||
**Presenting the design:**
|
**Presenting the design:**
|
||||||
|
|
||||||
- Once you believe you understand what you're building, present the design
|
- Once you believe you understand what you're building, present the design
|
||||||
- Break it into sections of 200-300 words
|
- 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
|
- Ask after each section whether it looks right so far
|
||||||
- Cover: architecture, components, data flow, error handling, testing
|
- Cover: architecture, components, data flow, error handling, testing
|
||||||
- Be ready to go back and clarify if something doesn't make sense
|
- 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
|
## After the Design
|
||||||
|
|
||||||
**Documentation:**
|
**Documentation:**
|
||||||
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
|
|
||||||
|
- 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
|
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
||||||
- Commit the design document to git
|
- Commit the design document to git
|
||||||
|
|
||||||
**Implementation (if continuing):**
|
**Spec Review Loop:**
|
||||||
- Ask: "Ready to set up for implementation?"
|
After writing the spec document:
|
||||||
- Use superpowers:using-git-worktrees to create isolated workspace
|
|
||||||
- Use superpowers:writing-plans to create detailed implementation plan
|
1. Dispatch spec-document-reviewer subagent (see spec-document-reviewer-prompt.md)
|
||||||
|
2. If Issues Found: fix, re-dispatch, repeat until Approved
|
||||||
|
3. If loop exceeds 5 iterations, surface to human for guidance
|
||||||
|
|
||||||
|
**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
|
## Key Principles
|
||||||
|
|
||||||
|
|
@ -50,5 +141,24 @@ Start by understanding the current project context, then ask questions one at a
|
||||||
- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
||||||
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
||||||
- **Explore alternatives** - Always propose 2-3 approaches before settling
|
- **Explore alternatives** - Always propose 2-3 approaches before settling
|
||||||
- **Incremental validation** - Present design in sections, validate each
|
- **Incremental validation** - Present design, get approval before moving on
|
||||||
- **Be flexible** - Go back and clarify when something doesn't make sense
|
- **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`
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,214 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<title>Superpowers Brainstorming</title>
|
||||||
|
<style>
|
||||||
|
/*
|
||||||
|
* BRAINSTORM COMPANION FRAME TEMPLATE
|
||||||
|
*
|
||||||
|
* This template provides a consistent frame with:
|
||||||
|
* - OS-aware light/dark theming
|
||||||
|
* - Fixed header and selection indicator bar
|
||||||
|
* - Scrollable main content area
|
||||||
|
* - CSS helpers for common UI patterns
|
||||||
|
*
|
||||||
|
* Content is injected via placeholder comment in #claude-content.
|
||||||
|
*/
|
||||||
|
|
||||||
|
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||||
|
html, body { height: 100%; overflow: hidden; }
|
||||||
|
|
||||||
|
/* ===== THEME VARIABLES ===== */
|
||||||
|
:root {
|
||||||
|
--bg-primary: #f5f5f7;
|
||||||
|
--bg-secondary: #ffffff;
|
||||||
|
--bg-tertiary: #e5e5e7;
|
||||||
|
--border: #d1d1d6;
|
||||||
|
--text-primary: #1d1d1f;
|
||||||
|
--text-secondary: #86868b;
|
||||||
|
--text-tertiary: #aeaeb2;
|
||||||
|
--accent: #0071e3;
|
||||||
|
--accent-hover: #0077ed;
|
||||||
|
--success: #34c759;
|
||||||
|
--warning: #ff9f0a;
|
||||||
|
--error: #ff3b30;
|
||||||
|
--selected-bg: #e8f4fd;
|
||||||
|
--selected-border: #0071e3;
|
||||||
|
}
|
||||||
|
|
||||||
|
@media (prefers-color-scheme: dark) {
|
||||||
|
:root {
|
||||||
|
--bg-primary: #1d1d1f;
|
||||||
|
--bg-secondary: #2d2d2f;
|
||||||
|
--bg-tertiary: #3d3d3f;
|
||||||
|
--border: #424245;
|
||||||
|
--text-primary: #f5f5f7;
|
||||||
|
--text-secondary: #86868b;
|
||||||
|
--text-tertiary: #636366;
|
||||||
|
--accent: #0a84ff;
|
||||||
|
--accent-hover: #409cff;
|
||||||
|
--selected-bg: rgba(10, 132, 255, 0.15);
|
||||||
|
--selected-border: #0a84ff;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
font-family: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
|
||||||
|
background: var(--bg-primary);
|
||||||
|
color: var(--text-primary);
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ===== FRAME STRUCTURE ===== */
|
||||||
|
.header {
|
||||||
|
background: var(--bg-secondary);
|
||||||
|
padding: 0.5rem 1.5rem;
|
||||||
|
display: flex;
|
||||||
|
justify-content: space-between;
|
||||||
|
align-items: center;
|
||||||
|
border-bottom: 1px solid var(--border);
|
||||||
|
flex-shrink: 0;
|
||||||
|
}
|
||||||
|
.header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
|
||||||
|
.header .status { font-size: 0.7rem; color: var(--success); display: flex; align-items: center; gap: 0.4rem; }
|
||||||
|
.header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
|
||||||
|
|
||||||
|
.main { flex: 1; overflow-y: auto; }
|
||||||
|
#claude-content { padding: 2rem; min-height: 100%; }
|
||||||
|
|
||||||
|
.indicator-bar {
|
||||||
|
background: var(--bg-secondary);
|
||||||
|
border-top: 1px solid var(--border);
|
||||||
|
padding: 0.5rem 1.5rem;
|
||||||
|
flex-shrink: 0;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
.indicator-bar span {
|
||||||
|
font-size: 0.75rem;
|
||||||
|
color: var(--text-secondary);
|
||||||
|
}
|
||||||
|
.indicator-bar .selected-text {
|
||||||
|
color: var(--accent);
|
||||||
|
font-weight: 500;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ===== TYPOGRAPHY ===== */
|
||||||
|
h2 { font-size: 1.5rem; font-weight: 600; margin-bottom: 0.5rem; }
|
||||||
|
h3 { font-size: 1.1rem; font-weight: 600; margin-bottom: 0.25rem; }
|
||||||
|
.subtitle { color: var(--text-secondary); margin-bottom: 1.5rem; }
|
||||||
|
.section { margin-bottom: 2rem; }
|
||||||
|
.label { font-size: 0.7rem; color: var(--text-secondary); text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 0.5rem; }
|
||||||
|
|
||||||
|
/* ===== OPTIONS (for A/B/C choices) ===== */
|
||||||
|
.options { display: flex; flex-direction: column; gap: 0.75rem; }
|
||||||
|
.option {
|
||||||
|
background: var(--bg-secondary);
|
||||||
|
border: 2px solid var(--border);
|
||||||
|
border-radius: 12px;
|
||||||
|
padding: 1rem 1.25rem;
|
||||||
|
cursor: pointer;
|
||||||
|
transition: all 0.15s ease;
|
||||||
|
display: flex;
|
||||||
|
align-items: flex-start;
|
||||||
|
gap: 1rem;
|
||||||
|
}
|
||||||
|
.option:hover { border-color: var(--accent); }
|
||||||
|
.option.selected { background: var(--selected-bg); border-color: var(--selected-border); }
|
||||||
|
.option .letter {
|
||||||
|
background: var(--bg-tertiary);
|
||||||
|
color: var(--text-secondary);
|
||||||
|
width: 1.75rem; height: 1.75rem;
|
||||||
|
border-radius: 6px;
|
||||||
|
display: flex; align-items: center; justify-content: center;
|
||||||
|
font-weight: 600; font-size: 0.85rem; flex-shrink: 0;
|
||||||
|
}
|
||||||
|
.option.selected .letter { background: var(--accent); color: white; }
|
||||||
|
.option .content { flex: 1; }
|
||||||
|
.option .content h3 { font-size: 0.95rem; margin-bottom: 0.15rem; }
|
||||||
|
.option .content p { color: var(--text-secondary); font-size: 0.85rem; margin: 0; }
|
||||||
|
|
||||||
|
/* ===== CARDS (for showing designs/mockups) ===== */
|
||||||
|
.cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; }
|
||||||
|
.card {
|
||||||
|
background: var(--bg-secondary);
|
||||||
|
border: 1px solid var(--border);
|
||||||
|
border-radius: 12px;
|
||||||
|
overflow: hidden;
|
||||||
|
cursor: pointer;
|
||||||
|
transition: all 0.15s ease;
|
||||||
|
}
|
||||||
|
.card:hover { border-color: var(--accent); transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
|
||||||
|
.card.selected { border-color: var(--selected-border); border-width: 2px; }
|
||||||
|
.card-image { background: var(--bg-tertiary); aspect-ratio: 16/10; display: flex; align-items: center; justify-content: center; }
|
||||||
|
.card-body { padding: 1rem; }
|
||||||
|
.card-body h3 { margin-bottom: 0.25rem; }
|
||||||
|
.card-body p { color: var(--text-secondary); font-size: 0.85rem; }
|
||||||
|
|
||||||
|
/* ===== MOCKUP CONTAINER ===== */
|
||||||
|
.mockup {
|
||||||
|
background: var(--bg-secondary);
|
||||||
|
border: 1px solid var(--border);
|
||||||
|
border-radius: 12px;
|
||||||
|
overflow: hidden;
|
||||||
|
margin-bottom: 1.5rem;
|
||||||
|
}
|
||||||
|
.mockup-header {
|
||||||
|
background: var(--bg-tertiary);
|
||||||
|
padding: 0.5rem 1rem;
|
||||||
|
font-size: 0.75rem;
|
||||||
|
color: var(--text-secondary);
|
||||||
|
border-bottom: 1px solid var(--border);
|
||||||
|
}
|
||||||
|
.mockup-body { padding: 1.5rem; }
|
||||||
|
|
||||||
|
/* ===== SPLIT VIEW (side-by-side comparison) ===== */
|
||||||
|
.split { display: grid; grid-template-columns: 1fr 1fr; gap: 1.5rem; }
|
||||||
|
@media (max-width: 700px) { .split { grid-template-columns: 1fr; } }
|
||||||
|
|
||||||
|
/* ===== PROS/CONS ===== */
|
||||||
|
.pros-cons { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; }
|
||||||
|
.pros, .cons { background: var(--bg-secondary); border-radius: 8px; padding: 1rem; }
|
||||||
|
.pros h4 { color: var(--success); font-size: 0.85rem; margin-bottom: 0.5rem; }
|
||||||
|
.cons h4 { color: var(--error); font-size: 0.85rem; margin-bottom: 0.5rem; }
|
||||||
|
.pros ul, .cons ul { margin-left: 1.25rem; font-size: 0.85rem; color: var(--text-secondary); }
|
||||||
|
.pros li, .cons li { margin-bottom: 0.25rem; }
|
||||||
|
|
||||||
|
/* ===== PLACEHOLDER (for mockup areas) ===== */
|
||||||
|
.placeholder {
|
||||||
|
background: var(--bg-tertiary);
|
||||||
|
border: 2px dashed var(--border);
|
||||||
|
border-radius: 8px;
|
||||||
|
padding: 2rem;
|
||||||
|
text-align: center;
|
||||||
|
color: var(--text-tertiary);
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ===== INLINE MOCKUP ELEMENTS ===== */
|
||||||
|
.mock-nav { background: var(--accent); color: white; padding: 0.75rem 1rem; display: flex; gap: 1.5rem; font-size: 0.9rem; }
|
||||||
|
.mock-sidebar { background: var(--bg-tertiary); padding: 1rem; min-width: 180px; }
|
||||||
|
.mock-content { padding: 1.5rem; flex: 1; }
|
||||||
|
.mock-button { background: var(--accent); color: white; border: none; padding: 0.5rem 1rem; border-radius: 6px; font-size: 0.85rem; }
|
||||||
|
.mock-input { background: var(--bg-primary); border: 1px solid var(--border); border-radius: 6px; padding: 0.5rem; width: 100%; }
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<div class="header">
|
||||||
|
<h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
|
||||||
|
<div class="status">Connected</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="main">
|
||||||
|
<div id="claude-content">
|
||||||
|
<!-- CONTENT -->
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div class="indicator-bar">
|
||||||
|
<span id="indicator-text">Click an option above, then return to the terminal</span>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
@ -0,0 +1,88 @@
|
||||||
|
(function() {
|
||||||
|
const WS_URL = 'ws://' + window.location.host;
|
||||||
|
let ws = null;
|
||||||
|
let eventQueue = [];
|
||||||
|
|
||||||
|
function connect() {
|
||||||
|
ws = new WebSocket(WS_URL);
|
||||||
|
|
||||||
|
ws.onopen = () => {
|
||||||
|
eventQueue.forEach(e => ws.send(JSON.stringify(e)));
|
||||||
|
eventQueue = [];
|
||||||
|
};
|
||||||
|
|
||||||
|
ws.onmessage = (msg) => {
|
||||||
|
const data = JSON.parse(msg.data);
|
||||||
|
if (data.type === 'reload') {
|
||||||
|
window.location.reload();
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
ws.onclose = () => {
|
||||||
|
setTimeout(connect, 1000);
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function sendEvent(event) {
|
||||||
|
event.timestamp = Date.now();
|
||||||
|
if (ws && ws.readyState === WebSocket.OPEN) {
|
||||||
|
ws.send(JSON.stringify(event));
|
||||||
|
} else {
|
||||||
|
eventQueue.push(event);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Capture clicks on choice elements
|
||||||
|
document.addEventListener('click', (e) => {
|
||||||
|
const target = e.target.closest('[data-choice]');
|
||||||
|
if (!target) return;
|
||||||
|
|
||||||
|
sendEvent({
|
||||||
|
type: 'click',
|
||||||
|
text: target.textContent.trim(),
|
||||||
|
choice: target.dataset.choice,
|
||||||
|
id: target.id || null
|
||||||
|
});
|
||||||
|
|
||||||
|
// Update indicator bar (defer so toggleSelect runs first)
|
||||||
|
setTimeout(() => {
|
||||||
|
const indicator = document.getElementById('indicator-text');
|
||||||
|
if (!indicator) return;
|
||||||
|
const container = target.closest('.options') || target.closest('.cards');
|
||||||
|
const selected = container ? container.querySelectorAll('.selected') : [];
|
||||||
|
if (selected.length === 0) {
|
||||||
|
indicator.textContent = 'Click an option above, then return to the terminal';
|
||||||
|
} else if (selected.length === 1) {
|
||||||
|
const label = selected[0].querySelector('h3, .content h3, .card-body h3')?.textContent?.trim() || selected[0].dataset.choice;
|
||||||
|
indicator.innerHTML = '<span class="selected-text">' + label + ' selected</span> — return to terminal to continue';
|
||||||
|
} else {
|
||||||
|
indicator.innerHTML = '<span class="selected-text">' + selected.length + ' selected</span> — return to terminal to continue';
|
||||||
|
}
|
||||||
|
}, 0);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Frame UI: selection tracking
|
||||||
|
window.selectedChoice = null;
|
||||||
|
|
||||||
|
window.toggleSelect = function(el) {
|
||||||
|
const container = el.closest('.options') || el.closest('.cards');
|
||||||
|
const multi = container && container.dataset.multiselect !== undefined;
|
||||||
|
if (container && !multi) {
|
||||||
|
container.querySelectorAll('.option, .card').forEach(o => o.classList.remove('selected'));
|
||||||
|
}
|
||||||
|
if (multi) {
|
||||||
|
el.classList.toggle('selected');
|
||||||
|
} else {
|
||||||
|
el.classList.add('selected');
|
||||||
|
}
|
||||||
|
window.selectedChoice = el.dataset.choice;
|
||||||
|
};
|
||||||
|
|
||||||
|
// Expose API for explicit use
|
||||||
|
window.brainstorm = {
|
||||||
|
send: sendEvent,
|
||||||
|
choice: (value, metadata = {}) => sendEvent({ type: 'choice', value, ...metadata })
|
||||||
|
};
|
||||||
|
|
||||||
|
connect();
|
||||||
|
})();
|
||||||
|
|
@ -0,0 +1,338 @@
|
||||||
|
const crypto = require('crypto');
|
||||||
|
const http = require('http');
|
||||||
|
const fs = require('fs');
|
||||||
|
const path = require('path');
|
||||||
|
|
||||||
|
// ========== WebSocket Protocol (RFC 6455) ==========
|
||||||
|
|
||||||
|
const OPCODES = { TEXT: 0x01, CLOSE: 0x08, PING: 0x09, PONG: 0x0A };
|
||||||
|
const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
|
||||||
|
|
||||||
|
function computeAcceptKey(clientKey) {
|
||||||
|
return crypto.createHash('sha1').update(clientKey + WS_MAGIC).digest('base64');
|
||||||
|
}
|
||||||
|
|
||||||
|
function encodeFrame(opcode, payload) {
|
||||||
|
const fin = 0x80;
|
||||||
|
const len = payload.length;
|
||||||
|
let header;
|
||||||
|
|
||||||
|
if (len < 126) {
|
||||||
|
header = Buffer.alloc(2);
|
||||||
|
header[0] = fin | opcode;
|
||||||
|
header[1] = len;
|
||||||
|
} else if (len < 65536) {
|
||||||
|
header = Buffer.alloc(4);
|
||||||
|
header[0] = fin | opcode;
|
||||||
|
header[1] = 126;
|
||||||
|
header.writeUInt16BE(len, 2);
|
||||||
|
} else {
|
||||||
|
header = Buffer.alloc(10);
|
||||||
|
header[0] = fin | opcode;
|
||||||
|
header[1] = 127;
|
||||||
|
header.writeBigUInt64BE(BigInt(len), 2);
|
||||||
|
}
|
||||||
|
|
||||||
|
return Buffer.concat([header, payload]);
|
||||||
|
}
|
||||||
|
|
||||||
|
function decodeFrame(buffer) {
|
||||||
|
if (buffer.length < 2) return null;
|
||||||
|
|
||||||
|
const secondByte = buffer[1];
|
||||||
|
const opcode = buffer[0] & 0x0F;
|
||||||
|
const masked = (secondByte & 0x80) !== 0;
|
||||||
|
let payloadLen = secondByte & 0x7F;
|
||||||
|
let offset = 2;
|
||||||
|
|
||||||
|
if (!masked) throw new Error('Client frames must be masked');
|
||||||
|
|
||||||
|
if (payloadLen === 126) {
|
||||||
|
if (buffer.length < 4) return null;
|
||||||
|
payloadLen = buffer.readUInt16BE(2);
|
||||||
|
offset = 4;
|
||||||
|
} else if (payloadLen === 127) {
|
||||||
|
if (buffer.length < 10) return null;
|
||||||
|
payloadLen = Number(buffer.readBigUInt64BE(2));
|
||||||
|
offset = 10;
|
||||||
|
}
|
||||||
|
|
||||||
|
const maskOffset = offset;
|
||||||
|
const dataOffset = offset + 4;
|
||||||
|
const totalLen = dataOffset + payloadLen;
|
||||||
|
if (buffer.length < totalLen) return null;
|
||||||
|
|
||||||
|
const mask = buffer.slice(maskOffset, dataOffset);
|
||||||
|
const data = Buffer.alloc(payloadLen);
|
||||||
|
for (let i = 0; i < payloadLen; i++) {
|
||||||
|
data[i] = buffer[dataOffset + i] ^ mask[i % 4];
|
||||||
|
}
|
||||||
|
|
||||||
|
return { opcode, payload: data, bytesConsumed: totalLen };
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Configuration ==========
|
||||||
|
|
||||||
|
const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
|
||||||
|
const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
|
||||||
|
const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
|
||||||
|
const SCREEN_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
|
||||||
|
const OWNER_PID = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
|
||||||
|
|
||||||
|
const MIME_TYPES = {
|
||||||
|
'.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
|
||||||
|
'.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
|
||||||
|
'.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml'
|
||||||
|
};
|
||||||
|
|
||||||
|
// ========== Templates and Constants ==========
|
||||||
|
|
||||||
|
const WAITING_PAGE = `<!DOCTYPE html>
|
||||||
|
<html>
|
||||||
|
<head><meta charset="utf-8"><title>Brainstorm Companion</title>
|
||||||
|
<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
|
||||||
|
h1 { color: #333; } p { color: #666; }</style>
|
||||||
|
</head>
|
||||||
|
<body><h1>Brainstorm Companion</h1>
|
||||||
|
<p>Waiting for Claude to push a screen...</p></body></html>`;
|
||||||
|
|
||||||
|
const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
|
||||||
|
const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
|
||||||
|
const helperInjection = '<script>\n' + helperScript + '\n</script>';
|
||||||
|
|
||||||
|
// ========== Helper Functions ==========
|
||||||
|
|
||||||
|
function isFullDocument(html) {
|
||||||
|
const trimmed = html.trimStart().toLowerCase();
|
||||||
|
return trimmed.startsWith('<!doctype') || trimmed.startsWith('<html');
|
||||||
|
}
|
||||||
|
|
||||||
|
function wrapInFrame(content) {
|
||||||
|
return frameTemplate.replace('<!-- CONTENT -->', content);
|
||||||
|
}
|
||||||
|
|
||||||
|
function getNewestScreen() {
|
||||||
|
const files = fs.readdirSync(SCREEN_DIR)
|
||||||
|
.filter(f => f.endsWith('.html'))
|
||||||
|
.map(f => {
|
||||||
|
const fp = path.join(SCREEN_DIR, f);
|
||||||
|
return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
|
||||||
|
})
|
||||||
|
.sort((a, b) => b.mtime - a.mtime);
|
||||||
|
return files.length > 0 ? files[0].path : null;
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== HTTP Request Handler ==========
|
||||||
|
|
||||||
|
function handleRequest(req, res) {
|
||||||
|
touchActivity();
|
||||||
|
if (req.method === 'GET' && req.url === '/') {
|
||||||
|
const screenFile = getNewestScreen();
|
||||||
|
let html = screenFile
|
||||||
|
? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
|
||||||
|
: WAITING_PAGE;
|
||||||
|
|
||||||
|
if (html.includes('</body>')) {
|
||||||
|
html = html.replace('</body>', helperInjection + '\n</body>');
|
||||||
|
} else {
|
||||||
|
html += helperInjection;
|
||||||
|
}
|
||||||
|
|
||||||
|
res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
|
||||||
|
res.end(html);
|
||||||
|
} else if (req.method === 'GET' && req.url.startsWith('/files/')) {
|
||||||
|
const fileName = req.url.slice(7);
|
||||||
|
const filePath = path.join(SCREEN_DIR, path.basename(fileName));
|
||||||
|
if (!fs.existsSync(filePath)) {
|
||||||
|
res.writeHead(404);
|
||||||
|
res.end('Not found');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
const ext = path.extname(filePath).toLowerCase();
|
||||||
|
const contentType = MIME_TYPES[ext] || 'application/octet-stream';
|
||||||
|
res.writeHead(200, { 'Content-Type': contentType });
|
||||||
|
res.end(fs.readFileSync(filePath));
|
||||||
|
} else {
|
||||||
|
res.writeHead(404);
|
||||||
|
res.end('Not found');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== WebSocket Connection Handling ==========
|
||||||
|
|
||||||
|
const clients = new Set();
|
||||||
|
|
||||||
|
function handleUpgrade(req, socket) {
|
||||||
|
const key = req.headers['sec-websocket-key'];
|
||||||
|
if (!key) { socket.destroy(); return; }
|
||||||
|
|
||||||
|
const accept = computeAcceptKey(key);
|
||||||
|
socket.write(
|
||||||
|
'HTTP/1.1 101 Switching Protocols\r\n' +
|
||||||
|
'Upgrade: websocket\r\n' +
|
||||||
|
'Connection: Upgrade\r\n' +
|
||||||
|
'Sec-WebSocket-Accept: ' + accept + '\r\n\r\n'
|
||||||
|
);
|
||||||
|
|
||||||
|
let buffer = Buffer.alloc(0);
|
||||||
|
clients.add(socket);
|
||||||
|
|
||||||
|
socket.on('data', (chunk) => {
|
||||||
|
buffer = Buffer.concat([buffer, chunk]);
|
||||||
|
while (buffer.length > 0) {
|
||||||
|
let result;
|
||||||
|
try {
|
||||||
|
result = decodeFrame(buffer);
|
||||||
|
} catch (e) {
|
||||||
|
socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
|
||||||
|
clients.delete(socket);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
if (!result) break;
|
||||||
|
buffer = buffer.slice(result.bytesConsumed);
|
||||||
|
|
||||||
|
switch (result.opcode) {
|
||||||
|
case OPCODES.TEXT:
|
||||||
|
handleMessage(result.payload.toString());
|
||||||
|
break;
|
||||||
|
case OPCODES.CLOSE:
|
||||||
|
socket.end(encodeFrame(OPCODES.CLOSE, Buffer.alloc(0)));
|
||||||
|
clients.delete(socket);
|
||||||
|
return;
|
||||||
|
case OPCODES.PING:
|
||||||
|
socket.write(encodeFrame(OPCODES.PONG, result.payload));
|
||||||
|
break;
|
||||||
|
case OPCODES.PONG:
|
||||||
|
break;
|
||||||
|
default: {
|
||||||
|
const closeBuf = Buffer.alloc(2);
|
||||||
|
closeBuf.writeUInt16BE(1003);
|
||||||
|
socket.end(encodeFrame(OPCODES.CLOSE, closeBuf));
|
||||||
|
clients.delete(socket);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
socket.on('close', () => clients.delete(socket));
|
||||||
|
socket.on('error', () => clients.delete(socket));
|
||||||
|
}
|
||||||
|
|
||||||
|
function handleMessage(text) {
|
||||||
|
let event;
|
||||||
|
try {
|
||||||
|
event = JSON.parse(text);
|
||||||
|
} catch (e) {
|
||||||
|
console.error('Failed to parse WebSocket message:', e.message);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
touchActivity();
|
||||||
|
console.log(JSON.stringify({ source: 'user-event', ...event }));
|
||||||
|
if (event.choice) {
|
||||||
|
const eventsFile = path.join(SCREEN_DIR, '.events');
|
||||||
|
fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function broadcast(msg) {
|
||||||
|
const frame = encodeFrame(OPCODES.TEXT, Buffer.from(JSON.stringify(msg)));
|
||||||
|
for (const socket of clients) {
|
||||||
|
try { socket.write(frame); } catch (e) { clients.delete(socket); }
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== Activity Tracking ==========
|
||||||
|
|
||||||
|
const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
|
||||||
|
let lastActivity = Date.now();
|
||||||
|
|
||||||
|
function touchActivity() {
|
||||||
|
lastActivity = Date.now();
|
||||||
|
}
|
||||||
|
|
||||||
|
// ========== File Watching ==========
|
||||||
|
|
||||||
|
const debounceTimers = new Map();
|
||||||
|
|
||||||
|
// ========== Server Startup ==========
|
||||||
|
|
||||||
|
function startServer() {
|
||||||
|
if (!fs.existsSync(SCREEN_DIR)) fs.mkdirSync(SCREEN_DIR, { recursive: true });
|
||||||
|
|
||||||
|
// Track known files to distinguish new screens from updates.
|
||||||
|
// macOS fs.watch reports 'rename' for both new files and overwrites,
|
||||||
|
// so we can't rely on eventType alone.
|
||||||
|
const knownFiles = new Set(
|
||||||
|
fs.readdirSync(SCREEN_DIR).filter(f => f.endsWith('.html'))
|
||||||
|
);
|
||||||
|
|
||||||
|
const server = http.createServer(handleRequest);
|
||||||
|
server.on('upgrade', handleUpgrade);
|
||||||
|
|
||||||
|
const watcher = fs.watch(SCREEN_DIR, (eventType, filename) => {
|
||||||
|
if (!filename || !filename.endsWith('.html')) return;
|
||||||
|
|
||||||
|
if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
|
||||||
|
debounceTimers.set(filename, setTimeout(() => {
|
||||||
|
debounceTimers.delete(filename);
|
||||||
|
const filePath = path.join(SCREEN_DIR, filename);
|
||||||
|
|
||||||
|
if (!fs.existsSync(filePath)) return; // file was deleted
|
||||||
|
touchActivity();
|
||||||
|
|
||||||
|
if (!knownFiles.has(filename)) {
|
||||||
|
knownFiles.add(filename);
|
||||||
|
const eventsFile = path.join(SCREEN_DIR, '.events');
|
||||||
|
if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
|
||||||
|
console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
|
||||||
|
} else {
|
||||||
|
console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
|
||||||
|
}
|
||||||
|
|
||||||
|
broadcast({ type: 'reload' });
|
||||||
|
}, 100));
|
||||||
|
});
|
||||||
|
watcher.on('error', (err) => console.error('fs.watch error:', err.message));
|
||||||
|
|
||||||
|
function shutdown(reason) {
|
||||||
|
console.log(JSON.stringify({ type: 'server-stopped', reason }));
|
||||||
|
const infoFile = path.join(SCREEN_DIR, '.server-info');
|
||||||
|
if (fs.existsSync(infoFile)) fs.unlinkSync(infoFile);
|
||||||
|
fs.writeFileSync(
|
||||||
|
path.join(SCREEN_DIR, '.server-stopped'),
|
||||||
|
JSON.stringify({ reason, timestamp: Date.now() }) + '\n'
|
||||||
|
);
|
||||||
|
watcher.close();
|
||||||
|
clearInterval(lifecycleCheck);
|
||||||
|
server.close(() => process.exit(0));
|
||||||
|
}
|
||||||
|
|
||||||
|
function ownerAlive() {
|
||||||
|
if (!OWNER_PID) return true;
|
||||||
|
try { process.kill(OWNER_PID, 0); return true; } catch (e) { return false; }
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check every 60s: exit if owner process died or idle for 30 minutes
|
||||||
|
const lifecycleCheck = setInterval(() => {
|
||||||
|
if (!ownerAlive()) shutdown('owner process exited');
|
||||||
|
else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
|
||||||
|
}, 60 * 1000);
|
||||||
|
lifecycleCheck.unref();
|
||||||
|
|
||||||
|
server.listen(PORT, HOST, () => {
|
||||||
|
const info = JSON.stringify({
|
||||||
|
type: 'server-started', port: Number(PORT), host: HOST,
|
||||||
|
url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
|
||||||
|
screen_dir: SCREEN_DIR
|
||||||
|
});
|
||||||
|
console.log(info);
|
||||||
|
fs.writeFileSync(path.join(SCREEN_DIR, '.server-info'), info + '\n');
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
if (require.main === module) {
|
||||||
|
startServer();
|
||||||
|
}
|
||||||
|
|
||||||
|
module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES };
|
||||||
|
|
@ -0,0 +1,137 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# Start the brainstorm server and output connection info
|
||||||
|
# Usage: start-server.sh [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
|
||||||
|
#
|
||||||
|
# Starts server on a random high port, outputs JSON with URL.
|
||||||
|
# Each session gets its own directory to avoid conflicts.
|
||||||
|
#
|
||||||
|
# Options:
|
||||||
|
# --project-dir <path> Store session files under <path>/.superpowers/brainstorm/
|
||||||
|
# instead of /tmp. Files persist after server stops.
|
||||||
|
# --host <bind-host> Host/interface to bind (default: 127.0.0.1).
|
||||||
|
# Use 0.0.0.0 in remote/containerized environments.
|
||||||
|
# --url-host <host> Hostname shown in returned URL JSON.
|
||||||
|
# --foreground Run server in the current terminal (no backgrounding).
|
||||||
|
# --background Force background mode (overrides Codex auto-foreground).
|
||||||
|
|
||||||
|
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||||
|
|
||||||
|
# Parse arguments
|
||||||
|
PROJECT_DIR=""
|
||||||
|
FOREGROUND="false"
|
||||||
|
FORCE_BACKGROUND="false"
|
||||||
|
BIND_HOST="127.0.0.1"
|
||||||
|
URL_HOST=""
|
||||||
|
while [[ $# -gt 0 ]]; do
|
||||||
|
case "$1" in
|
||||||
|
--project-dir)
|
||||||
|
PROJECT_DIR="$2"
|
||||||
|
shift 2
|
||||||
|
;;
|
||||||
|
--host)
|
||||||
|
BIND_HOST="$2"
|
||||||
|
shift 2
|
||||||
|
;;
|
||||||
|
--url-host)
|
||||||
|
URL_HOST="$2"
|
||||||
|
shift 2
|
||||||
|
;;
|
||||||
|
--foreground|--no-daemon)
|
||||||
|
FOREGROUND="true"
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
--background|--daemon)
|
||||||
|
FORCE_BACKGROUND="true"
|
||||||
|
shift
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "{\"error\": \"Unknown argument: $1\"}"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
done
|
||||||
|
|
||||||
|
if [[ -z "$URL_HOST" ]]; then
|
||||||
|
if [[ "$BIND_HOST" == "127.0.0.1" || "$BIND_HOST" == "localhost" ]]; then
|
||||||
|
URL_HOST="localhost"
|
||||||
|
else
|
||||||
|
URL_HOST="$BIND_HOST"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Some environments reap detached/background processes. Auto-foreground when detected.
|
||||||
|
if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
|
||||||
|
FOREGROUND="true"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Generate unique session directory
|
||||||
|
SESSION_ID="$$-$(date +%s)"
|
||||||
|
|
||||||
|
if [[ -n "$PROJECT_DIR" ]]; then
|
||||||
|
SCREEN_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
|
||||||
|
else
|
||||||
|
SCREEN_DIR="/tmp/brainstorm-${SESSION_ID}"
|
||||||
|
fi
|
||||||
|
|
||||||
|
PID_FILE="${SCREEN_DIR}/.server.pid"
|
||||||
|
LOG_FILE="${SCREEN_DIR}/.server.log"
|
||||||
|
|
||||||
|
# Create fresh session directory
|
||||||
|
mkdir -p "$SCREEN_DIR"
|
||||||
|
|
||||||
|
# Kill any existing server
|
||||||
|
if [[ -f "$PID_FILE" ]]; then
|
||||||
|
old_pid=$(cat "$PID_FILE")
|
||||||
|
kill "$old_pid" 2>/dev/null
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
fi
|
||||||
|
|
||||||
|
cd "$SCRIPT_DIR"
|
||||||
|
|
||||||
|
# Resolve the harness PID (grandparent of this script).
|
||||||
|
# $PPID is the ephemeral shell the harness spawned to run us — it dies
|
||||||
|
# when this script exits. The harness itself is $PPID's parent.
|
||||||
|
OWNER_PID="$(ps -o ppid= -p "$PPID" 2>/dev/null | tr -d ' ')"
|
||||||
|
if [[ -z "$OWNER_PID" || "$OWNER_PID" == "1" ]]; then
|
||||||
|
OWNER_PID="$PPID"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Foreground mode for environments that reap detached/background processes.
|
||||||
|
if [[ "$FOREGROUND" == "true" ]]; then
|
||||||
|
echo "$$" > "$PID_FILE"
|
||||||
|
env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.js
|
||||||
|
exit $?
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Start server, capturing output to log file
|
||||||
|
# Use nohup to survive shell exit; disown to remove from job table
|
||||||
|
nohup env BRAINSTORM_DIR="$SCREEN_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.js > "$LOG_FILE" 2>&1 &
|
||||||
|
SERVER_PID=$!
|
||||||
|
disown "$SERVER_PID" 2>/dev/null
|
||||||
|
echo "$SERVER_PID" > "$PID_FILE"
|
||||||
|
|
||||||
|
# Wait for server-started message (check log file)
|
||||||
|
for i in {1..50}; do
|
||||||
|
if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
|
||||||
|
# Verify server is still alive after a short window (catches process reapers)
|
||||||
|
alive="true"
|
||||||
|
for _ in {1..20}; do
|
||||||
|
if ! kill -0 "$SERVER_PID" 2>/dev/null; then
|
||||||
|
alive="false"
|
||||||
|
break
|
||||||
|
fi
|
||||||
|
sleep 0.1
|
||||||
|
done
|
||||||
|
if [[ "$alive" != "true" ]]; then
|
||||||
|
echo "{\"error\": \"Server started but was killed. Retry in a persistent terminal with: $SCRIPT_DIR/start-server.sh${PROJECT_DIR:+ --project-dir $PROJECT_DIR} --host $BIND_HOST --url-host $URL_HOST --foreground\"}"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
grep "server-started" "$LOG_FILE" | head -1
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
sleep 0.1
|
||||||
|
done
|
||||||
|
|
||||||
|
# Timeout - server didn't start
|
||||||
|
echo '{"error": "Server failed to start within 5 seconds"}'
|
||||||
|
exit 1
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# Stop the brainstorm server and clean up
|
||||||
|
# Usage: stop-server.sh <screen_dir>
|
||||||
|
#
|
||||||
|
# Kills the server process. Only deletes session directory if it's
|
||||||
|
# under /tmp (ephemeral). Persistent directories (.superpowers/) are
|
||||||
|
# kept so mockups can be reviewed later.
|
||||||
|
|
||||||
|
SCREEN_DIR="$1"
|
||||||
|
|
||||||
|
if [[ -z "$SCREEN_DIR" ]]; then
|
||||||
|
echo '{"error": "Usage: stop-server.sh <screen_dir>"}'
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
PID_FILE="${SCREEN_DIR}/.server.pid"
|
||||||
|
|
||||||
|
if [[ -f "$PID_FILE" ]]; then
|
||||||
|
pid=$(cat "$PID_FILE")
|
||||||
|
kill "$pid" 2>/dev/null
|
||||||
|
rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
|
||||||
|
|
||||||
|
# Only delete ephemeral /tmp directories
|
||||||
|
if [[ "$SCREEN_DIR" == /tmp/* ]]; then
|
||||||
|
rm -rf "$SCREEN_DIR"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo '{"status": "stopped"}'
|
||||||
|
else
|
||||||
|
echo '{"status": "not_running"}'
|
||||||
|
fi
|
||||||
|
|
@ -0,0 +1,50 @@
|
||||||
|
# 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/superpowers/specs/
|
||||||
|
|
||||||
|
```
|
||||||
|
Task tool (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 |
|
||||||
|
| Coverage | Missing error handling, edge cases, integration points |
|
||||||
|
| Consistency | Internal contradictions, conflicting requirements |
|
||||||
|
| Clarity | Ambiguous requirements |
|
||||||
|
| YAGNI | Unrequested features, over-engineering |
|
||||||
|
| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
|
||||||
|
| Architecture | Units with clear boundaries, well-defined interfaces, independently understandable and testable |
|
||||||
|
|
||||||
|
## CRITICAL
|
||||||
|
|
||||||
|
Look especially hard for:
|
||||||
|
- Any TODO markers or placeholder text
|
||||||
|
- Sections saying "to be defined later" or "will spec when X is done"
|
||||||
|
- Sections noticeably less detailed than others
|
||||||
|
- Units that lack clear boundaries or interfaces — can you understand what each unit does without reading its internals?
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
## Spec Review
|
||||||
|
|
||||||
|
**Status:** ✅ Approved | ❌ Issues Found
|
||||||
|
|
||||||
|
**Issues (if any):**
|
||||||
|
- [Section X]: [specific issue] - [why it matters]
|
||||||
|
|
||||||
|
**Recommendations (advisory):**
|
||||||
|
- [suggestions that don't block approval]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Reviewer returns:** Status, Issues (if any), Recommendations
|
||||||
|
|
@ -0,0 +1,277 @@
|
||||||
|
# Visual Companion Guide
|
||||||
|
|
||||||
|
Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
|
||||||
|
Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
|
||||||
|
|
||||||
|
**Use the browser** when the content itself is visual:
|
||||||
|
|
||||||
|
- **UI mockups** — wireframes, layouts, navigation structures, component designs
|
||||||
|
- **Architecture diagrams** — system components, data flow, relationship maps
|
||||||
|
- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
|
||||||
|
- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
|
||||||
|
- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
|
||||||
|
|
||||||
|
**Use the terminal** when the content is text or tabular:
|
||||||
|
|
||||||
|
- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
|
||||||
|
- **Conceptual A/B/C choices** — picking between approaches described in words
|
||||||
|
- **Tradeoff lists** — pros/cons, comparison tables
|
||||||
|
- **Technical decisions** — API design, data modeling, architectural approach selection
|
||||||
|
- **Clarifying questions** — anything where the answer is words, not a visual preference
|
||||||
|
|
||||||
|
A 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.
|
||||||
|
|
||||||
|
## How It Works
|
||||||
|
|
||||||
|
The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content, the user sees it in their browser and can click to select options. Selections are recorded to a `.events` file that you read on your next turn.
|
||||||
|
|
||||||
|
**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
|
||||||
|
|
||||||
|
## Starting a Session
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start server with persistence (mockups saved to project)
|
||||||
|
scripts/start-server.sh --project-dir /path/to/project
|
||||||
|
|
||||||
|
# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
|
||||||
|
# "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000"}
|
||||||
|
```
|
||||||
|
|
||||||
|
Save `screen_dir` from the response. Tell user to open the URL.
|
||||||
|
|
||||||
|
**Finding connection info:** The server writes its startup JSON to `$SCREEN_DIR/.server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**Launching the server by platform:**
|
||||||
|
|
||||||
|
**Claude Code:**
|
||||||
|
```bash
|
||||||
|
# Default mode works — the script backgrounds the server itself
|
||||||
|
scripts/start-server.sh --project-dir /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**Codex:**
|
||||||
|
```bash
|
||||||
|
# Codex reaps background processes. The script auto-detects CODEX_CI and
|
||||||
|
# switches to foreground mode. Run it normally — no extra flags needed.
|
||||||
|
scripts/start-server.sh --project-dir /path/to/project
|
||||||
|
```
|
||||||
|
|
||||||
|
**Gemini CLI:**
|
||||||
|
```bash
|
||||||
|
# Use --foreground and set is_background: true on your shell tool call
|
||||||
|
# so the process survives across turns
|
||||||
|
scripts/start-server.sh --project-dir /path/to/project --foreground
|
||||||
|
```
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
scripts/start-server.sh \
|
||||||
|
--project-dir /path/to/project \
|
||||||
|
--host 0.0.0.0 \
|
||||||
|
--url-host localhost
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `--url-host` to control what hostname is printed in the returned URL JSON.
|
||||||
|
|
||||||
|
## The Loop
|
||||||
|
|
||||||
|
1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
|
||||||
|
- Before each write, check that `$SCREEN_DIR/.server-info` exists. If it doesn't (or `.server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
|
||||||
|
- Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
|
||||||
|
- **Never reuse filenames** — each screen gets a fresh file
|
||||||
|
- Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
|
||||||
|
- Server automatically serves the newest file
|
||||||
|
|
||||||
|
2. **Tell user what to expect and end your turn:**
|
||||||
|
- Remind them of the URL (every step, not just first)
|
||||||
|
- Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
|
||||||
|
- 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."
|
||||||
|
|
||||||
|
3. **On your next turn** — after the user responds in the terminal:
|
||||||
|
- Read `$SCREEN_DIR/.events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
|
||||||
|
- Merge with the user's terminal text to get the full picture
|
||||||
|
- The terminal message is the primary feedback; `.events` provides structured interaction data
|
||||||
|
|
||||||
|
4. **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.
|
||||||
|
|
||||||
|
5. **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:
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- filename: waiting.html (or waiting-2.html, etc.) -->
|
||||||
|
<div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
|
||||||
|
<p class="subtitle">Continuing in terminal...</p>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
6. Repeat until done.
|
||||||
|
|
||||||
|
## Writing Content Fragments
|
||||||
|
|
||||||
|
Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
|
||||||
|
|
||||||
|
**Minimal example:**
|
||||||
|
|
||||||
|
```html
|
||||||
|
<h2>Which layout works better?</h2>
|
||||||
|
<p class="subtitle">Consider readability and visual hierarchy</p>
|
||||||
|
|
||||||
|
<div class="options">
|
||||||
|
<div class="option" data-choice="a" onclick="toggleSelect(this)">
|
||||||
|
<div class="letter">A</div>
|
||||||
|
<div class="content">
|
||||||
|
<h3>Single Column</h3>
|
||||||
|
<p>Clean, focused reading experience</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
<div class="option" data-choice="b" onclick="toggleSelect(this)">
|
||||||
|
<div class="letter">B</div>
|
||||||
|
<div class="content">
|
||||||
|
<h3>Two Column</h3>
|
||||||
|
<p>Sidebar navigation with main content</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
|
||||||
|
|
||||||
|
## CSS Classes Available
|
||||||
|
|
||||||
|
The frame template provides these CSS classes for your content:
|
||||||
|
|
||||||
|
### Options (A/B/C choices)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="options">
|
||||||
|
<div class="option" data-choice="a" onclick="toggleSelect(this)">
|
||||||
|
<div class="letter">A</div>
|
||||||
|
<div class="content">
|
||||||
|
<h3>Title</h3>
|
||||||
|
<p>Description</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="options" data-multiselect>
|
||||||
|
<!-- same option markup — users can select/deselect multiple -->
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cards (visual designs)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="cards">
|
||||||
|
<div class="card" data-choice="design1" onclick="toggleSelect(this)">
|
||||||
|
<div class="card-image"><!-- mockup content --></div>
|
||||||
|
<div class="card-body">
|
||||||
|
<h3>Name</h3>
|
||||||
|
<p>Description</p>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mockup container
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="mockup">
|
||||||
|
<div class="mockup-header">Preview: Dashboard Layout</div>
|
||||||
|
<div class="mockup-body"><!-- your mockup HTML --></div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Split view (side-by-side)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="split">
|
||||||
|
<div class="mockup"><!-- left --></div>
|
||||||
|
<div class="mockup"><!-- right --></div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pros/Cons
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="pros-cons">
|
||||||
|
<div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
|
||||||
|
<div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mock elements (wireframe building blocks)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div class="mock-nav">Logo | Home | About | Contact</div>
|
||||||
|
<div style="display: flex;">
|
||||||
|
<div class="mock-sidebar">Navigation</div>
|
||||||
|
<div class="mock-content">Main content area</div>
|
||||||
|
</div>
|
||||||
|
<button class="mock-button">Action Button</button>
|
||||||
|
<input class="mock-input" placeholder="Input field">
|
||||||
|
<div class="placeholder">Placeholder area</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Typography and sections
|
||||||
|
|
||||||
|
- `h2` — page title
|
||||||
|
- `h3` — section heading
|
||||||
|
- `.subtitle` — secondary text below title
|
||||||
|
- `.section` — content block with bottom margin
|
||||||
|
- `.label` — small uppercase label text
|
||||||
|
|
||||||
|
## Browser Events Format
|
||||||
|
|
||||||
|
When the user clicks options in the browser, their interactions are recorded to `$SCREEN_DIR/.events` (one JSON object per line). The file is cleared automatically when you push a new screen.
|
||||||
|
|
||||||
|
```jsonl
|
||||||
|
{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
|
||||||
|
{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
|
||||||
|
{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
|
||||||
|
```
|
||||||
|
|
||||||
|
The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
|
||||||
|
|
||||||
|
If `.events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
|
||||||
|
|
||||||
|
## Design Tips
|
||||||
|
|
||||||
|
- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
|
||||||
|
- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
|
||||||
|
- **Iterate before advancing** — if feedback changes current screen, write a new version
|
||||||
|
- **2-4 options max** per screen
|
||||||
|
- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
|
||||||
|
- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
|
||||||
|
|
||||||
|
## File Naming
|
||||||
|
|
||||||
|
- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
|
||||||
|
- Never reuse filenames — each screen must be a new file
|
||||||
|
- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
|
||||||
|
- Server serves newest file by modification time
|
||||||
|
|
||||||
|
## Cleaning Up
|
||||||
|
|
||||||
|
```bash
|
||||||
|
scripts/stop-server.sh $SCREEN_DIR
|
||||||
|
```
|
||||||
|
|
||||||
|
If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
|
||||||
|
|
||||||
|
## Reference
|
||||||
|
|
||||||
|
- Frame template (CSS reference): `scripts/frame-template.html`
|
||||||
|
- Helper script (client-side): `scripts/helper.js`
|
||||||
|
|
@ -7,6 +7,8 @@ description: Use when facing 2+ independent tasks that can be worked on without
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
|
You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
|
||||||
|
|
||||||
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
|
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
|
||||||
|
|
||||||
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
|
**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
|
||||||
|
|
|
||||||
|
|
@ -7,12 +7,12 @@ description: Use when you have a written implementation plan to execute in a sep
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
Load plan, review critically, execute tasks in batches, report for review between batches.
|
Load plan, review critically, execute all tasks, report when complete.
|
||||||
|
|
||||||
**Core principle:** Batch execution with checkpoints for architect review.
|
|
||||||
|
|
||||||
**Announce at start:** "I'm using the executing-plans skill to implement this plan."
|
**Announce at start:** "I'm using the executing-plans skill to implement this plan."
|
||||||
|
|
||||||
|
**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
|
||||||
|
|
||||||
## The Process
|
## The Process
|
||||||
|
|
||||||
### Step 1: Load and Review Plan
|
### Step 1: Load and Review Plan
|
||||||
|
|
@ -21,8 +21,7 @@ Load plan, review critically, execute tasks in batches, report for review betwee
|
||||||
3. If concerns: Raise them with your human partner before starting
|
3. If concerns: Raise them with your human partner before starting
|
||||||
4. If no concerns: Create TodoWrite and proceed
|
4. If no concerns: Create TodoWrite and proceed
|
||||||
|
|
||||||
### Step 2: Execute Batch
|
### Step 2: Execute Tasks
|
||||||
**Default: First 3 tasks**
|
|
||||||
|
|
||||||
For each task:
|
For each task:
|
||||||
1. Mark as in_progress
|
1. Mark as in_progress
|
||||||
|
|
@ -30,19 +29,7 @@ For each task:
|
||||||
3. Run verifications as specified
|
3. Run verifications as specified
|
||||||
4. Mark as completed
|
4. Mark as completed
|
||||||
|
|
||||||
### Step 3: Report
|
### Step 3: Complete Development
|
||||||
When batch complete:
|
|
||||||
- Show what was implemented
|
|
||||||
- Show verification output
|
|
||||||
- Say: "Ready for feedback."
|
|
||||||
|
|
||||||
### Step 4: Continue
|
|
||||||
Based on feedback:
|
|
||||||
- Apply changes if needed
|
|
||||||
- Execute next batch
|
|
||||||
- Repeat until complete
|
|
||||||
|
|
||||||
### Step 5: Complete Development
|
|
||||||
|
|
||||||
After all tasks complete and verified:
|
After all tasks complete and verified:
|
||||||
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
|
- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
|
||||||
|
|
@ -52,7 +39,7 @@ After all tasks complete and verified:
|
||||||
## When to Stop and Ask for Help
|
## When to Stop and Ask for Help
|
||||||
|
|
||||||
**STOP executing immediately when:**
|
**STOP executing immediately when:**
|
||||||
- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
|
- Hit a blocker (missing dependency, test fails, instruction unclear)
|
||||||
- Plan has critical gaps preventing starting
|
- Plan has critical gaps preventing starting
|
||||||
- You don't understand an instruction
|
- You don't understand an instruction
|
||||||
- Verification fails repeatedly
|
- Verification fails repeatedly
|
||||||
|
|
@ -72,5 +59,12 @@ After all tasks complete and verified:
|
||||||
- Follow plan steps exactly
|
- Follow plan steps exactly
|
||||||
- Don't skip verifications
|
- Don't skip verifications
|
||||||
- Reference skills when plan says to
|
- Reference skills when plan says to
|
||||||
- Between batches: just report and wait
|
|
||||||
- Stop when blocked, don't guess
|
- Stop when blocked, don't guess
|
||||||
|
- Never start implementation on main/master branch without explicit user consent
|
||||||
|
|
||||||
|
## Integration
|
||||||
|
|
||||||
|
**Required workflow skills:**
|
||||||
|
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
|
||||||
|
- **superpowers:writing-plans** - Creates the plan this skill executes
|
||||||
|
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
||||||
|
|
|
||||||
|
|
@ -5,7 +5,7 @@ description: Use when completing tasks, implementing major features, or before m
|
||||||
|
|
||||||
# Requesting Code Review
|
# Requesting Code Review
|
||||||
|
|
||||||
Dispatch superpowers:code-reviewer subagent to catch issues before they cascade.
|
Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
|
||||||
|
|
||||||
**Core principle:** Review early, review often.
|
**Core principle:** Review early, review often.
|
||||||
|
|
||||||
|
|
@ -58,7 +58,7 @@ HEAD_SHA=$(git rev-parse HEAD)
|
||||||
|
|
||||||
[Dispatch superpowers:code-reviewer subagent]
|
[Dispatch superpowers:code-reviewer subagent]
|
||||||
WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
|
WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index
|
||||||
PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md
|
PLAN_OR_REQUIREMENTS: Task 2 from docs/superpowers/plans/deployment-plan.md
|
||||||
BASE_SHA: a7981ec
|
BASE_SHA: a7981ec
|
||||||
HEAD_SHA: 3df7661
|
HEAD_SHA: 3df7661
|
||||||
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
|
DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
|
||||||
|
|
|
||||||
|
|
@ -7,6 +7,8 @@ description: Use when executing implementation plans with independent tasks in t
|
||||||
|
|
||||||
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
|
Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
|
||||||
|
|
||||||
|
**Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
|
||||||
|
|
||||||
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
|
**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
|
||||||
|
|
||||||
## When to Use
|
## When to Use
|
||||||
|
|
@ -82,6 +84,39 @@ digraph process {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Model Selection
|
||||||
|
|
||||||
|
Use the least powerful model that can handle each role to conserve cost and increase speed.
|
||||||
|
|
||||||
|
**Mechanical implementation tasks** (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.
|
||||||
|
|
||||||
|
**Integration and judgment tasks** (multi-file coordination, pattern matching, debugging): use a standard model.
|
||||||
|
|
||||||
|
**Architecture, design, and review tasks**: use the most capable available model.
|
||||||
|
|
||||||
|
**Task complexity signals:**
|
||||||
|
- Touches 1-2 files with a complete spec → cheap model
|
||||||
|
- Touches multiple files with integration concerns → standard model
|
||||||
|
- Requires design judgment or broad codebase understanding → most capable model
|
||||||
|
|
||||||
|
## Handling Implementer Status
|
||||||
|
|
||||||
|
Implementer subagents report one of four statuses. Handle each appropriately:
|
||||||
|
|
||||||
|
**DONE:** Proceed to spec compliance review.
|
||||||
|
|
||||||
|
**DONE_WITH_CONCERNS:** The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.
|
||||||
|
|
||||||
|
**NEEDS_CONTEXT:** The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.
|
||||||
|
|
||||||
|
**BLOCKED:** The implementer cannot complete the task. Assess the blocker:
|
||||||
|
1. If it's a context problem, provide more context and re-dispatch with the same model
|
||||||
|
2. If the task requires more reasoning, re-dispatch with a more capable model
|
||||||
|
3. If the task is too large, break it into smaller pieces
|
||||||
|
4. If the plan itself is wrong, escalate to the human
|
||||||
|
|
||||||
|
**Never** ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.
|
||||||
|
|
||||||
## Prompt Templates
|
## Prompt Templates
|
||||||
|
|
||||||
- `./implementer-prompt.md` - Dispatch implementer subagent
|
- `./implementer-prompt.md` - Dispatch implementer subagent
|
||||||
|
|
@ -93,7 +128,7 @@ digraph process {
|
||||||
```
|
```
|
||||||
You: I'm using Subagent-Driven Development to execute this plan.
|
You: I'm using Subagent-Driven Development to execute this plan.
|
||||||
|
|
||||||
[Read plan file once: docs/plans/feature-plan.md]
|
[Read plan file once: docs/superpowers/plans/feature-plan.md]
|
||||||
[Extract all 5 tasks with full text and context]
|
[Extract all 5 tasks with full text and context]
|
||||||
[Create TodoWrite with all tasks]
|
[Create TodoWrite with all tasks]
|
||||||
|
|
||||||
|
|
@ -199,6 +234,7 @@ Done!
|
||||||
## Red Flags
|
## Red Flags
|
||||||
|
|
||||||
**Never:**
|
**Never:**
|
||||||
|
- Start implementation on main/master branch without explicit user consent
|
||||||
- Skip reviews (spec compliance OR code quality)
|
- Skip reviews (spec compliance OR code quality)
|
||||||
- Proceed with unfixed issues
|
- Proceed with unfixed issues
|
||||||
- Dispatch multiple implementation subagents in parallel (conflicts)
|
- Dispatch multiple implementation subagents in parallel (conflicts)
|
||||||
|
|
@ -229,6 +265,7 @@ Done!
|
||||||
## Integration
|
## Integration
|
||||||
|
|
||||||
**Required workflow skills:**
|
**Required workflow skills:**
|
||||||
|
- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
|
||||||
- **superpowers:writing-plans** - Creates the plan this skill executes
|
- **superpowers:writing-plans** - Creates the plan this skill executes
|
||||||
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
|
- **superpowers:requesting-code-review** - Code review template for reviewer subagents
|
||||||
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
- **superpowers:finishing-a-development-branch** - Complete development after all tasks
|
||||||
|
|
|
||||||
|
|
@ -17,4 +17,10 @@ Task tool (superpowers:code-reviewer):
|
||||||
DESCRIPTION: [task summary]
|
DESCRIPTION: [task summary]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**In addition to standard code quality concerns, the reviewer should check:**
|
||||||
|
- Does each file have one clear responsibility with a well-defined interface?
|
||||||
|
- Are units decomposed so they can be understood and tested independently?
|
||||||
|
- Is the implementation following the file structure from the plan?
|
||||||
|
- Did this implementation create new files that are already large, or significantly grow existing files? (Don't flag pre-existing file sizes — focus on what this change contributed.)
|
||||||
|
|
||||||
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
|
**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment
|
||||||
|
|
|
||||||
|
|
@ -41,6 +41,36 @@ Task tool (general-purpose):
|
||||||
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
|
**While you work:** If you encounter something unexpected or unclear, **ask questions**.
|
||||||
It's always OK to pause and clarify. Don't guess or make assumptions.
|
It's always OK to pause and clarify. Don't guess or make assumptions.
|
||||||
|
|
||||||
|
## Code Organization
|
||||||
|
|
||||||
|
You reason best about code you can hold in context at once, and your edits are more
|
||||||
|
reliable when files are focused. Keep this in mind:
|
||||||
|
- Follow the file structure defined in the plan
|
||||||
|
- Each file should have one clear responsibility with a well-defined interface
|
||||||
|
- If a file you're creating is growing beyond the plan's intent, stop and report
|
||||||
|
it as DONE_WITH_CONCERNS — don't split files on your own without plan guidance
|
||||||
|
- If an existing file you're modifying is already large or tangled, work carefully
|
||||||
|
and note it as a concern in your report
|
||||||
|
- In existing codebases, follow established patterns. Improve code you're touching
|
||||||
|
the way a good developer would, but don't restructure things outside your task.
|
||||||
|
|
||||||
|
## When You're in Over Your Head
|
||||||
|
|
||||||
|
It is always OK to stop and say "this is too hard for me." Bad work is worse than
|
||||||
|
no work. You will not be penalized for escalating.
|
||||||
|
|
||||||
|
**STOP and escalate when:**
|
||||||
|
- The task requires architectural decisions with multiple valid approaches
|
||||||
|
- You need to understand code beyond what was provided and can't find clarity
|
||||||
|
- You feel uncertain about whether your approach is correct
|
||||||
|
- The task involves restructuring existing code in ways the plan didn't anticipate
|
||||||
|
- You've been reading file after file trying to understand the system without progress
|
||||||
|
|
||||||
|
**How to escalate:** Report back with status BLOCKED or NEEDS_CONTEXT. Describe
|
||||||
|
specifically what you're stuck on, what you've tried, and what kind of help you need.
|
||||||
|
The controller can provide more context, re-dispatch with a more capable model,
|
||||||
|
or break the task into smaller pieces.
|
||||||
|
|
||||||
## Before Reporting Back: Self-Review
|
## Before Reporting Back: Self-Review
|
||||||
|
|
||||||
Review your work with fresh eyes. Ask yourself:
|
Review your work with fresh eyes. Ask yourself:
|
||||||
|
|
@ -70,9 +100,14 @@ Task tool (general-purpose):
|
||||||
## Report Format
|
## Report Format
|
||||||
|
|
||||||
When done, report:
|
When done, report:
|
||||||
- What you implemented
|
- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
|
||||||
|
- What you implemented (or what you attempted, if blocked)
|
||||||
- What you tested and test results
|
- What you tested and test results
|
||||||
- Files changed
|
- Files changed
|
||||||
- Self-review findings (if any)
|
- Self-review findings (if any)
|
||||||
- Any issues or concerns
|
- Any issues or concerns
|
||||||
|
|
||||||
|
Use DONE_WITH_CONCERNS if you completed the work but have doubts about correctness.
|
||||||
|
Use BLOCKED if you cannot complete the task. Use NEEDS_CONTEXT if you need
|
||||||
|
information that wasn't provided. Never silently produce work you're unsure about.
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -210,8 +210,9 @@ Ready to implement auth feature
|
||||||
|
|
||||||
**Called by:**
|
**Called by:**
|
||||||
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
|
- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows
|
||||||
|
- **subagent-driven-development** - REQUIRED before executing any tasks
|
||||||
|
- **executing-plans** - REQUIRED before executing any tasks
|
||||||
- Any skill needing isolated workspace
|
- Any skill needing isolated workspace
|
||||||
|
|
||||||
**Pairs with:**
|
**Pairs with:**
|
||||||
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
|
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
|
||||||
- **executing-plans** or **subagent-driven-development** - Work happens in this worktree
|
|
||||||
|
|
|
||||||
|
|
@ -3,6 +3,10 @@ name: using-superpowers
|
||||||
description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
|
description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
|
||||||
---
|
---
|
||||||
|
|
||||||
|
<SUBAGENT-STOP>
|
||||||
|
If you were dispatched as a subagent to execute a specific task, skip this skill.
|
||||||
|
</SUBAGENT-STOP>
|
||||||
|
|
||||||
<EXTREMELY-IMPORTANT>
|
<EXTREMELY-IMPORTANT>
|
||||||
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
|
If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
|
||||||
|
|
||||||
|
|
@ -11,12 +15,28 @@ IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
|
||||||
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
|
This is not negotiable. This is not optional. You cannot rationalize your way out of this.
|
||||||
</EXTREMELY-IMPORTANT>
|
</EXTREMELY-IMPORTANT>
|
||||||
|
|
||||||
|
## Instruction Priority
|
||||||
|
|
||||||
|
Superpowers skills override default system prompt behavior, but **user instructions always take precedence**:
|
||||||
|
|
||||||
|
1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority
|
||||||
|
2. **Superpowers skills** — override default system behavior where they conflict
|
||||||
|
3. **Default system prompt** — lowest priority
|
||||||
|
|
||||||
|
If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
|
||||||
|
|
||||||
## How to Access Skills
|
## How to Access Skills
|
||||||
|
|
||||||
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
|
**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
|
||||||
|
|
||||||
|
**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand.
|
||||||
|
|
||||||
**In other environments:** Check your platform's documentation for how skills are loaded.
|
**In other environments:** Check your platform's documentation for how skills are loaded.
|
||||||
|
|
||||||
|
## Platform Adaptation
|
||||||
|
|
||||||
|
Skills use Claude Code tool names. Non-CC platforms: see `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.
|
||||||
|
|
||||||
# Using Skills
|
# Using Skills
|
||||||
|
|
||||||
## The Rule
|
## The Rule
|
||||||
|
|
@ -26,6 +46,9 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
|
||||||
```dot
|
```dot
|
||||||
digraph skill_flow {
|
digraph skill_flow {
|
||||||
"User message received" [shape=doublecircle];
|
"User message received" [shape=doublecircle];
|
||||||
|
"About to EnterPlanMode?" [shape=doublecircle];
|
||||||
|
"Already brainstormed?" [shape=diamond];
|
||||||
|
"Invoke brainstorming skill" [shape=box];
|
||||||
"Might any skill apply?" [shape=diamond];
|
"Might any skill apply?" [shape=diamond];
|
||||||
"Invoke Skill tool" [shape=box];
|
"Invoke Skill tool" [shape=box];
|
||||||
"Announce: 'Using [skill] to [purpose]'" [shape=box];
|
"Announce: 'Using [skill] to [purpose]'" [shape=box];
|
||||||
|
|
@ -34,6 +57,11 @@ digraph skill_flow {
|
||||||
"Follow skill exactly" [shape=box];
|
"Follow skill exactly" [shape=box];
|
||||||
"Respond (including clarifications)" [shape=doublecircle];
|
"Respond (including clarifications)" [shape=doublecircle];
|
||||||
|
|
||||||
|
"About to EnterPlanMode?" -> "Already brainstormed?";
|
||||||
|
"Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
|
||||||
|
"Already brainstormed?" -> "Might any skill apply?" [label="yes"];
|
||||||
|
"Invoke brainstorming skill" -> "Might any skill apply?";
|
||||||
|
|
||||||
"User message received" -> "Might any skill apply?";
|
"User message received" -> "Might any skill apply?";
|
||||||
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
|
"Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
|
||||||
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
|
"Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,25 @@
|
||||||
|
# Codex Tool Mapping
|
||||||
|
|
||||||
|
Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
|
||||||
|
|
||||||
|
| Skill references | Codex equivalent |
|
||||||
|
|-----------------|------------------|
|
||||||
|
| `Task` tool (dispatch subagent) | `spawn_agent` |
|
||||||
|
| Multiple `Task` calls (parallel) | Multiple `spawn_agent` calls |
|
||||||
|
| Task returns result | `wait` |
|
||||||
|
| Task completes automatically | `close_agent` to free slot |
|
||||||
|
| `TodoWrite` (task tracking) | `update_plan` |
|
||||||
|
| `Skill` tool (invoke a skill) | Skills load natively — just follow the instructions |
|
||||||
|
| `Read`, `Write`, `Edit` (files) | Use your native file tools |
|
||||||
|
| `Bash` (run commands) | Use your native shell tools |
|
||||||
|
|
||||||
|
## Subagent dispatch requires collab
|
||||||
|
|
||||||
|
Add to your Codex config (`~/.codex/config.toml`):
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[features]
|
||||||
|
collab = true
|
||||||
|
```
|
||||||
|
|
||||||
|
This enables `spawn_agent`, `wait`, and `close_agent` for skills like `dispatching-parallel-agents` and `subagent-driven-development`.
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
# Gemini CLI Tool Mapping
|
||||||
|
|
||||||
|
Skills use Claude Code tool names. When you encounter these in a skill, use your platform equivalent:
|
||||||
|
|
||||||
|
| Skill references | Gemini CLI equivalent |
|
||||||
|
|-----------------|----------------------|
|
||||||
|
| `Read` (file reading) | `read_file` |
|
||||||
|
| `Write` (file creation) | `write_file` |
|
||||||
|
| `Edit` (file editing) | `replace` |
|
||||||
|
| `Bash` (run commands) | `run_shell_command` |
|
||||||
|
| `Grep` (search file content) | `grep_search` |
|
||||||
|
| `Glob` (search files by name) | `glob` |
|
||||||
|
| `TodoWrite` (task tracking) | `write_todos` |
|
||||||
|
| `Skill` tool (invoke a skill) | `activate_skill` |
|
||||||
|
| `WebSearch` | `google_web_search` |
|
||||||
|
| `WebFetch` | `web_fetch` |
|
||||||
|
| `Task` tool (dispatch subagent) | No equivalent — Gemini CLI does not support subagents |
|
||||||
|
|
||||||
|
## No subagent support
|
||||||
|
|
||||||
|
Gemini CLI has no equivalent to Claude Code's `Task` tool. Skills that rely on subagent dispatch (`subagent-driven-development`, `dispatching-parallel-agents`) will fall back to single-session execution via `executing-plans`.
|
||||||
|
|
||||||
|
## Additional Gemini CLI tools
|
||||||
|
|
||||||
|
These tools are available in Gemini CLI but have no Claude Code equivalent:
|
||||||
|
|
||||||
|
| Tool | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `list_directory` | List files and subdirectories |
|
||||||
|
| `save_memory` | Persist facts to GEMINI.md across sessions |
|
||||||
|
| `ask_user` | Request structured input from the user |
|
||||||
|
| `tracker_create_task` | Rich task management (create, update, list, visualize) |
|
||||||
|
| `enter_plan_mode` / `exit_plan_mode` | Switch to read-only research mode before making changes |
|
||||||
|
|
@ -15,7 +15,23 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
|
||||||
|
|
||||||
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
|
**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
|
||||||
|
|
||||||
**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
|
**Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
|
||||||
|
- (User preferences for plan location override this default)
|
||||||
|
|
||||||
|
## Scope Check
|
||||||
|
|
||||||
|
If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.
|
||||||
|
|
||||||
|
## File Structure
|
||||||
|
|
||||||
|
Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.
|
||||||
|
|
||||||
|
- Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
|
||||||
|
- You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
|
||||||
|
- Files that change together should live together. Split by responsibility, not by technical layer.
|
||||||
|
- In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.
|
||||||
|
|
||||||
|
This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.
|
||||||
|
|
||||||
## Bite-Sized Task Granularity
|
## Bite-Sized Task Granularity
|
||||||
|
|
||||||
|
|
@ -33,7 +49,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
|
||||||
```markdown
|
```markdown
|
||||||
# [Feature Name] Implementation Plan
|
# [Feature Name] Implementation Plan
|
||||||
|
|
||||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
**Goal:** [One sentence describing what this builds]
|
**Goal:** [One sentence describing what this builds]
|
||||||
|
|
||||||
|
|
@ -46,7 +62,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
|
||||||
|
|
||||||
## Task Structure
|
## Task Structure
|
||||||
|
|
||||||
```markdown
|
````markdown
|
||||||
### Task N: [Component Name]
|
### Task N: [Component Name]
|
||||||
|
|
||||||
**Files:**
|
**Files:**
|
||||||
|
|
@ -54,7 +70,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
|
||||||
- Modify: `exact/path/to/existing.py:123-145`
|
- Modify: `exact/path/to/existing.py:123-145`
|
||||||
- Test: `tests/exact/path/to/test.py`
|
- Test: `tests/exact/path/to/test.py`
|
||||||
|
|
||||||
**Step 1: Write the failing test**
|
- [ ] **Step 1: Write the failing test**
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def test_specific_behavior():
|
def test_specific_behavior():
|
||||||
|
|
@ -62,30 +78,30 @@ def test_specific_behavior():
|
||||||
assert result == expected
|
assert result == expected
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 2: Run test to verify it fails**
|
- [ ] **Step 2: Run test to verify it fails**
|
||||||
|
|
||||||
Run: `pytest tests/path/test.py::test_name -v`
|
Run: `pytest tests/path/test.py::test_name -v`
|
||||||
Expected: FAIL with "function not defined"
|
Expected: FAIL with "function not defined"
|
||||||
|
|
||||||
**Step 3: Write minimal implementation**
|
- [ ] **Step 3: Write minimal implementation**
|
||||||
|
|
||||||
```python
|
```python
|
||||||
def function(input):
|
def function(input):
|
||||||
return expected
|
return expected
|
||||||
```
|
```
|
||||||
|
|
||||||
**Step 4: Run test to verify it passes**
|
- [ ] **Step 4: Run test to verify it passes**
|
||||||
|
|
||||||
Run: `pytest tests/path/test.py::test_name -v`
|
Run: `pytest tests/path/test.py::test_name -v`
|
||||||
Expected: PASS
|
Expected: PASS
|
||||||
|
|
||||||
**Step 5: Commit**
|
- [ ] **Step 5: Commit**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git add tests/path/test.py src/path/file.py
|
git add tests/path/test.py src/path/file.py
|
||||||
git commit -m "feat: add specific feature"
|
git commit -m "feat: add specific feature"
|
||||||
```
|
```
|
||||||
```
|
````
|
||||||
|
|
||||||
## Remember
|
## Remember
|
||||||
- Exact file paths always
|
- Exact file paths always
|
||||||
|
|
@ -94,23 +110,38 @@ git commit -m "feat: add specific feature"
|
||||||
- Reference relevant skills with @ syntax
|
- Reference relevant skills with @ syntax
|
||||||
- DRY, YAGNI, TDD, frequent commits
|
- DRY, YAGNI, TDD, frequent commits
|
||||||
|
|
||||||
|
## Plan Review Loop
|
||||||
|
|
||||||
|
After completing each chunk of the plan:
|
||||||
|
|
||||||
|
1. Dispatch plan-document-reviewer subagent (see plan-document-reviewer-prompt.md) with precisely crafted review context — never your session history. This keeps the reviewer focused on the plan, not your thought process.
|
||||||
|
- Provide: chunk content, path to spec document
|
||||||
|
2. If ❌ Issues Found:
|
||||||
|
- Fix the issues in the chunk
|
||||||
|
- Re-dispatch reviewer for that chunk
|
||||||
|
- Repeat until ✅ Approved
|
||||||
|
3. If ✅ Approved: proceed to next chunk (or execution handoff if last chunk)
|
||||||
|
|
||||||
|
**Chunk boundaries:** Use `## Chunk N: <name>` headings to delimit chunks. Each chunk should be ≤1000 lines and logically self-contained.
|
||||||
|
|
||||||
|
**Review loop guidance:**
|
||||||
|
- Same agent that wrote the plan fixes it (preserves context)
|
||||||
|
- If loop exceeds 5 iterations, surface to human for guidance
|
||||||
|
- Reviewers are advisory - explain disagreements if you believe feedback is incorrect
|
||||||
|
|
||||||
## Execution Handoff
|
## Execution Handoff
|
||||||
|
|
||||||
After saving the plan, offer execution choice:
|
After saving the plan:
|
||||||
|
|
||||||
**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
|
**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Ready to execute?"**
|
||||||
|
|
||||||
**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
|
**Execution path depends on harness capabilities:**
|
||||||
|
|
||||||
**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
|
**If harness has subagents (Claude Code, etc.):**
|
||||||
|
- **REQUIRED:** Use superpowers:subagent-driven-development
|
||||||
|
- Do NOT offer a choice - subagent-driven is the standard approach
|
||||||
|
- Fresh subagent per task + two-stage review
|
||||||
|
|
||||||
**Which approach?"**
|
**If harness does NOT have subagents:**
|
||||||
|
- Execute plan in current session using superpowers:executing-plans
|
||||||
**If Subagent-Driven chosen:**
|
- Batch execution with checkpoints for review
|
||||||
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
|
|
||||||
- Stay in this session
|
|
||||||
- Fresh subagent per task + code review
|
|
||||||
|
|
||||||
**If Parallel Session chosen:**
|
|
||||||
- Guide them to open new session in worktree
|
|
||||||
- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
|
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,52 @@
|
||||||
|
# Plan Document Reviewer Prompt Template
|
||||||
|
|
||||||
|
Use this template when dispatching a plan document reviewer subagent.
|
||||||
|
|
||||||
|
**Purpose:** Verify the plan chunk is complete, matches the spec, and has proper task decomposition.
|
||||||
|
|
||||||
|
**Dispatch after:** Each plan chunk is written
|
||||||
|
|
||||||
|
```
|
||||||
|
Task tool (general-purpose):
|
||||||
|
description: "Review plan chunk N"
|
||||||
|
prompt: |
|
||||||
|
You are a plan document reviewer. Verify this plan chunk is complete and ready for implementation.
|
||||||
|
|
||||||
|
**Plan chunk to review:** [PLAN_FILE_PATH] - Chunk N only
|
||||||
|
**Spec for reference:** [SPEC_FILE_PATH]
|
||||||
|
|
||||||
|
## What to Check
|
||||||
|
|
||||||
|
| Category | What to Look For |
|
||||||
|
|----------|------------------|
|
||||||
|
| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
|
||||||
|
| Spec Alignment | Chunk covers relevant spec requirements, no scope creep |
|
||||||
|
| Task Decomposition | Tasks atomic, clear boundaries, steps actionable |
|
||||||
|
| File Structure | Files have clear single responsibilities, split by responsibility not layer |
|
||||||
|
| File Size | Would any new or modified file likely grow large enough to be hard to reason about as a whole? |
|
||||||
|
| Task Syntax | Checkbox syntax (`- [ ]`) on steps for tracking |
|
||||||
|
| Chunk Size | Each chunk under 1000 lines |
|
||||||
|
|
||||||
|
## CRITICAL
|
||||||
|
|
||||||
|
Look especially hard for:
|
||||||
|
- Any TODO markers or placeholder text
|
||||||
|
- Steps that say "similar to X" without actual content
|
||||||
|
- Incomplete task definitions
|
||||||
|
- Missing verification steps or expected outputs
|
||||||
|
- Files planned to hold multiple responsibilities or likely to grow unwieldy
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
## Plan Review - Chunk N
|
||||||
|
|
||||||
|
**Status:** Approved | Issues Found
|
||||||
|
|
||||||
|
**Issues (if any):**
|
||||||
|
- [Task X, Step Y]: [specific issue] - [why it matters]
|
||||||
|
|
||||||
|
**Recommendations (advisory):**
|
||||||
|
- [suggestions that don't block approval]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Reviewer returns:** Status, Issues (if any), Recommendations
|
||||||
|
|
@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
|
||||||
|
|
||||||
**Writing skills IS Test-Driven Development applied to process documentation.**
|
**Writing skills IS Test-Driven Development applied to process documentation.**
|
||||||
|
|
||||||
**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)**
|
**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)**
|
||||||
|
|
||||||
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
|
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue