<EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**

---
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
---

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-STOP>

<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 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.
</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

**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 Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Claude Code's `Skill` tool.

**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.

## Platform Adaptation

Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.

# Using Skills

## The Rule

**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.

```dot
digraph skill_flow {
    "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];
    "Invoke Skill tool" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create TodoWrite todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "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?";
    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create TodoWrite todo per item" -> "Follow skill exactly";
}
```

## Red Flags

These thoughts mean STOP—you're rationalizing:

| Thought | Reality |
|---------|---------|
| "This is just a simple question" | Questions are tasks. Check for skills. |
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
| "Let me gather information first" | Skills tell you HOW to gather information. |
| "This doesn't need a formal skill" | If a skill exists, use it. |
| "I remember this skill" | Skills evolve. Read current version. |
| "This doesn't count as a task" | Action = task. Check for skills. |
| "The skill is overkill" | Simple things become complex. Use it. |
| "I'll just do this one thing first" | Check BEFORE doing anything. |
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |

## Skill Priority

When multiple skills could apply, use this order:

1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution

"Let's build X" → brainstorming first, then implementation skills.
"Fix this bug" → debugging first, then domain-specific skills.

## Skill Types

**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.

**Flexible** (patterns): Adapt principles to context.

The skill itself tells you which.

## User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

</EXTREMELY_IMPORTANT>


<memvid-mind-context>
# 🧠 Claude Mind Ready

📁 Project: **heapoverflow**
💾 Memory will be created at: `.claude/mind.mv2`

_Your observations will be automatically captured._
</memvid-mind-context>


<EXTREMELY_IMPORTANT>
You have superpowers.

**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**

---
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
---

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task, skip this skill.
</SUBAGENT-STOP>

<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 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.
</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

**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 Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. The `skill` tool works the same as Claude Code's `Skill` tool.

**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.

## Platform Adaptation

Skills use Claude Code tool names. Non-CC platforms: see `references/copilot-tools.md` (Copilot CLI), `references/codex-tools.md` (Codex) for tool equivalents. Gemini CLI users get the tool mapping loaded automatically via GEMINI.md.

# Using Skills

## The Rule

**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.

```dot
digraph skill_flow {
    "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];
    "Invoke Skill tool" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create TodoWrite todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "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?";
    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create TodoWrite todo per item" -> "Follow skill exactly";
}
```

## Red Flags

These thoughts mean STOP—you're rationalizing:

| Thought | Reality |
|---------|---------|
| "This is just a simple question" | Questions are tasks. Check for skills. |
| "I need more context first" | Skill check comes BEFORE clarifying questions. |
| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
| "Let me gather information first" | Skills tell you HOW to gather information. |
| "This doesn't need a formal skill" | If a skill exists, use it. |
| "I remember this skill" | Skills evolve. Read current version. |
| "This doesn't count as a task" | Action = task. Check for skills. |
| "The skill is overkill" | Simple things become complex. Use it. |
| "I'll just do this one thing first" | Check BEFORE doing anything. |
| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
| "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |

## Skill Priority

When multiple skills could apply, use this order:

1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution

"Let's build X" → brainstorming first, then implementation skills.
"Fix this bug" → debugging first, then domain-specific skills.

## Skill Types

**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.

**Flexible** (patterns): Adapt principles to context.

The skill itself tells you which.

## User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

</EXTREMELY_IMPORTANT>

<memvid-mind-context>
# 🧠 Claude Mind Ready

📁 Project: **heapoverflow**
💾 Memory will be created at: `.claude/mind.mv2`

_Your observations will be automatically captured._
</memvid-mind-context>


I want to create a StackOverflow for Teams clone using our internal UI library at @~/projects/pxl-components and I have an export of currently existing data in @data that I will want to import


.postcssrc.json
.cursor
tailwind.config.js
iPXL-dark.svg
projects
.tool-versions
PULL_REQUEST_TEMPLATE.md
.npmrc
playwright
iPXL-white.svg
.prettierignore
figma.config.json
.editorconfig
README.md
angular.json
.gitignore
package-lock.json
package.json
.prettierrc.js
.nvmrc
.github
.gitattributes
tsconfig.json
kendo-ui-license.txt
playwright.config.ts
eslint.config.js
AGENTS.md
.git
.vscode
chromatic.config.json


user_groups.json
users.json
questions_answers_comments.json
articles.json
tags.json


## claude.ai Context7
Use this server to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.

Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.


- obsidian-load: Load context from Obsidian notes in the `Claude/` directory into the current conversation.
- obsidian-save: Save current conversation context to an Obsidian note under the `Claude/` directory.
- mind:search: Search memories for specific content or patterns
- mind:ask: Ask questions about memories and get context-aware answers
- mind:stats: Show memory statistics and storage information
- mind:recent: Show recent memories and activity timeline
- superpowers:using-git-worktrees: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
- superpowers:test-driven-development: Use when implementing any feature or bugfix, before writing implementation code
- superpowers:receiving-code-review: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
- superpowers:requesting-code-review: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
- superpowers:verification-before-completion: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
- superpowers:executing-plans: Use when you have a written implementation plan to execute in a separate session with review checkpoints
- superpowers:writing-plans: Use when you have a spec or requirements for a multi-step task, before touching code
- superpowers:systematic-debugging: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
- superpowers:writing-skills: Use when creating new skills, editing existing skills, or verifying skills work before deployment
- superpowers:dispatching-parallel-agents: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
- superpowers:using-superpowers: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
- superpowers:brainstorming: 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.
- superpowers:finishing-a-development-branch: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
- superpowers:subagent-driven-development: Use when executing implementation plans with independent tasks in the current session
- mind:mind: Claude Mind - Search and manage Claude's persistent memory stored in a single portable .mv2 file
- mind:memory: Claude Mind - Search and manage Claude's persistent memory stored in a single portable .mv2 file
- update-config: Use this skill to configure the Claude Code harness via settings.json. Automated behaviors ("from now on when X", "each time X", "whenever X", "before/after X") require hooks configured in settings.json - the harness executes these, not Claude, so memory/preferences cannot fulfill them. Also use for: permissions ("allow X", "add permission", "move permission to"), env vars ("set X=Y"), hook troubleshooting, or any changes to settings.json/settings.local.json files. Examples: "allow npm commands", "add bq permission to global settings", "move permission to user settings", "set DEBUG=true", "when claude stops show X". For simple settings like theme/model, suggest the /config command.
- keybindings-help: Use when the user wants to customize keyboard shortcuts, rebind keys, add chord bindings, or modify ~/.claude/keybindings.json. Examples: "rebind ctrl+s", "add a chord shortcut", "change the submit key", "customize keybindings".
- simplify: Review changed code for reuse, quality, and efficiency, then fix any issues found.
- fewer-permission-prompts: Scan your transcripts for common read-only Bash and MCP tool calls, then add a prioritized allowlist to project .claude/settings.json to reduce permission prompts.
- loop: Run a prompt or slash command on a recurring interval (e.g. /loop 5m /foo). Omit the interval to let the model self-pace. - When the user wants to set up a recurring task, poll for status, or run something repeatedly on an interval (e.g. "check the deploy every 5 minutes", "keep running /babysit-prs"). Do NOT invoke for one-off tasks.
- schedule: Create, update, list, or run scheduled remote agents (routines) that execute on a cron schedule. - When the user wants to schedule a recurring remote agent, set up automated tasks, create a cron job for Claude Code, or manage their scheduled agents/routines. Also use when the user wants a one-time scheduled run ("run this once at 3pm", "remind me to check X tomorrow").
- claude-api: Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements).
TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project.
SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML.
- init: Initialize a new CLAUDE.md file with codebase documentation
- review: Review a pull request
- security-review: Complete a security review of the pending changes on the current branch


Build Stack Overflow Teams clone with pxl-components


Launching skill: superpowers:brainstorming


Base directory for this skill: /Users/steve.briggs/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0/skills/brainstorming

# Brainstorming Ideas Into Designs

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
</HARD-GATE>

## Anti-Pattern: "This Is Too Simple To Need A Design"

Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.

## Checklist

You MUST create a task for each of these items and complete them in order:

1. **Explore project context** — check files, docs, recent commits
2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
4. **Propose 2-3 approaches** — with trade-offs and your recommendation
5. **Present design** — in sections scaled to their complexity, get user approval after each section
6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
8. **User reviews written spec** — ask user to review the spec file before proceeding
9. **Transition to implementation** — invoke writing-plans skill to create implementation plan

## Process Flow

```dot
digraph brainstorming {
    "Explore project context" [shape=box];
    "Visual questions ahead?" [shape=diamond];
    "Offer Visual Companion\n(own message, no other content)" [shape=box];
    "Ask clarifying questions" [shape=box];
    "Propose 2-3 approaches" [shape=box];
    "Present design sections" [shape=box];
    "User approves design?" [shape=diamond];
    "Write design doc" [shape=box];
    "Spec self-review\n(fix inline)" [shape=box];
    "User reviews spec?" [shape=diamond];
    "Invoke writing-plans skill" [shape=doublecircle];

    "Explore project context" -> "Visual questions ahead?";
    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
    "Ask clarifying questions" -> "Propose 2-3 approaches";
    "Propose 2-3 approaches" -> "Present design sections";
    "Present design sections" -> "User approves design?";
    "User approves design?" -> "Present design sections" [label="no, revise"];
    "User approves design?" -> "Write design doc" [label="yes"];
    "Write design doc" -> "Spec self-review\n(fix inline)";
    "Spec self-review\n(fix inline)" -> "User reviews spec?";
    "User reviews spec?" -> "Write design doc" [label="changes requested"];
    "User reviews spec?" -> "Invoke writing-plans skill" [label="approved"];
}
```

**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.

## The Process

**Understanding the idea:**

- Check out the current project state first (files, docs, recent commits)
- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
- For appropriately-scoped projects, ask questions one at a time to refine the idea
- Prefer multiple choice questions when possible, but open-ended is fine too
- Only one question per message - if a topic needs more exploration, break it into multiple questions
- Focus on understanding: purpose, constraints, success criteria

**Exploring approaches:**

- Propose 2-3 different approaches with trade-offs
- Present options conversationally with your recommendation and reasoning
- Lead with your recommended option and explain why

**Presenting the design:**

- Once you believe you understand what you're building, present the design
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
- Ask after each section whether it looks right so far
- Cover: architecture, components, data flow, error handling, testing
- Be ready to go back and clarify if something doesn't make sense

**Design for isolation and clarity:**

- Break the system into smaller units that each have one clear purpose, communicate through well-defined interfaces, and can be understood and tested independently
- For each unit, you should be able to answer: what does it do, how do you use it, and what does it depend on?
- Can someone understand what a unit does without reading its internals? Can you change the internals without breaking consumers? If not, the boundaries need work.
- Smaller, well-bounded units are also easier for you to work with - you reason better about code you can hold in context at once, and your edits are more reliable when files are focused. When a file grows large, that's often a signal that it's doing too much.

**Working in existing codebases:**

- Explore the current structure before proposing changes. Follow existing patterns.
- Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
- Don't propose unrelated refactoring. Stay focused on what serves the current goal.

## After the Design

**Documentation:**

- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
  - (User preferences for spec location override this default)
- Use elements-of-style:writing-clearly-and-concisely skill if available
- Commit the design document to git

**Spec Self-Review:**
After writing the spec document, look at it with fresh eyes:

1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
4. **Ambiguity check:** Could any requirement be interpreted two different ways? If so, pick one and make it explicit.

Fix any issues inline. No need to re-review — just fix and move on.

**User Review Gate:**
After the spec review loop passes, ask the user to review the written spec before proceeding:

> "Spec written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Wait for the user's response. If they request changes, make them and re-run the spec review loop. Only proceed once the user approves.

**Implementation:**

- Invoke the writing-plans skill to create a detailed implementation plan
- Do NOT invoke any other skill. writing-plans is the next step.

## Key Principles

- **One question at a time** - Don't overwhelm with multiple questions
- **Multiple choice preferred** - Easier to answer than open-ended when possible
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
- **Explore alternatives** - Always propose 2-3 approaches before settling
- **Incremental validation** - Present design, get approval before moving on
- **Be flexible** - Go back and clarify when something doesn't make sense

## Visual Companion

A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.

**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"

**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.

**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**

- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions

A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.

If they agree to the companion, read the detailed guide before proceeding:
`skills/brainstorming/visual-companion.md`


ToolSearch

Question: select:TaskCreate


Question: select:TaskCreate


TaskCreate

Explore project context

Check pxl-components library, data files, and any existing project structure


Task #1 created successfully: Explore project context

Explore project context


Offer visual companion

Offer the visual browser companion for UI mockups


Task #2 created successfully: Offer visual companion

Offer visual companion


Ask clarifying questions

One at a time, understand purpose, constraints, and success criteria


Task #3 created successfully: Ask clarifying questions

Ask clarifying questions


Propose 2-3 approaches

Present trade-offs and a recommendation


Task #4 created successfully: Propose 2-3 approaches

Propose 2-3 approaches


Present design

In sections scaled to complexity, get user approval after each section


Task #5 created successfully: Present design

Present design


Write design doc

Save to docs/superpowers/specs/YYYY-MM-DD-heapoverflow-design.md and commit


Task #6 created successfully: Write design doc

Write design doc


Spec self-review

Check for placeholders, contradictions, ambiguity, scope issues


Task #7 created successfully: Spec self-review

Spec self-review


User reviews written spec

Ask user to review spec file before proceeding


Task #8 created successfully: User reviews written spec

User reviews written spec


Transition to implementation

Invoke writing-plans skill to create implementation plan


Task #9 created successfully: Transition to implementation

Transition to implementation


ToolSearch

Question: select:TaskUpdate


Question: select:TaskUpdate


Updated task #1 status


Exploring the project context now — checking the data files and pxl-components library structure in parallel.


Bash

ls /Users/steve.briggs/projects/heapoverflow && echo "---" && ls /Users/steve.briggs/projects/heapoverflow/data

List heapoverflow project root and data directory


Agent

Explore pxl-components library structure

Prompt:
Explore the Angular component library at /Users/steve.briggs/projects/pxl-components. I need to understand:
1. What UI components are available (list them with brief descriptions)
2. What the overall tech stack is (framework, styling, etc.)
3. Where components are defined (e.g., src/lib or projects/)
4. Any design tokens, theming, or style conventions

Look at the package.json, angular.json, and the component source files. Focus on what's available to use, not how it's built internally. Report in under 300 words.


drwxr-xr-x steve.briggs staff 224 B  Thu May  7 19:59:38 2026 data
drwxr-xr-x steve.briggs staff  96 B  Thu May  7 19:59:38 2026 .
drwxr-xr-x steve.briggs staff 1.7 KB Thu May  7 19:59:57 2026 ..
---
.rw-r--r-- steve.briggs staff  16 KB Thu May  7 19:59:30 2026 articles.json
.rw-r--r-- steve.briggs staff 3.0 MB Thu May  7 19:59:30 2026 questions_answers_comments.json
.rw-r--r-- steve.briggs staff  55 KB Thu May  7 19:59:30 2026 tags.json
.rw-r--r-- steve.briggs staff   2 B  Thu May  7 19:59:30 2026 user_groups.json
.rw-r--r-- steve.briggs staff 103 KB Thu May  7 19:59:30 2026 users.json
drwxr-xr-x steve.briggs staff 224 B  Thu May  7 19:59:38 2026 .
drwxr-xr-x steve.briggs staff  96 B  Thu May  7 19:59:38 2026 ..


Perfect! Now I have comprehensive understanding. Let me compile the findings:

## PXL Components Library Overview

**Tech Stack:**
- Angular 21.0.4 with standalone components and modules
- Styling: SCSS with Tailwind CSS 4.1.17 (integrated)
- Material Design via Angular Material 21.0.3
- Kendo UI components (21.2.0) for advanced widgets
- Storybook 10.1.6 for documentation with Figma integration
- Testing: Playwright for E2E tests, linting with ESLint 9.39.1

**Component Location:**
Components defined in `/projects/pxl-components/src/lib/components/` with 47 components total.

**Available UI Components (47 total):**
Alert, Animation, Breadcrumbs, Cards, Chart, Chip-Filter, Chips, Code-Highlight, Copy-to-Clipboard, Date-Range-Filter, Drawer, Empty-State, Expand-Region, Form-Field, Highlight, Icon, Image, Information-Label, Inline-Date-Range, Layout, Logo, Logo-Loader, Page-Header, Popover, Progress, Search-Input, Section-Header, Selectable-Card, Skeleton-Loader, Skip-Link, Stacked-Text-Display, Status-Bar, Status-Indicator, Step-Summary, Stepper-Icons, Stepper-Actions, Tooltip, Typography, Vertical-Nav, Vertical-Nav-Dropdown, Vertical-Nav-Link, NGX-Scrollspy, Control-Value-Accessor (utility)

**Design Tokens & Theming:**
- CSS variables with light/dark mode support via `prefers-color-scheme` media queries
- Theme palette system: primary, accent, warn, secondary, tertiary, action, success, error, warning, info, brand variants, and 12 tag colors
- Sensitivity levels (high/medium/non/indeterminate/not-applicable) for specialized use cases
- Located in `/projects/pxl-components/src/lib/styles/` with organized subdirectories: variables, palettes, mixins, utilities, keyframes, overrides, icons

**Additional Exports:**
Services (link, status, vertical-nav, page, color), Pipes (highlight-text, safe, truncate), Directives (print-button, chip-action, queryparam-button, stepper-auto-focus, focus-container-watcher)

Prompt:
Explore the Angular component library at /Users/steve.briggs/projects/pxl-components. I need to understand:
1. What UI components are available (list them with brief descriptions)
2. What the overall tech stack is (framework, styling, etc.)
3. Where components are defined (e.g., src/lib or projects/)
4. Any design tokens, theming, or style conventions

Look at the package.json, angular.json, and the component source files. Focus on what's available to use, not how it's built internally. Report in under 300 words.


Now let me look at the data schemas to understand what we're importing.


Bash

python3 -c "
import json

# Sample each file for structure
files = ['questions_answers_comments.json', 'articles.json', 'tags.json', 'users.json', 'user_groups.json']
for f in files:
    with open(f'/Users/steve.briggs/projects/heapoverflow/data/{f}') as fp:
        data = json.load(fp)
    print(f'=== {f} ===')
    if isinstance(data, list):
        print(f'Array of {len(data)} items')
        if data:
            print('First item keys:', list(data[0].keys()) if isinstance(data[0], dict) else type(data[0]))
            # Show first item structure
            import json as j
            print(j.dumps(data[0], indent=2)[:800])
    elif isinstance(data, dict):
        print('Object keys:', list(data.keys()))
        print(json.dumps(data, indent=2)[:800])
    print()
"

Sample each data file to understand schemas


=== questions_answers_comments.json ===
Array of 401 items
First item keys: ['tags', 'answers', 'owner', 'comment_count', 'is_answered', 'view_count', 'favorite_count', 'down_vote_count', 'up_vote_count', 'accepted_answer_id', 'answer_count', 'score', 'last_activity_date', 'creation_date', 'question_id', 'share_link', 'body_markdown', 'link', 'title', 'body', 'is_deleted', 'is_obsolete']
{
  "tags": [
    "saas",
    "k8s",
    "sre"
  ],
  "answers": [
    {
      "owner": {
        "account_id": 27513216,
        "reputation": 525,
        "user_id": 68,
        "user_type": "registered",
        "profile_image": "https://i.stack.imgur.com/OVNBl.png?s=256&g=1",
        "display_name": "Haris Khan",
        "link": "https://stackoverflowteams.com/c/immuta-product-engineering/users/68/haris-khan"
      },
      "comment_count": 0,
      "down_vote_count": 0,
      "up_vote_count": 0,
      "is_accepted": true,
      "score": 0,
      "last_activity_date": 1776284120,
      "creation_date": 1776284120,
      "answer_id": 852,
      "question_id": 851,
      "share_link": "https://stackoverflowteams.com/c/immuta-product-engineering/a/852/38",
      "body_markdown": "In Retoo

=== articles.json ===
Array of 2 items
First item keys: ['tags', 'owner', 'comment_count', 'view_count', 'score', 'last_activity_date', 'creation_date', 'article_id', 'article_type', 'body_markdown', 'link', 'title', 'body']
{
  "tags": [
    "core-policy"
  ],
  "owner": {
    "account_id": 24051275,
    "reputation": 900,
    "user_id": 25,
    "user_type": "registered",
    "profile_image": "https://lh3.googleusercontent.com/a-/AOh14GhBoShjsjd-0iAC-XuOkjtveg-MCJGQIrojMjNkKQ=k-s256",
    "display_name": "Jeff Hastings",
    "link": "https://stackoverflowteams.com/c/immuta-product-engineering/users/25/jeff-hastings"
  },
  "comment_count": 0,
  "view_count": 15,
  "score": 1,
  "last_activity_date": 1737142392,
  "creation_date": 1737142392,
  "article_id": 759,
  "article_type": "knowledge-article",
  "body_markdown": "## Audience\r\n\r\nThis article is intended for use by the on-call engineers from the core-policy squad. It contains guidance on how to respond when there is a datadog notification about error

=== tags.json ===
Array of 117 items
First item keys: ['synonyms', 'last_activity_date', 'has_synonyms', 'is_moderator_only', 'is_required', 'count', 'name', 'description', 'id', 'smes']
{
  "synonyms": [
    "bodata"
  ],
  "last_activity_date": 1740169363,
  "has_synonyms": true,
  "is_moderator_only": false,
  "is_required": false,
  "count": 96,
  "name": "bodata-development",
  "description": "",
  "id": 13,
  "smes": {
    "users": [
      {
        "id": 1,
        "accountId": 22343644,
        "name": "Floyd Hawkes",
        "avatarUrl": "https://stackoverflowteams.com/c/immuta-product-engineering/images/s/157b1d42-5f54-4eca-a970-75db0a8fad59.png?s=128&g=1",
        "webUrl": "https://stackoverflowteams.com/c/immuta-product-engineering/users/1/",
        "reputation": 450,
        "role": "Admin"
      },
      {
        "id": 63,
        "accountId": 27300549,
        "name": "Barry Hammen",
        "avatarUrl": "https://stackoverflowteams.com/c/immuta-product-en

=== users.json ===
Array of 107 items
First item keys: ['badge_counts', 'down_vote_count', 'up_vote_count', 'answer_count', 'question_count', 'account_id', 'is_employee', 'last_modified_date', 'last_access_date', 'reputation_change_year', 'reputation_change_quarter', 'reputation_change_month', 'reputation_change_week', 'reputation_change_day', 'reputation', 'creation_date', 'user_type', 'user_id', 'about_me', 'location', 'website_url', 'link', 'profile_image', 'display_name']
{
  "badge_counts": {
    "bronze": 11,
    "silver": 4,
    "gold": 0
  },
  "down_vote_count": 0,
  "up_vote_count": 45,
  "answer_count": 30,
  "question_count": 15,
  "account_id": 24051275,
  "is_employee": false,
  "last_modified_date": 1765893814,
  "last_access_date": 1766090578,
  "reputation_change_year": 0,
  "reputation_change_quarter": 0,
  "reputation_change_month": 0,
  "reputation_change_week": 0,
  "reputation_change_day": 0,
  "reputation": 900,
  "creation_date": 1643126611,
  "user_type": "registered",
  "user_id": 25,
  "about_me": "
I'm a software engineer at Immuta. I've worked on a lot of things from our core product, to the Immuta Helm Chart, to Kubernetes and Argo CD and database migrations, etc.
\n
Hit me up on the Immuta Slack, I'm @jeff.

=== user_groups.json ===
Array of 0 items


Good context gathered. The project is a blank slate (just data files), built on Angular 21 + the pxl-components library.

Key data summary:
- **401 questions** with nested answers/comments, votes, tags, markdown body
- **2 knowledge articles**
- **117 tags** with SME assignments
- **107 users** with reputation, badges
- **pxl-components**: 47 Angular components, Tailwind + Angular Material


Updated task #2 status


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)


afplay ~/.claude/sounds/mario/stop/stomp.wav 2>/dev/null || true


yes lets try it


<tool_use_error>Unknown skill: brainstorming/visual-companion</tool_use_error>

Error: Unknown skill: brainstorming/visual-companion


find /Users/steve.briggs/.claude/plugins -name "visual-companion*" 2>/dev/null

Find visual companion skill file


1	# Visual Companion Guide
2
3	Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
4
5	## When to Use
6
7	Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
8
9	**Use the browser** when the content itself is visual:
10
11	- **UI mockups** — wireframes, layouts, navigation structures, component designs
12	- **Architecture diagrams** — system components, data flow, relationship maps
13	- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
14	- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
15	- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
16
17	**Use the terminal** when the content is text or tabular:
18
19	- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
20	- **Conceptual A/B/C choices** — picking between approaches described in words
21	- **Tradeoff lists** — pros/cons, comparison tables
22	- **Technical decisions** — API design, data modeling, architectural approach selection
23	- **Clarifying questions** — anything where the answer is words, not a visual preference
24
25	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.
26
27	## How It Works
28
29	The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
30
31	**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.
32
33	## Starting a Session
34
35	```bash
36	# Start server with persistence (mockups saved to project)
37	scripts/start-server.sh --project-dir /path/to/project
38
39	# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
40	#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
41	#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
42	```
43
44	Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
45
46	**Finding connection info:** The server writes its startup JSON to `$STATE_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.
47
48	**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.
49
50	**Launching the server by platform:**
51
52	**Claude Code (macOS / Linux):**
53	```bash
54	# Default mode works — the script backgrounds the server itself
55	scripts/start-server.sh --project-dir /path/to/project
56	```
57
58	**Claude Code (Windows):**
59	```bash
60	# Windows auto-detects and uses foreground mode, which blocks the tool call.
61	# Use run_in_background: true on the Bash tool call so the server survives
62	# across conversation turns.
63	scripts/start-server.sh --project-dir /path/to/project
64	```
65	When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
66
67	**Codex:**
68	```bash
69	# Codex reaps background processes. The script auto-detects CODEX_CI and
70	# switches to foreground mode. Run it normally — no extra flags needed.
71	scripts/start-server.sh --project-dir /path/to/project
72	```
73
74	**Gemini CLI:**
75	```bash
76	# Use --foreground and set is_background: true on your shell tool call
77	# so the process survives across turns
78	scripts/start-server.sh --project-dir /path/to/project --foreground
79	```
80
81	**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.
82
83	If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
84
85	```bash
86	scripts/start-server.sh \
87	  --project-dir /path/to/project \
88	  --host 0.0.0.0 \
89	  --url-host localhost
90	```
91
92	Use `--url-host` to control what hostname is printed in the returned URL JSON.
93
94	## The Loop
95
96	1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
97	   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/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.
98	   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
99	   - **Never reuse filenames** — each screen gets a fresh file
100	   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
101	   - Server automatically serves the newest file
102
103	2. **Tell user what to expect and end your turn:**
104	   - Remind them of the URL (every step, not just first)
105	   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
106	   - 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."
107
108	3. **On your next turn** — after the user responds in the terminal:
109	   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
110	   - Merge with the user's terminal text to get the full picture
111	   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
112
113	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.
114
115	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:
116
117	   ```html
118	   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
119	   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
120	     <p class="subtitle">Continuing in terminal...</p>
121	   </div>
122	   ```
123
124	   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.
125
126	6. Repeat until done.
127
128	## Writing Content Fragments
129
130	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).
131
132	**Minimal example:**
133
134	```html
135	<h2>Which layout works better?</h2>
136	<p class="subtitle">Consider readability and visual hierarchy</p>
137
138	<div class="options">
139	  <div class="option" data-choice="a" onclick="toggleSelect(this)">
140	    <div class="letter">A</div>
141	    <div class="content">
142	      <h3>Single Column</h3>
143	      <p>Clean, focused reading experience</p>
144	    </div>
145	  </div>
146	  <div class="option" data-choice="b" onclick="toggleSelect(this)">
147	    <div class="letter">B</div>
148	    <div class="content">
149	      <h3>Two Column</h3>
150	      <p>Sidebar navigation with main content</p>
151	    </div>
152	  </div>
153	</div>
154	```
155
156	That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
157
158	## CSS Classes Available
159
160	The frame template provides these CSS classes for your content:
161
162	### Options (A/B/C choices)
163
164	```html
165	<div class="options">
166	  <div class="option" data-choice="a" onclick="toggleSelect(this)">
167	    <div class="letter">A</div>
168	    <div class="content">
169	      <h3>Title</h3>
170	      <p>Description</p>
171	    </div>
172	  </div>
173	</div>
174	```
175
176	**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.
177
178	```html
179	<div class="options" data-multiselect>
180	  <!-- same option markup — users can select/deselect multiple -->
181	</div>
182	```
183
184	### Cards (visual designs)
185
186	```html
187	<div class="cards">
188	  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
189	    <div class="card-image"><!-- mockup content --></div>
190	    <div class="card-body">
191	      <h3>Name</h3>
192	      <p>Description</p>
193	    </div>
194	  </div>
195	</div>
196	```
197
198	### Mockup container
199
200	```html
201	<div class="mockup">
202	  <div class="mockup-header">Preview: Dashboard Layout</div>
203	  <div class="mockup-body"><!-- your mockup HTML --></div>
204	</div>
205	```
206
207	### Split view (side-by-side)
208
209	```html
210	<div class="split">
211	  <div class="mockup"><!-- left --></div>
212	  <div class="mockup"><!-- right --></div>
213	</div>
214	```
215
216	### Pros/Cons
217
218	```html
219	<div class="pros-cons">
220	  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
221	  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
222	</div>
223	```
224
225	### Mock elements (wireframe building blocks)
226
227	```html
228	<div class="mock-nav">Logo | Home | About | Contact</div>
229	<div style="display: flex;">
230	  <div class="mock-sidebar">Navigation</div>
231	  <div class="mock-content">Main content area</div>
232	</div>
233	<button class="mock-button">Action Button</button>
234	<input class="mock-input" placeholder="Input field">
235	<div class="placeholder">Placeholder area</div>
236	```
237
238	### Typography and sections
239
240	- `h2` — page title
241	- `h3` — section heading
242	- `.subtitle` — secondary text below title
243	- `.section` — content block with bottom margin
244	- `.label` — small uppercase label text
245
246	## Browser Events Format
247
248	When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
249
250	```jsonl
251	{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
252	{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
253	{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
254	```
255
256	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.
257
258	If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
259
260	## Design Tips
261
262	- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
263	- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
264	- **Iterate before advancing** — if feedback changes current screen, write a new version
265	- **2-4 options max** per screen
266	- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
267	- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
268
269	## File Naming
270
271	- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
272	- Never reuse filenames — each screen must be a new file
273	- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
274	- Server serves newest file by modification time
275
276	## Cleaning Up
277
278	```bash
279	scripts/stop-server.sh $SESSION_DIR
280	```
281
282	If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
283
284	## Reference
285
286	- Frame template (CSS reference): `scripts/frame-template.html`
287	- Helper script (client-side): `scripts/helper.js`
288

# 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 to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.

**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/content",
#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
```

Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.

**Finding connection info:** The server writes its startup JSON to `$STATE_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 (macOS / Linux):**
```bash
# Default mode works — the script backgrounds the server itself
scripts/start-server.sh --project-dir /path/to/project
```

**Claude Code (Windows):**
```bash
# Windows auto-detects and uses foreground mode, which blocks the tool call.
# Use run_in_background: true on the Bash tool call so the server survives
# across conversation turns.
scripts/start-server.sh --project-dir /path/to/project
```
When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.

**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 `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/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 `$STATE_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; `state_dir/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 `$STATE_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 `$STATE_DIR/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 $SESSION_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`


find /Users/steve.briggs/.claude/plugins/cache/claude-plugins-official/superpowers/5.1.0 -name "start-server.sh" 2>/dev/null

Find start-server.sh script path


Start the visual companion server


Updated task #3 status


Server is running at **http://localhost:50109** — go ahead and open that in your browser.

Now, first clarifying question: this data export contains 401 questions, users, tags, etc. — but is this app going to be **read-only** (browsing the imported data), or do you want users to be able to **post new questions, answers, and comments**?


users should be able to post new questions, answers and comments


Got it — full CRUD. Next question: for the backend, are you thinking a **Go API** (fits your preferences) + Angular frontend as separate services, or something else like a single deployable binary that serves the Angular app too?


i would like to use a Go API and the angular front end and serve it as a single deployable binary


Love it — Go binary with embedded Angular assets. Next question: how should users authenticate? Since this is an internal tool, are you thinking something like **SSO/OIDC** (e.g., Google, Okta), **simple username/password**, or no auth at all (trust the network)?


for authentication I would like to use oauth via okta but for testing we can have a static user


Okta OAuth with a static test user fallback — nice. Next question: for data storage, since this is a single binary, are you thinking **SQLite** (embedded, zero-ops, perfect for a single binary), or a separate **PostgreSQL** instance?


I would like to use PostgreSQL but for local development we should have a bootstrap that spins up a local (in docker) postgres instance and sets it up for use


PostgreSQL + Docker bootstrap for local dev — perfect. Last scoping question: the data has reputation, badges, votes, accepted answers, tags with SMEs — do you want to **replicate the full StackOverflow reputation/badge system** in v1, or keep it simpler (voting works, but no badge earning or reputation tracking for new activity)?


lets keep it simpler for now but keep in mind that I do want to add badge earning and reputation (and import it from the users.json file) at a later time


That's a sensible call — import the existing reputation/badges, design the schema to support earning them later, but don't build the earning logic in v1.

I have enough to propose approaches now. Let me move to task 4.


Updated task #4 status


Here are three approaches for the overall repo/architecture structure:

---

**Option A — Go-first monorepo (Recommended)**
Go module at root, Angular app in `ui/`. A single `Makefile` runs everything: `make dev` starts Docker Postgres + Go API + `ng serve` with a proxy config pointing `/api` at Go. `make build` compiles Angular first, then embeds `ui/dist/` into the Go binary with `//go:embed`. Clean Go conventions, minimal tooling overhead.

**Option B — Separate `frontend/` and `backend/` directories**
Cleanest conceptual separation — Go in `backend/`, Angular in `frontend/`. Slightly more awkward because Go conventions want the module at the repo root, so the build script needs a `cd backend && go build` step. Doesn't save you anything and adds friction.

**Option C — Angular-first (Angular at root, Go API in `api/`)**
Since you already have a blank project dir, you could scaffold Angular at the root and put Go in `api/`. Mirrors the structure of some full-stack JS projects but fights Go tooling — `go.mod` inside a subdirectory means every Go command needs `-C api/` or a `cd`. Not worth it.

---

**My recommendation is Option A.** Go conventions are natural here, the build is a simple two-step (build Angular → embed into Go), and dev workflow is ergonomic. The Angular app is a consumer of `pxl-components` so it needs its own project scaffold regardless — `ui/` is the obvious home for it.

Does Option A work for you, or do you have a preference?


option A


Option A it is. Let me present the design in sections — starting with the overall architecture.


Updated task #5 status


Write

Architecture Overview

Section 1 of 4 — does this structure look right?

Repo Structure

heapoverflow/

├── cmd/server/main.go

├── internal/

│   ├── api/        ← REST handlers

│   ├── auth/       ← Okta OIDC + static user

│   ├── store/      ← DB queries (pgx)

│   └── importer/   ← JSON import logic

├── migrations/     ← SQL migration files

├── ui/             ← Angular app (uses pxl-components)

├── scripts/        ← dev bootstrap (Docker postgres)

├── Makefile

└── go.mod

Runtime Architecture

BROWSER

Angular SPA

pxl-components

HTTP

⟷

SINGLE BINARY

Go Server

/api/v1/* → REST handlers

/* → embedded Angular

pgx

⟷

DATABASE

PostgreSQL

Docker (dev)

Managed (prod)

OIDC

⟷

AUTH

Okta

+ static user

(dev only)

Key Workflows

MAKE DEV

          1. scripts/bootstrap.sh — spins up Docker postgres, runs migrations, seeds with JSON data

          2. go run ./cmd/server — API on :8080

          3. ng serve — Angular on :4200, proxies /api → :8080

MAKE BUILD

          1. ng build --configuration production

          2. go build embeds ui/dist/**

          3. Single binary: ./heapoverflow

          4. Reads config from env vars


File created successfully at: /Users/steve.briggs/projects/heapoverflow/.superpowers/brainstorm/61545-1778198706/content/architecture.html (file state is current in your context — no need to Read it back)

Architecture Overview

Section 1 of 4 — does this structure look right?

Repo Structure

heapoverflow/

├── cmd/server/main.go

├── internal/

│   ├── api/        ← REST handlers

│   ├── auth/       ← Okta OIDC + static user

│   ├── store/      ← DB queries (pgx)

│   └── importer/   ← JSON import logic

├── migrations/     ← SQL migration files

├── ui/             ← Angular app (uses pxl-components)

├── scripts/        ← dev bootstrap (Docker postgres)

├── Makefile

└── go.mod

Runtime Architecture

BROWSER

Angular SPA

pxl-components

HTTP

⟷

SINGLE BINARY

Go Server

/api/v1/* → REST handlers

/* → embedded Angular

pgx

⟷

DATABASE

PostgreSQL

Docker (dev)

Managed (prod)

OIDC

⟷

AUTH

Okta

+ static user

(dev only)

Key Workflows

MAKE DEV

          1. scripts/bootstrap.sh — spins up Docker postgres, runs migrations, seeds with JSON data

          2. go run ./cmd/server — API on :8080

          3. ng serve — Angular on :4200, proxies /api → :8080

MAKE BUILD

          1. ng build --configuration production

          2. go build embeds ui/dist/**

          3. Single binary: ./heapoverflow

          4. Reads config from env vars


Take a look at **http://localhost:50109** — showing the repo structure, runtime architecture, and the `make dev` / `make build` workflows.

Does this overall structure look right before we move on to the data model?


yes this looks right


Now let me show you the data model.


Data Model

Section 2 of 4 — PostgreSQL schema. Designed to import existing data and support future reputation/badge earning.

USERS

id SERIAL PK

user_id INT UNIQUE ← SO import

account_id INT UNIQUE

okta_id TEXT UNIQUE

display_name TEXT

email TEXT UNIQUE

profile_image TEXT

about_me TEXT

reputation INT

badge_bronze INT

badge_silver INT

badge_gold INT

↑ imported; earning logic in v2

is_employee BOOL

created_at TIMESTAMPTZ

last_access_at TIMESTAMPTZ

QUESTIONS

id SERIAL PK

legacy_id INT UNIQUE ← SO id

user_id INT FK→users

title TEXT

body_markdown TEXT

body_html TEXT

is_answered BOOL

is_deleted BOOL

is_obsolete BOOL

view_count INT

score INT

up_vote_count INT

down_vote_count INT

accepted_answer_id INT FK→answers

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

ANSWERS

id SERIAL PK

legacy_id INT UNIQUE

question_id INT FK→questions

user_id INT FK→users

body_markdown TEXT

body_html TEXT

is_accepted BOOL

score INT

up_vote_count INT

down_vote_count INT

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

TAGS

id SERIAL PK

legacy_id INT UNIQUE

name TEXT UNIQUE

description TEXT

count INT

is_moderator_only BOOL

is_required BOOL

JUNCTION TABLES

question_tags

question_id, tag_id

tag_synonyms

tag_id, synonym TEXT

tag_smes

tag_id, user_id

COMMENTS

id SERIAL PK

user_id INT FK→users

post_id INT (polymorphic)

post_type TEXT 'question'|'answer'

body_markdown TEXT

created_at TIMESTAMPTZ

VOTES

id SERIAL PK

user_id INT FK→users

post_id INT (polymorphic)

post_type TEXT 'question'|'answer'

vote_type SMALLINT 1 or -1

created_at TIMESTAMPTZ

UNIQUE(post_id, post_type, user_id)

tracks new votes; imported counts cached on posts

ARTICLES

id SERIAL PK

legacy_id INT UNIQUE

user_id INT FK→users

title TEXT

body_markdown TEXT

body_html TEXT

article_type TEXT

view_count INT

score INT

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

+ article_tags junction

Import Strategy

      make import runs go run ./cmd/importer which loads all 5 JSON files in dependency order:
      users → tags → questions → answers → comments → articles.
      Existing records are upserted by legacy_id so the import is idempotent.
      Reputation, badge counts, and cached vote counts are imported as-is from users.json.


File created successfully at: /Users/steve.briggs/projects/heapoverflow/.superpowers/brainstorm/61545-1778198706/content/data-model.html (file state is current in your context — no need to Read it back)

Data Model

Section 2 of 4 — PostgreSQL schema. Designed to import existing data and support future reputation/badge earning.

USERS

id SERIAL PK

user_id INT UNIQUE ← SO import

account_id INT UNIQUE

okta_id TEXT UNIQUE

display_name TEXT

email TEXT UNIQUE

profile_image TEXT

about_me TEXT

reputation INT

badge_bronze INT

badge_silver INT

badge_gold INT

↑ imported; earning logic in v2

is_employee BOOL

created_at TIMESTAMPTZ

last_access_at TIMESTAMPTZ

QUESTIONS

id SERIAL PK

legacy_id INT UNIQUE ← SO id

user_id INT FK→users

title TEXT

body_markdown TEXT

body_html TEXT

is_answered BOOL

is_deleted BOOL

is_obsolete BOOL

view_count INT

score INT

up_vote_count INT

down_vote_count INT

accepted_answer_id INT FK→answers

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

ANSWERS

id SERIAL PK

legacy_id INT UNIQUE

question_id INT FK→questions

user_id INT FK→users

body_markdown TEXT

body_html TEXT

is_accepted BOOL

score INT

up_vote_count INT

down_vote_count INT

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

TAGS

id SERIAL PK

legacy_id INT UNIQUE

name TEXT UNIQUE

description TEXT

count INT

is_moderator_only BOOL

is_required BOOL

JUNCTION TABLES

question_tags

question_id, tag_id

tag_synonyms

tag_id, synonym TEXT

tag_smes

tag_id, user_id

COMMENTS

id SERIAL PK

user_id INT FK→users

post_id INT (polymorphic)

post_type TEXT 'question'|'answer'

body_markdown TEXT

created_at TIMESTAMPTZ

VOTES

id SERIAL PK

user_id INT FK→users

post_id INT (polymorphic)

post_type TEXT 'question'|'answer'

vote_type SMALLINT 1 or -1

created_at TIMESTAMPTZ

UNIQUE(post_id, post_type, user_id)

tracks new votes; imported counts cached on posts

ARTICLES

id SERIAL PK

legacy_id INT UNIQUE

user_id INT FK→users

title TEXT

body_markdown TEXT

body_html TEXT

article_type TEXT

view_count INT

score INT

created_at TIMESTAMPTZ

updated_at TIMESTAMPTZ

+ article_tags junction

Import Strategy

      make import runs go run ./cmd/importer which loads all 5 JSON files in dependency order:
      users → tags → questions → answers → comments → articles.
      Existing records are upserted by legacy_id so the import is idempotent.
      Reputation, badge counts, and cached vote counts are imported as-is from users.json.


Check **http://localhost:50109** — showing the full database schema and import strategy.

A couple of design notes worth calling out:
- **Votes** are tracked individually in a `votes` table for new activity; imported vote counts are cached as denormalized columns on questions/answers (since the export only gives us totals, not individual votes)
- **Reputation/badges** are imported from `users.json` as static values; the schema is ready for v2 earning logic without changes
- **Comments** use a polymorphic `post_type` column so one table covers both question and answer comments

Does the data model look right?


Now let me show the API and frontend routing.


API & Frontend Routes

Section 3 of 4 — REST endpoints and Angular page structure

REST API  base: /api/v1

AUTH

GET  /auth/login → redirect to Okta

GET  /auth/callback → exchange code, set session

POST /auth/logout

GET  /auth/me → current user

QUESTIONS

GET  /questions ?page &sort &tag &q

POST /questions

GET  /questions/:id

PUT  /questions/:id

DELETE /questions/:id

POST /questions/:id/vote

ANSWERS

POST /questions/:id/answers

PUT  /answers/:id

DELETE /answers/:id

POST /answers/:id/vote

POST /answers/:id/accept

COMMENTS

POST /questions/:id/comments

POST /answers/:id/comments

DELETE /comments/:id

TAGS

GET  /tags ?q (search)

GET  /tags/:name → tag + SMEs

USERS

GET  /users/:id

PUT  /users/me

ARTICLES

GET  /articles

GET  /articles/:id

SEARCH

GET  /search ?q → questions + articles

Angular Routes

PUBLIC

/login → LoginComponent

/auth/callback → AuthCallbackComponent

AUTHENTICATED (AuthGuard)

/ → redirect to /questions

/questions → QuestionListComponent

sort: newest | active | votes | unanswered

filter by tag, full-text search

/questions/ask → AskQuestionComponent

/questions/:id → QuestionDetailComponent

answers, comments, voting, accept

/tags → TagListComponent

/tags/:name → TagDetailComponent

SMEs, questions with this tag

/articles → ArticleListComponent

/articles/:id → ArticleDetailComponent

/users/:id → UserProfileComponent

reputation, badges, activity

/search → SearchResultsComponent

Auth Flow

OKTA (production)

1. Angular AuthGuard → redirect to /api/v1/auth/login

2. Go redirects → Okta authorization URL

3. Okta callback → /api/v1/auth/callback

4. Go exchanges code, looks up or creates user, sets HTTP-only session cookie

5. Redirect to Angular /auth/callback → Angular reads /auth/me → proceed

STATIC USER (dev / testing)

Enabled by env var AUTH_MODE=static

Login page shows a "Dev Login" button

Go sets session as a pre-configured test user

No Okta credentials required locally

Static mode disabled if OKTA_* env vars present

Search Strategy

      Full-text search powered by PostgreSQL's built-in tsvector — no external service needed.
      A search_vector column on questions and articles is maintained via a trigger,
      indexed with GIN. The GET /search?q= endpoint queries both tables and returns a ranked, merged list.
      Good enough for 400+ questions without Elasticsearch overhead.


File created successfully at: /Users/steve.briggs/projects/heapoverflow/.superpowers/brainstorm/61545-1778198706/content/api-frontend.html (file state is current in your context — no need to Read it back)

API & Frontend Routes

Section 3 of 4 — REST endpoints and Angular page structure

REST API  base: /api/v1

AUTH

GET  /auth/login → redirect to Okta

GET  /auth/callback → exchange code, set session

POST /auth/logout

GET  /auth/me → current user

QUESTIONS

GET  /questions ?page &sort &tag &q

POST /questions

GET  /questions/:id

PUT  /questions/:id

DELETE /questions/:id

POST /questions/:id/vote

ANSWERS

POST /questions/:id/answers

PUT  /answers/:id

DELETE /answers/:id

POST /answers/:id/vote

POST /answers/:id/accept

COMMENTS

POST /questions/:id/comments

POST /answers/:id/comments

DELETE /comments/:id

TAGS

GET  /tags ?q (search)

GET  /tags/:name → tag + SMEs

USERS

GET  /users/:id

PUT  /users/me

ARTICLES

GET  /articles

GET  /articles/:id

SEARCH

GET  /search ?q → questions + articles

Angular Routes

PUBLIC

/login → LoginComponent

/auth/callback → AuthCallbackComponent

AUTHENTICATED (AuthGuard)

/ → redirect to /questions

/questions → QuestionListComponent

sort: newest | active | votes | unanswered

filter by tag, full-text search

/questions/ask → AskQuestionComponent

/questions/:id → QuestionDetailComponent

answers, comments, voting, accept

/tags → TagListComponent

/tags/:name → TagDetailComponent

SMEs, questions with this tag

/articles → ArticleListComponent

/articles/:id → ArticleDetailComponent

/users/:id → UserProfileComponent

reputation, badges, activity

/search → SearchResultsComponent

Auth Flow

OKTA (production)

1. Angular AuthGuard → redirect to /api/v1/auth/login

2. Go redirects → Okta authorization URL

3. Okta callback → /api/v1/auth/callback

4. Go exchanges code, looks up or creates user, sets HTTP-only session cookie

5. Redirect to Angular /auth/callback → Angular reads /auth/me → proceed

STATIC USER (dev / testing)

Enabled by env var AUTH_MODE=static

Login page shows a "Dev Login" button

Go sets session as a pre-configured test user

No Okta credentials required locally

Static mode disabled if OKTA_* env vars present

Search Strategy

      Full-text search powered by PostgreSQL's built-in tsvector — no external service needed.
      A search_vector column on questions and articles is maintained via a trigger,
      indexed with GIN. The GET /search?q= endpoint queries both tables and returns a ranked, merged list.
      Good enough for 400+ questions without Elasticsearch overhead.


Check **http://localhost:50109** — showing the full REST API, Angular routes, auth flow, and search strategy.

A few things worth noting:
- **Session auth** uses HTTP-only cookies (not JWTs in localStorage) — safer against XSS
- **Static dev user** is toggled by `AUTH_MODE=static` env var, automatically disabled when Okta env vars are present
- **Full-text search** uses PostgreSQL `tsvector` with a GIN index — no Elasticsearch needed at this scale

Does the API and routing structure look right?


Building a StackOverflow for Teams clone with a Go API, Angular frontend using pxl-components, and PostgreSQL — all in a single deployable binary. Architecture, data model, and API design are approved; waiting for confirmation on the API and routing section before moving to the UI layout. (disable recaps in /config)


looks right to me


Last section — the UI layout. This is worth seeing visually.


UI Layout

Section 4 of 4 — page structure using pxl-components. Does this feel right?

Questions List (/questions)

⬡ HeapOverflow

🔍 Search...

👤 Steve

Questions

Tags

Articles

Users

All Questions

Ask Question

Newest

Active

Votes

Unanswered

12

votes

3

ans ✓

How do we handle k8s pod restarts in SRE runbooks?

                    k8s
                    sre

asked by Floyd H. · 2d ago

3

votes

0

ans

Best practices for bodata-development migrations?

                    bodata-development

asked by Barry H. · 5h ago

7

votes

1

ans ✓

SaaS deployment checklist for new regions?

                    saas

asked by Jeff H. · 1w ago

1

2

3

›

Question Detail (/questions/:id)

⬡ HeapOverflow

🔍 Search...

👤 Steve

Questions

Tags

Articles

Users

How do we handle k8s pod restarts in SRE runbooks?

              k8s
              sre
              asked by Floyd H. · 2d ago · 45 views

▲

12

▼

                We've been seeing issues with our SRE runbooks not properly accounting for pod restart scenarios...

2 comments

3 Answers

▲

8

▼

✓

                The key is to add a livenessProbe with appropriate thresholds...

answered by Haris K. · accepted ✓

Your Answer

Post Answer

pxl-components Mapping

Navigation

VerticalNav — sidebar

PageHeader — top bar

Breadcrumbs — question detail

SearchInput — global search

Content

Chips — sort tabs & tags

Cards — question rows

Alert — errors / notices

SkeletonLoader — loading state

Forms & Feedback

FormField — ask/answer forms

EmptyState — no results

StatusIndicator — answered badge

Tooltip — vote counts


File created successfully at: /Users/steve.briggs/projects/heapoverflow/.superpowers/brainstorm/61545-1778198706/content/ui-layout.html (file state is current in your context — no need to Read it back)

UI Layout

Section 4 of 4 — page structure using pxl-components. Does this feel right?

Questions List (/questions)

⬡ HeapOverflow

🔍 Search...

👤 Steve

Questions

Tags

Articles

Users

All Questions

Ask Question

Newest

Active

Votes

Unanswered

12

votes

3

ans ✓

How do we handle k8s pod restarts in SRE runbooks?

                    k8s
                    sre

asked by Floyd H. · 2d ago

3

votes

0

ans

Best practices for bodata-development migrations?

                    bodata-development

asked by Barry H. · 5h ago

7

votes

1

ans ✓

SaaS deployment checklist for new regions?

                    saas

asked by Jeff H. · 1w ago

1

2

3

›

Question Detail (/questions/:id)

⬡ HeapOverflow

🔍 Search...

👤 Steve

Questions

Tags

Articles

Users

How do we handle k8s pod restarts in SRE runbooks?

              k8s
              sre
              asked by Floyd H. · 2d ago · 45 views

▲

12

▼

                We've been seeing issues with our SRE runbooks not properly accounting for pod restart scenarios...

2 comments

3 Answers

▲

8

▼

✓

                The key is to add a livenessProbe with appropriate thresholds...

answered by Haris K. · accepted ✓

Your Answer

Post Answer

pxl-components Mapping

Navigation

VerticalNav — sidebar

PageHeader — top bar

Breadcrumbs — question detail

SearchInput — global search

Content

Chips — sort tabs & tags

Cards — question rows

Alert — errors / notices

SkeletonLoader — loading state

Forms & Feedback

FormField — ask/answer forms

EmptyState — no results

StatusIndicator — answered badge

Tooltip — vote counts


Explore project context

Check pxl-components library, data files, and any existing project structure

Offer visual companion

Offer the visual browser companion for UI mockups

Ask clarifying questions

One at a time, understand purpose, constraints, and success criteria

Propose 2-3 approaches

Present trade-offs and a recommendation

Present design

In sections scaled to complexity, get user approval after each section

Write design doc

Save to docs/superpowers/specs/YYYY-MM-DD-heapoverflow-design.md and commit

Spec self-review

Check for placeholders, contradictions, ambiguity, scope issues

User reviews written spec

Ask user to review spec file before proceeding

Transition to implementation

Invoke writing-plans skill to create implementation plan


Check **http://localhost:50109** — wireframes of the questions list and question detail pages, plus the pxl-components mapping.

The key design choices here:
- **Vertical nav** (pxl `VerticalNav`) for the sidebar — Questions, Tags, Articles, Users
- **Vote controls** are inline with the post body, accepted answer gets a green highlight
- **Chips** for sort tabs (Newest/Active/Votes/Unanswered) and tag filters
- Markdown body is pre-rendered to HTML at write time and stored as `body_html` — fast reads, no client-side rendering needed

Does this layout look right, or would you like to adjust anything?


this looks right


All four sections approved. Writing the design doc now.


Updated task #5 status


Updated task #6 status


Bash

Create specs directory


(Bash completed with no output)