brainstorm-toolkit

Interactive brainstorming and feature ideation skill: clarifies the idea, explores codebase context, generates multiple approaches, evaluates tradeoffs, and writes an action plan to `plans/`. Use whenever the user says /brainstorm, mentions "brainstorm", "let's think through", "I have an idea", "what if we", "how should we approach", "let's explore", or wants to ideate on a feature or change before jumping into code. This is the conversational planning companion — for heavy autonomous multi-agent product research, use /brainstorm-team instead.

Launches a coordinated 6-agent team (4 researching in parallel, then synthesis and blueprints) to produce a complete product strategy document: competitive research, codebase mapping, UX critique, ranked feature list, and detailed implementation blueprints. Use when the user wants heavy autonomous product research or says "brainstorm team", "what should we build next", "competitive analysis", "product review", or invokes /brainstorm-team. For conversational ideation with the user in-session, use /brainstorm instead.

Turn a codebase into teaching material: audit docstring coverage, write why-focused docstrings, and generate a guided reading path (TOUR.md). Use whenever someone wants a codebase documented for humans, not an API reference — onboarding a new hire, "explain this codebase", "add docstrings", "help someone learn this repo", or when docs say WHAT but not WHY. Triggers on /code-tour, /docstrings, /codetour, /onboarding-docs. Unlike /repo-onboarding (contract files) and /repo-health (read-only sweep), this writes documentation into the source.

Launches a parallel fan-out of review agents to find dead code, dead docs, and dead plans, then removes them and runs the test suite before and after to verify zero regressions. THIS IS THE SKILL FOR "launch a few agents to review everything for dead code / anything no longer needed" — use it instead of hand-composing an ad-hoc agent fan-out. Use when the user says /dead-code-review, "what can be deleted", "what's no longer needed", "clean this up", "look for dead code", or asks to sweep the repo before a release or after a refactor.

Repair docstrings and comments that drifted from their code: stale or wrong claims, param/return mismatches, placeholder text, and pointers to plan files or tickets that rot. Deterministic checks run first; an LLM rewrites only the flagged ones, and you review the diff. Never commits. Use on /docstring-sync, "fix stale docstrings", "docstrings are out of date", or "clean up legacy comments".

Trace the claimed flow from a plan or task through the source code and report mismatches. This is a structured code-review pass formatted as a narrative execution trace — the goal is to surface "the plan said X but the code does Y" gaps that test suites and evals miss. Use during the /sdlc fix loop, after implementing a feature, or ad hoc when a plan and its implementation feel misaligned. Invoke via /flowsim or when the user says "trace the flow", "verify the plan matches", "walk through what actually happens".

Maintains a running log of project-specific "gotchas" — non-obvious pitfalls, traps, and hard-won lessons that have caused bugs or wasted time in this codebase. Use this skill proactively whenever writing or modifying code in any area where a prior gotcha has been recorded. Also use when the user invokes /gotcha to add a new entry or review existing ones. Consult the project's GOTCHAS.md before writing code in any area where a known pitfall exists.

Render a markdown plan file as a self-contained, shareable HTML page. Use it whenever the user says /plan-html, "render the plan", "make this plan viewable", "HTML version of the plan", or wants to send a plan to someone who won't read markdown, share a plan with a stakeholder, or hand off a roadmap. Composes with any plan — brainstorm output, SDLC plans, refactor docs, threat models. Output is throwaway: the .md remains canonical.

Read-only repo hygiene sweep: runs dead-code, tests, dependency audit, secret scan, and gotchas-currency in parallel, rolling findings into a single scored report. Use when the user says /repo-health, asks for a "hygiene check", "weekly sweep", "is this repo healthy", "what should I clean up", or before a release. Never modifies code — produces a report and a `.next-action` suggestion. Run after merges land, not mid-implementation. For a deep dead-code investigation use /dead-code-review; for PR-scoped review use /sdlc's Stage 5.

Inspect a repository and generate the cross-tool contract files this toolkit's skills rely on: AGENTS.md, TASKS.md, .claude/project.json, and GOTCHAS.md. Use when onboarding a new repo to the workflow toolkit, when the user says "set up this repo for the toolkit", "generate AGENTS.md", "create project.json", or asks how the codebase is laid out, or when /onboard, /discovery, /codelearn, or /init-toolkit is invoked.

Run the full SDLC pipeline on a plan file, task id, task range (e.g. "1-5"), or an ad-hoc description: sanity-check → implement → evals → fix → validate → flowsim, then hand off the validated changes in your working tree for you to commit. Never commits, branches, pushes, or opens a PR — no git writes at all. Use when you want full SDLC discipline on work you will review and commit yourself, e.g. onto an open PR's branch. Use /task instead for a single small TDD fix with no plan.

Show a quick readout of the current work queue: task counts by state, the active task, and the most recently completed task. Also surfaces any non-terminal pipeline runs (so a stalled /sdlc run can't hide). Reads TASKS.md and .claude/pipeline/ directly — no subagents, no dashboards. Invoke via /sdlc-status or when the user asks "what's left?", "current task?", "status". Read-only by default; `--prune-stale` and `--reconcile` are opt-in, confirm-gated cleanup of stale/orphaned pipeline envelopes.

Create a bounded, single-purpose task and execute it with TDD. Appends a row to TASKS.md, writes a task file at plans/tasks/task-N-<slug>.md, and runs a write-test → implement → verify loop. Use for small to medium items that are too concrete for /brainstorm and too small to justify the full /sdlc pipeline. Invoke via /task or when the user asks to "just do X", "quick fix", "small change", or names one concrete, bounded ask with no plan behind it.

Run all relevant tests, feature evals and log audits after code changes, in a Haiku sub-agent so raw output never lands in your context. Reads `.claude/project.json` for the project's commands and skips any step whose command is not configured. Use it after implementing a feature or fixing a bug, before marking work done, or whenever the user says /test-check, "run the tests", "did I break anything", "check the logs", or "is it green". `--loop` also fixes failing e2e tests instead of only reporting them.