/superpowers:brainstorming for the skills how hard would it be to add the marvin logo in ascii art or

Claude Code·Opus 4.7[1m]·

alishakawaguchi·5mo ago·1hr 18min·3 Checkpoints·12 file changes·+132·37.7K tokens

Base directory for this skill: /Users/alisha/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/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:

Explore project context — check files, docs, recent commits
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.
Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
Propose 2-3 approaches — with trade-offs and your recommendation
Present design — in sections scaled to their complexity, get user approval after each section
Write design doc — save to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and commit
Spec self-review — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
User reviews written spec — ask user to review the spec file before proceeding
Transition to implementation — invoke writing-plans skill to create implementation plan

Process Flow

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:

Placeholder scan: Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
Internal consistency: Do any sections contradict each other? Does the architecture match the feature descriptions?
Scope check: Is this focused enough for a single implementation plan, or does it need decomposition?
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

ARGUMENTS: for the skills how hard would it be to add the marvin logo in ascii art or '/var/folders/5g/w6qvhr890pxfz9sg1l0d5c0r0000gn/T/TemporaryItems/NSIRD_screencapture ui_9Yu67G/Screenshot 2026-04-17 at 10.36.37 AM.png' something to the response of these skills

5mo ago·45.9s

Pretty easy — skills are just markdown instructions, so you'd add a line like "Begin your response with this ASCII block:" followed by the art. Main tradeoffs: (1) it burns tokens on every invocation, (2) ASCII renders inconsistently across terminals/agents (Codex, Gemini, OpenCode may strip or reflow it), and (3) agents sometimes "forget" decorative instructions under load — so it'd be a soft convention, not a guarantee.

For the logo itself, ASCII is the portable choice (the screenshot is a little ninja-looking Marvin with two dot eyes — translates fine to ~5 lines of ASCII). Want me to go through proper brainstorming to nail down exactly where/how it appears (header vs. footer, all three skills vs. just one, fixed art vs. variant per skill), or is this already enough to decide?

Starting with the most foundational question — purpose shapes everything else (placement, frequency, styling).

Question 1 of ~4: What's the primary purpose of adding Marvin to these skill responses?

A. Branding / identification — make it visually obvious when a response was produced by an Entire-powered skill (vs. the agent's own reasoning). Logo appears on every skill invocation, prominently (likely top of response).
B. Delight / flourish — a small mascot signature as a sign-off, mostly for fun. Appears at bottom, low-key, maybe only on successful completion.
C. Wayfinding inside multi-agent workflows — help the user (or other agents in a handoff chain) recognize which skill fired. Placement tied to skill boundaries.
D. Something else — tell me what you have in mind.

Which is closest to what you want?

Got it — branding + delight. Those aren't in conflict: a well-placed mascot can be both identifiable and charming. But A leans "top, every time" while B leans "bottom, sometimes" — so placement is the next thing to pin down.

Question 2 of ~4: Where should Marvin appear?

A. Top header — Marvin ASCII block is the first thing in every skill response. Strongest branding, hardest to miss. Cost: every response starts with ~5 lines of ASCII before the actual content.
B. Bottom sign-off — Marvin appears at the end, like a signature. Softer, doesn't delay the useful content. Cost: easier for the agent to forget/drop under load.
C. Both — tiny marker at top, full ASCII at bottom — e.g. a one-line ◼ Marvin header for identification, full ASCII sign-off at the end. Gets both jobs done without doubling the ASCII payload.
D. Inline, tied to a moment — e.g. only at the very end of a successful handoff, or next to the summary header.

Which fits best? (My lean is C — it splits the two jobs cleanly, and the tiny top marker is cheap enough to survive even if the full sign-off gets dropped.)

Top header it is. Next up: how big and detailed should Marvin be? This is the main knob on token cost and visual impact — every skill invocation eats this on stdout.

Question 3 of ~4: What size/detail level?

A. Tiny one-liner — e.g. ◼◼ Marvin · Entire or ( •_• ) Marvin — one line, ~20-30 chars. Unobtrusive, hardest to mess up, lowest token cost.
B. Small block (~3-5 lines) — a compact stylized version of the ninja mascot, roughly 5-15 chars wide. Still readable quickly, survives narrow terminals.
C. Medium block (~6-10 lines) — more detailed ASCII with some shading/character, looks more like a "proper logo". Starts to dominate the first screen.
D. Figlet-style wordmark — big "MARVIN" or "ENTIRE" text in block letters. Pure branding, no mascot.

My lean is B — a small 3-5 line block keeps the mascot recognizable but doesn't push real content below the fold. A (one-liner) is safer but loses the personality you picked B for. Which way?

Got it — scrap the mascot. Just an "Entire [Skill Name]:" header line prepended to each skill's response. So:

search → starts with Entire Search: then the results summary
explain → starts with Entire Explain: then the traced intent
session-handoff → starts with Entire Session Handoff: then the compaction summary

Question 4: exact format?

A. Inline header on its own line — Entire Session Handoff: followed by a newline, then the content. Clean, minimal.
B. Markdown heading — ## Entire Session Handoff as an H2. Renders prominently in markdown-aware UIs, looks like "just text" in plain terminals.
C. Prefixed to the first sentence — Entire Session Handoff: Picking up the Codex session from this morning... — runs into the content, reads like a single statement.

My lean: A — it's the most reliable instruction for the agent to follow and works equally well across Claude Code, Codex, Gemini, OpenCode. Which one?

Skipping the "2-3 approaches" round — the design space collapsed cleanly once you picked format A. Moving to the design.

Design: "Entire [Skill Name]:" header on skill responses

1. What changes

Each of the three SKILL.md files gets a short response-format instruction near the top telling the agent to begin its response with a fixed header line, followed by a blank line, followed by the actual content.

Exact headers:

plugins/entire/skills/search/SKILL.md → Entire Search:
plugins/entire/skills/explain/SKILL.md → Entire Explain:
plugins/entire/skills/session-handoff/SKILL.md → Entire Session Handoff:

Does that look right so far?

3. Edge cases and scope of the header

Three things worth pinning down now so the writing-plans step doesn't have to guess:

Error / early-exit paths — skills already have "stop and tell the user" branches (e.g. "Entire CLI is required but not installed"). The header applies to these too. Reason: if the purpose is branding, users should still see it when the skill fails — otherwise they can't tell which layer threw the error.
Follow-up turns in the same invocation — only the first response of the skill invocation gets the header. Subsequent agent replies during the same task (e.g. after the user answers a clarifying question) don't re-print it. Reason: the header marks the entry point of the skill, not every agent turn.
session-handoff unanswered-question flow — the header still applies. The compaction summary gets printed under the header as normal, and the unanswered-question ask comes after the summary.

Agree with all three? Anything you'd tweak?

Updated:

✅ First response only
✅ No header on error / early-exit paths (so the header becomes a positive "the skill actually ran" signal — cleaner than I had it)
✅ session-handoff unanswered-question flow still gets the header (that path is a successful run, not an error)

4. Testing / verification

How we'll know it worked:

Manual check per skill: invoke each skill with a known-good input, confirm the response opens with the correct header.
Manual error check per skill: force an error path (e.g. run explain on an uncommitted file) and confirm the header is absent.
Cross-agent spot-check: since this repo ships to Claude Code, Codex, OpenCode, Cursor, and Gemini, at minimum try one invocation in two different agents to make sure the instruction is followed broadly. Skill instructions are plain markdown, so there's no agent-specific code to worry about — but agent behavior can still vary.

No automated tests — skill responses are non-deterministic model output, unit tests would be flaky. Good?

Base directory for this skill: /Users/alisha/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/writing-plans

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Announce at start: "I'm using the writing-plans skill to create the implementation plan."

Context: This should be run in a dedicated worktree (created by brainstorming skill).

Save plans to: docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

(User preferences for plan location override this default)

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If it wasn't, suggest breaking this into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created or modified and what each one is responsible for. This is where decomposition decisions get locked in.

Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.
You reason best about code you can hold in context at once, and your edits are more reliable when files are focused. Prefer smaller, focused files over large ones that do too much.
Files that change together should live together. Split by responsibility, not by technical layer.
In existing codebases, follow established patterns. If the codebase uses large files, don't unilaterally restructure - but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

This structure informs the task decomposition. Each task should produce self-contained changes that make sense independently.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

"Write the failing test" - step
"Run it to make sure it fails" - step
"Implement the minimal code to make the test pass" - step
"Run the tests and make sure they pass" - step
"Commit" - step

Plan Document Header

Every plan MUST start with this header:

Task Structure

No Placeholders

Every step must contain the actual content an engineer needs. These are plan failures — never write them:

"TBD", "TODO", "implement later", "fill in details"
"Add appropriate error handling" / "add validation" / "handle edge cases"
"Write tests for the above" (without actual test code)
"Similar to Task N" (repeat the code — the engineer may be reading tasks out of order)
Steps that describe what to do without showing how (code blocks required for code steps)
References to types, functions, or methods not defined in any task

Remember

Exact file paths always
Complete code in every step — if a step changes code, show the code
Exact commands with expected output
DRY, YAGNI, TDD, frequent commits

Self-Review

After writing the complete plan, look at the spec with fresh eyes and check the plan against it. This is a checklist you run yourself — not a subagent dispatch.

1. Spec coverage: Skim each section/requirement in the spec. Can you point to a task that implements it? List any gaps.

2. Placeholder scan: Search your plan for red flags — any of the patterns from the "No Placeholders" section above. Fix them.

3. Type consistency: Do the types, method signatures, and property names you used in later tasks match what you defined in earlier tasks? A function called clearLayers() in Task 3 but clearFullLayers() in Task 7 is a bug.

If you find issues, fix them inline. No need to re-review — just fix and move on. If you find a spec requirement with no task, add the task.

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/superpowers/plans/<filename>.md. Two execution options:

1. Subagent-Driven (recommended) - I dispatch a fresh subagent per task, review between tasks, fast iteration

2. Inline Execution - Execute tasks in this session using executing-plans, batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen:

REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
Fresh subagent per task + two-stage review

If Inline Execution chosen:

REQUIRED SUB-SKILL: Use superpowers:executing-plans
Batch execution with checkpoints for review

5mo ago·2m

Running the self-review against the spec.

Spec coverage: each spec section maps to a task — Tasks 1–3 cover the three skills with exact headers and the edge-case bullets (first response only, no header on errors, session-handoff unanswered-question still gets header); Task 4 covers the manual verification plan across happy path, error path, and cross-agent spot-check. ✅ Placeholder scan: no TBDs, no "similar to Task N" — each task carries its own full old_string/new_string blocks. ✅ Type consistency: Entire Search: / Entire Explain: / Entire Session Handoff: appear identically in every task and in the template. ## Response Format is the same section name throughout. ✅

No fixes needed.

Plan saved locally at docs/superpowers/plans/2026-04-17-entire-skill-response-header.md (uncommitted — docs/ is gitignored in this repo, same as the spec).

Plan complete. Two execution options:

1. Subagent-Driven (recommended) — I dispatch a fresh subagent per task, review between tasks, fast iteration.

2. Inline Execution — I execute the tasks in this session using executing-plans, with checkpoints for review.

Which approach?

Base directory for this skill: /Users/alisha/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/subagent-driven-development

Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

Why subagents: You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

Core principle: Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

When to Use

vs. Executing Plans (parallel session):

Same session (no context switch)
Fresh subagent per task (no context pollution)
Two-stage review after each task: spec compliance first, then code quality
Faster iteration (no human-in-loop between tasks)

The Process

Model Selection

Use the least powerful model that can handle each role to conserve cost and increase speed.

Mechanical implementation tasks (isolated functions, clear specs, 1-2 files): use a fast, cheap model. Most implementation tasks are mechanical when the plan is well-specified.

Integration and judgment tasks (multi-file coordination, pattern matching, debugging): use a standard model.

Architecture, design, and review tasks: use the most capable available model.

Task complexity signals:

Touches 1-2 files with a complete spec → cheap model
Touches multiple files with integration concerns → standard model
Requires design judgment or broad codebase understanding → most capable model

Handling Implementer Status

Implementer subagents report one of four statuses. Handle each appropriately:

DONE: Proceed to spec compliance review.

DONE_WITH_CONCERNS: The implementer completed the work but flagged doubts. Read the concerns before proceeding. If the concerns are about correctness or scope, address them before review. If they're observations (e.g., "this file is getting large"), note them and proceed to review.

NEEDS_CONTEXT: The implementer needs information that wasn't provided. Provide the missing context and re-dispatch.

BLOCKED: The implementer cannot complete the task. Assess the blocker:

If it's a context problem, provide more context and re-dispatch with the same model
If the task requires more reasoning, re-dispatch with a more capable model
If the task is too large, break it into smaller pieces
If the plan itself is wrong, escalate to the human

Never ignore an escalation or force the same model to retry without changes. If the implementer said it's stuck, something needs to change.

Prompt Templates

./implementer-prompt.md - Dispatch implementer subagent
./spec-reviewer-prompt.md - Dispatch spec compliance reviewer subagent
./code-quality-reviewer-prompt.md - Dispatch code quality reviewer subagent

Example Workflow

Advantages

vs. Manual execution:

Subagents follow TDD naturally
Fresh context per task (no confusion)
Parallel-safe (subagents don't interfere)
Subagent can ask questions (before AND during work)

vs. Executing Plans:

Same session (no handoff)
Continuous progress (no waiting)
Review checkpoints automatic

Efficiency gains:

No file reading overhead (controller provides full text)
Controller curates exactly what context is needed
Subagent gets complete information upfront
Questions surfaced before work begins (not after)

Quality gates:

Self-review catches issues before handoff
Two-stage review: spec compliance, then code quality
Review loops ensure fixes actually work
Spec compliance prevents over/under-building
Code quality ensures implementation is well-built

Cost:

More subagent invocations (implementer + 2 reviewers per task)
Controller does more prep work (extracting all tasks upfront)
Review loops add iterations
But catches issues early (cheaper than debugging later)

Red Flags

Never:

Start implementation on main/master branch without explicit user consent
Skip reviews (spec compliance OR code quality)
Proceed with unfixed issues
Dispatch multiple implementation subagents in parallel (conflicts)
Make subagent read plan file (provide full text instead)
Skip scene-setting context (subagent needs to understand where task fits)
Ignore subagent questions (answer before letting them proceed)
Accept "close enough" on spec compliance (spec reviewer found issues = not done)
Skip review loops (reviewer found issues = implementer fixes = review again)
Let implementer self-review replace actual review (both are needed)
Start code quality review before spec compliance is ✅ (wrong order)
Move to next task while either review has open issues

If subagent asks questions:

Answer clearly and completely
Provide additional context if needed
Don't rush them into implementation

If reviewer finds issues:

Implementer (same subagent) fixes them
Reviewer reviews again
Repeat until approved
Don't skip the re-review

If subagent fails task:

Dispatch fix subagent with specific instructions
Don't try to fix manually (context pollution)

Integration

Required workflow skills:

superpowers:using-git-worktrees - REQUIRED: Set up isolated workspace before starting
superpowers:writing-plans - Creates the plan this skill executes
superpowers:requesting-code-review - Code review template for reviewer subagents
superpowers:finishing-a-development-branch - Complete development after all tasks

Subagents should use:

superpowers:test-driven-development - Subagents follow TDD for each task

Alternative workflow:

superpowers:executing-plans - Use for parallel session instead of same-session execution

5mo ago·18m

All implementation tasks complete and approved. Branch alisha/marvin has three focused commits:

Each SKILL.md now has a ## Response Format section telling the agent to begin the first successful response with Entire Search: / Entire Explain: / Entire Session Handoff: on its own line, and to omit the header on error or early-exit paths.

What's left

Task 4 — Manual verification (human-driven). This is the one step subagents can't do: it requires invoking the skills live in at least one agent (ideally two for the cross-agent spot-check) and confirming the first line of each response. The plan at docs/superpowers/plans/2026-04-17-entire-skill-response-header.md has the full 8-step checklist. Tip from the final reviewer: for the search error-path check, use a nonsense query like entire search "zzzzxxxxqqqq1234" to force the no-matches path (if you're logged in, the auth-required path won't fire).

Want me to dispatch superpowers:finishing-a-development-branch to help decide next steps (merge / PR / park), or are you taking it from here with the manual verification?

Brainstorming Ideas Into Designs

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

Checklist

Process Flow

The Process

After the Design

Key Principles

Visual Companion

Design: "Entire [Skill Name]:" header on skill responses

1. What changes

2. Where the instruction goes inside each SKILL.md

3. Edge cases and scope of the header

4. Testing / verification

Writing Plans

Overview

Scope Check

File Structure

Bite-Sized Task Granularity

Plan Document Header

Task Structure

No Placeholders

Remember

Self-Review

Execution Handoff

Subagent-Driven Development

When to Use

The Process

Model Selection

Handling Implementer Status

Prompt Templates

Example Workflow

Advantages

Red Flags

Integration

What's left