@vpxa/kb 0.1.13 → 0.1.16

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+argument-hint: "Feature, component, or behavior to design"
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+<HARD-GATE>
+Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+</HARD-GATE>
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+---
+
+## Mode Selection
+
+This skill operates in two modes. **You decide which mode to use** based on the task characteristics — do NOT ask the user which mode.
+
+### Simple Mode
+
+Use when **all** of these are true:
+- Affects ≤3 files
+- Single component or concern
+- No new service/package/module boundaries
+- No cross-service data flow changes
+- Clear, well-understood domain
+
+Examples: config change, utility function, bug fix with design ambiguity, small feature in existing component.
+
+### Advanced Mode
+
+Use when **any** of these are true:
+- Affects >3 files or crosses service boundaries
+- Introduces new packages, services, or modules
+- Multiple independent subsystems involved
+- Architectural decisions with multiple viable approaches
+- Changes data models, APIs, or interfaces used by other services
+- User explicitly requests thorough exploration
+
+Examples: new notification channel, new API service, platform redesign, multi-service feature, infrastructure changes.
+
+---
+
+## Simple Mode Process
+
+### Checklist
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+3. **Propose 2-3 approaches** — with trade-offs and your recommendation
+4. **Present design** — in sections scaled to their complexity, get user approval after each section
+5. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
+6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+### Process Flow
+
+```dot
+digraph brainstorming_simple {
+    "Explore project context" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+    "Explore project context" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Propose 2-3 approaches";
+    "Propose 2-3 approaches" -> "Present design sections";
+    "Present design sections" -> "User approves design?";
+    "User approves design?" -> "Present design sections" [label="no, revise"];
+    "User approves design?" -> "Write design doc" [label="yes"];
+    "Write design doc" -> "Invoke writing-plans skill";
+}
+```
+
+---
+
+## Advanced Mode Process
+
+### Checklist
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Assess scope** — if multiple independent subsystems, decompose before detailing (see below)
+3. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See `visual-companion.md`.
+4. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+5. **Propose 2-3 approaches via Decision Protocol** — launch ALL 4 Researcher variants in parallel to independently generate approaches. Synthesize their output into deduplicated options with trade-offs and your recommendation. Present agreements and disagreements to the user. *(See "Decision Protocol Integration" below.)*
+6. **Present design** — in sections scaled to their complexity, get user approval after each section
+7. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
+8. **Spec review loop** — review the spec for completeness, consistency, clarity, scope, and YAGNI. Fix issues. Max 3 iterations, then surface to user.
+9. **User reviews written spec** — ask user to review the spec file before proceeding
+10. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+### Decision Protocol Integration (Advanced Mode Only)
+
+When Advanced Mode reaches step 5 ("Propose approaches"), invoke the **multi-model decision protocol**:
+
+1. Frame the design question with full context gathered from steps 1-4
+2. Launch ALL 4 Researcher variants **in parallel** with identical framing:
+   > Independently analyze this design question. Propose 2-3 approaches with trade-offs, complexity, risks, and your recommendation.
+3. After all return, synthesize:
+   - **Strong agreements** (3+ models align) → Accept as validated direction
+   - **Disagreements** → Present each position to the user with reasoning
+4. Present the deduplicated approaches to the user for choice
+5. If a decision produces an ADR, write it to `docs/decisions/`
+
+This replaces the single-agent "propose approaches" step with 4 independent perspectives, producing higher-quality options.
+
+### Process Flow
+
+```dot
+digraph brainstorming_advanced {
+    "Explore project context" [shape=box];
+    "Assess scope" [shape=diamond];
+    "Decompose into sub-projects" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message)" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Decision Protocol:\n4 Researchers in parallel" [shape=box, style=bold];
+    "Synthesize 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" -> "Assess scope";
+    "Assess scope" -> "Decompose into sub-projects" [label="too large"];
+    "Assess scope" -> "Visual questions ahead?" [label="right-sized"];
+    "Decompose into sub-projects" -> "Visual questions ahead?" [label="first sub-project"];
+    "Visual questions ahead?" -> "Offer Visual Companion\n(own message)" [label="yes"];
+    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
+    "Offer Visual Companion\n(own message)" -> "Ask clarifying questions";
+    "Ask clarifying questions" -> "Decision Protocol:\n4 Researchers in parallel";
+    "Decision Protocol:\n4 Researchers in parallel" -> "Synthesize approaches";
+    "Synthesize 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, fix"];
+    "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"];
+}
+```
+
+### Large Project Decomposition
+
+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.
+
+### Spec Review Loop
+
+After writing the spec document, review it yourself for:
+
+| Category | What to Look For |
+|----------|------------------|
+| Completeness | TODOs, placeholders, "TBD", incomplete sections |
+| Consistency | Internal contradictions, conflicting requirements |
+| Clarity | Requirements ambiguous enough to cause someone to build the wrong thing |
+| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
+| YAGNI | Unrequested features, over-engineering |
+
+**Only flag issues that would cause real problems during implementation planning.** A missing section, a contradiction, or a requirement so ambiguous it could be interpreted two different ways — those are issues. Minor wording improvements and stylistic preferences are not.
+
+Fix issues and re-review. Max 3 iterations, then surface remaining concerns to the user.
+
+### User Review Gate
+
+After the spec review passes, ask the user to review:
+
+> "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. Only proceed once the user approves.
+
+---
+
+## The Process (Both Modes)
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message — if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+**Design for isolation and clarity** (Advanced mode emphasis, but good practice always):
+- 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.
+
+**Working in existing codebases:**
+- Explore the current structure before proposing changes. Follow existing patterns.
+- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design — the way a good developer improves code they're working in.
+- Don't propose unrelated refactoring. Stay focused on what serves the current goal.
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation:**
+- Invoke the writing-plans skill to create a detailed implementation plan
+- Do NOT invoke any other skill. writing-plans is the next step.
+
+**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.
+
+## Key Principles
+
+- **One question at a time** — Don't overwhelm with multiple questions
+- **Multiple choice preferred** — Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** — Remove unnecessary features from all designs
+- **Explore alternatives** — Always propose 2-3 approaches before settling
+- **Incremental validation** — Present design, get approval before moving on
+- **Be flexible** — Go back and clarify when something doesn't make sense
+
+## Visual Companion (Advanced Mode Only)
+
+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. The browser opens automatically when I start the visual companion. This feature is still new and can be token-intensive. Want to try it?"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. 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 visual content — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for text content — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+If they agree to the companion, read `visual-companion.md` for the detailed setup and usage guide.

package/skills/brainstorming/scripts/frame-template.html

@@ -0,0 +1,365 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Brainstorming</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+  :root {
+    --bg: #0d1117;
+    --surface: #161b22;
+    --border: #30363d;
+    --text: #e6edf3;
+    --text-muted: #8b949e;
+    --accent: #58a6ff;
+    --accent-glow: rgba(88, 166, 255, 0.15);
+    --success: #3fb950;
+    --radius: 8px;
+  }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.6;
+    min-height: 100vh;
+  }
+
+  .frame-header {
+    padding: 16px 24px;
+    border-bottom: 1px solid var(--border);
+    display: flex;
+    align-items: center;
+    gap: 12px;
+  }
+  .frame-header .logo {
+    font-size: 14px;
+    font-weight: 600;
+    color: var(--text-muted);
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+  }
+
+  .frame-content {
+    max-width: 960px;
+    margin: 0 auto;
+    padding: 32px 24px;
+  }
+
+  /* Selection indicator bar */
+  #selection-indicator {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    background: var(--surface);
+    border-top: 1px solid var(--border);
+    padding: 12px 24px;
+    display: none;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    font-size: 14px;
+    color: var(--accent);
+    z-index: 100;
+  }
+  #selection-indicator.visible { display: flex; }
+  #selection-indicator .check { font-size: 18px; }
+
+  /* Typography */
+  h2 {
+    font-size: 24px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    color: var(--text);
+  }
+  h3 {
+    font-size: 18px;
+    font-weight: 600;
+    margin-bottom: 4px;
+    color: var(--text);
+  }
+  h4 {
+    font-size: 14px;
+    font-weight: 600;
+    margin-bottom: 8px;
+    color: var(--text);
+  }
+  .subtitle {
+    font-size: 16px;
+    color: var(--text-muted);
+    margin-bottom: 24px;
+  }
+  .section {
+    margin-bottom: 32px;
+  }
+  .label {
+    font-size: 11px;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.8px;
+    color: var(--text-muted);
+    margin-bottom: 8px;
+  }
+
+  /* Options (A/B/C choices) */
+  .options {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+    margin: 16px 0;
+  }
+  .option {
+    display: flex;
+    align-items: flex-start;
+    gap: 16px;
+    padding: 16px 20px;
+    background: var(--surface);
+    border: 2px solid var(--border);
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: border-color 0.15s, background 0.15s;
+  }
+  .option:hover {
+    border-color: var(--accent);
+    background: var(--accent-glow);
+  }
+  .option.selected {
+    border-color: var(--accent);
+    background: var(--accent-glow);
+  }
+  .option .letter {
+    flex-shrink: 0;
+    width: 32px;
+    height: 32px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    border-radius: 50%;
+    background: var(--border);
+    font-weight: 700;
+    font-size: 14px;
+    color: var(--text-muted);
+    transition: background 0.15s, color 0.15s;
+  }
+  .option.selected .letter {
+    background: var(--accent);
+    color: var(--bg);
+  }
+  .option .content { flex: 1; }
+  .option .content p {
+    color: var(--text-muted);
+    font-size: 14px;
+    margin-top: 4px;
+  }
+
+  /* Cards (visual designs) */
+  .cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 16px;
+    margin: 16px 0;
+  }
+  .card {
+    background: var(--surface);
+    border: 2px solid var(--border);
+    border-radius: var(--radius);
+    overflow: hidden;
+    cursor: pointer;
+    transition: border-color 0.15s, transform 0.15s;
+  }
+  .card:hover {
+    border-color: var(--accent);
+    transform: translateY(-2px);
+  }
+  .card.selected {
+    border-color: var(--accent);
+  }
+  .card-image {
+    padding: 20px;
+    background: rgba(255,255,255,0.02);
+    min-height: 180px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .card-body {
+    padding: 16px;
+  }
+  .card-body p {
+    color: var(--text-muted);
+    font-size: 14px;
+    margin-top: 4px;
+  }
+
+  /* Mockup container */
+  .mockup {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    overflow: hidden;
+    margin: 16px 0;
+  }
+  .mockup-header {
+    padding: 8px 16px;
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--text-muted);
+    background: rgba(255,255,255,0.03);
+    border-bottom: 1px solid var(--border);
+  }
+  .mockup-body {
+    padding: 20px;
+  }
+
+  /* Split view */
+  .split {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 16px;
+    margin: 16px 0;
+  }
+  @media (max-width: 700px) {
+    .split { grid-template-columns: 1fr; }
+  }
+
+  /* Pros/Cons */
+  .pros-cons {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 16px;
+    margin: 16px 0;
+  }
+  .pros, .cons {
+    padding: 16px;
+    border-radius: var(--radius);
+  }
+  .pros {
+    background: rgba(63, 185, 80, 0.08);
+    border: 1px solid rgba(63, 185, 80, 0.3);
+  }
+  .cons {
+    background: rgba(248, 81, 73, 0.08);
+    border: 1px solid rgba(248, 81, 73, 0.3);
+  }
+  .pros h4 { color: #3fb950; }
+  .cons h4 { color: #f85149; }
+  .pros-cons ul {
+    list-style: none;
+    padding: 0;
+  }
+  .pros-cons li {
+    padding: 4px 0;
+    font-size: 14px;
+    color: var(--text-muted);
+  }
+  .pros-cons li::before {
+    margin-right: 8px;
+    font-weight: 600;
+  }
+  .pros li::before { content: '+'; color: #3fb950; }
+  .cons li::before { content: '−'; color: #f85149; }
+
+  /* Mock elements (wireframe building blocks) */
+  .mock-nav {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 12px 20px;
+    font-size: 14px;
+    color: var(--text-muted);
+    margin-bottom: 12px;
+  }
+  .mock-sidebar {
+    width: 200px;
+    flex-shrink: 0;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 16px;
+    font-size: 13px;
+    color: var(--text-muted);
+    margin-right: 12px;
+  }
+  .mock-content {
+    flex: 1;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 20px;
+    font-size: 14px;
+    color: var(--text-muted);
+    min-height: 200px;
+  }
+  .mock-button {
+    padding: 8px 20px;
+    background: var(--accent);
+    color: var(--bg);
+    border: none;
+    border-radius: 6px;
+    font-size: 14px;
+    font-weight: 600;
+    cursor: pointer;
+  }
+  .mock-button:hover { opacity: 0.9; }
+  .mock-input {
+    padding: 8px 12px;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    color: var(--text);
+    font-size: 14px;
+    width: 100%;
+    max-width: 300px;
+  }
+  .mock-input::placeholder { color: var(--text-muted); }
+  .placeholder {
+    background: rgba(255,255,255,0.03);
+    border: 1px dashed var(--border);
+    border-radius: var(--radius);
+    padding: 40px 20px;
+    text-align: center;
+    color: var(--text-muted);
+    font-size: 14px;
+  }
+
+  /* General list styling inside content */
+  .frame-content ul, .frame-content ol {
+    padding-left: 20px;
+    margin: 8px 0;
+  }
+  .frame-content li {
+    margin: 4px 0;
+    color: var(--text-muted);
+    font-size: 14px;
+  }
+  .frame-content p {
+    margin: 8px 0;
+  }
+  .frame-content a {
+    color: var(--accent);
+    text-decoration: none;
+  }
+  .frame-content a:hover { text-decoration: underline; }
+
+</style>
+</head>
+<body>
+  <div class="frame-header">
+    <span class="logo">Brainstorming</span>
+  </div>
+  <div class="frame-content">
+    <!-- CONTENT -->
+  </div>
+  <div id="selection-indicator">
+    <span class="check">✓</span>
+    <span id="selection-text">Selected</span>
+  </div>
+  <script>
+    const BRAINSTORM_DIR = __BRAINSTORM_DIR__;
+    <!-- HELPER_SCRIPT -->
+  </script>
+</body>
+</html>