diff --git a/README.md b/README.md index 5ab45ab..18686eb 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,7 @@ an explicit `adapted-from` marker in its frontmatter. | `caveman`, `caveman-commit`, `caveman-compress`, `caveman-help`, `caveman-review` | `adapted-from: JuliusBrussee/caveman` (MIT) — vendored copy, upstream pin TBD | | `find-skills` | `adapted-from: vercel-labs/skills` (MIT) — vendored copy, upstream pin TBD | | `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — family collapsed to one skill (pi hides `disable-model-invocation` wrappers) | +| `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — divergent phase, visual-companion dropped | | all other `skills/*` | `author: ours` | Adaptation policy: a clone is rewritten to our conventions (`.tasks/` boards, diff --git a/README.ru.md b/README.ru.md index 39e1924..b42558f 100644 --- a/README.ru.md +++ b/README.ru.md @@ -84,6 +84,7 @@ bash scripts/build.sh caveman # один | `caveman`, `caveman-commit`, `caveman-compress`, `caveman-help`, `caveman-review` | `adapted-from: JuliusBrussee/caveman` (MIT) — вендорная копия, пин апстрима TBD | | `find-skills` | `adapted-from: vercel-labs/skills` (MIT) — вендорная копия, пин апстрима TBD | | `grilling` | `adapted-from: mattpocock/skills @ 84fdeffd` (MIT) — семейство схлопнуто в один скил (pi прячет `disable-model-invocation` обёртки) | +| `brainstorming` | `adapted-from: obra/superpowers @ 6.2.0` (MIT) — расходящаяся фаза, visual-companion выброшен | | остальные `skills/*` | `author: ours` | Политика адаптации: клон переписывается под наши конвенции (доски `.tasks/`, diff --git a/dist/active-platform.skill b/dist/active-platform.skill index 2385015..064446c 100644 Binary files a/dist/active-platform.skill and b/dist/active-platform.skill differ diff --git a/dist/brainstorming.skill b/dist/brainstorming.skill new file mode 100644 index 0000000..5829a7e Binary files /dev/null and b/dist/brainstorming.skill differ diff --git a/dist/browser-cdp.skill b/dist/browser-cdp.skill index f37e93d..9695100 100644 Binary files a/dist/browser-cdp.skill and b/dist/browser-cdp.skill differ diff --git a/dist/caveman-commit.skill b/dist/caveman-commit.skill index 6da50a7..ca0e873 100644 Binary files a/dist/caveman-commit.skill and b/dist/caveman-commit.skill differ diff --git a/dist/caveman-compress.skill b/dist/caveman-compress.skill index 4e13b1a..26639b1 100644 Binary files a/dist/caveman-compress.skill and b/dist/caveman-compress.skill differ diff --git a/dist/caveman-help.skill b/dist/caveman-help.skill index a5c269b..fd20bf1 100644 Binary files a/dist/caveman-help.skill and b/dist/caveman-help.skill differ diff --git a/dist/caveman-review.skill b/dist/caveman-review.skill index b581c53..0bca211 100644 Binary files a/dist/caveman-review.skill and b/dist/caveman-review.skill differ diff --git a/dist/caveman.skill b/dist/caveman.skill index 1d24d39..e8b425a 100644 Binary files a/dist/caveman.skill and b/dist/caveman.skill differ diff --git a/dist/delegate-task.skill b/dist/delegate-task.skill index 3aa9890..a6830f8 100644 Binary files a/dist/delegate-task.skill and b/dist/delegate-task.skill differ diff --git a/dist/find-skills.skill b/dist/find-skills.skill index c8246c5..d662234 100644 Binary files a/dist/find-skills.skill and b/dist/find-skills.skill differ diff --git a/dist/grilling.skill b/dist/grilling.skill index 916ae8b..28e7b67 100644 Binary files a/dist/grilling.skill and b/dist/grilling.skill differ diff --git a/dist/inter-session-peer-discipline.skill b/dist/inter-session-peer-discipline.skill index c8cf790..faa1aba 100644 Binary files a/dist/inter-session-peer-discipline.skill and b/dist/inter-session-peer-discipline.skill differ diff --git a/dist/meta-host-routing.skill b/dist/meta-host-routing.skill index 5d6db47..cb0a0b1 100644 Binary files a/dist/meta-host-routing.skill and b/dist/meta-host-routing.skill differ diff --git a/dist/private-dev-public-publish.skill b/dist/private-dev-public-publish.skill index 42456b3..8caa01b 100644 Binary files a/dist/private-dev-public-publish.skill and b/dist/private-dev-public-publish.skill differ diff --git a/dist/pulling-before-work.skill b/dist/pulling-before-work.skill index 98c7cf7..f6f029e 100644 Binary files a/dist/pulling-before-work.skill and b/dist/pulling-before-work.skill differ diff --git a/dist/ralph-loop-execution.skill b/dist/ralph-loop-execution.skill index 5ed2f88..183cbe0 100644 Binary files a/dist/ralph-loop-execution.skill and b/dist/ralph-loop-execution.skill differ diff --git a/dist/session-handoff.skill b/dist/session-handoff.skill index 14b3bf9..3428852 100644 Binary files a/dist/session-handoff.skill and b/dist/session-handoff.skill differ diff --git a/dist/session-inbox-monitor.skill b/dist/session-inbox-monitor.skill index 8e169db..869db77 100644 Binary files a/dist/session-inbox-monitor.skill and b/dist/session-inbox-monitor.skill differ diff --git a/dist/setup-agents-task-runner.skill b/dist/setup-agents-task-runner.skill index 33acf17..0443ef4 100644 Binary files a/dist/setup-agents-task-runner.skill and b/dist/setup-agents-task-runner.skill differ diff --git a/dist/setup-context7.skill b/dist/setup-context7.skill index 0e188dd..17c6471 100644 Binary files a/dist/setup-context7.skill and b/dist/setup-context7.skill differ diff --git a/dist/setup-interns.skill b/dist/setup-interns.skill index 02a4be6..259a6eb 100644 Binary files a/dist/setup-interns.skill and b/dist/setup-interns.skill differ diff --git a/dist/setup-projects-meta.skill b/dist/setup-projects-meta.skill index fe14add..d8a7045 100644 Binary files a/dist/setup-projects-meta.skill and b/dist/setup-projects-meta.skill differ diff --git a/dist/setup-tasks.skill b/dist/setup-tasks.skill index 248feef..cf455b4 100644 Binary files a/dist/setup-tasks.skill and b/dist/setup-tasks.skill differ diff --git a/dist/setup-wiki.skill b/dist/setup-wiki.skill index db362f4..bd95fdb 100644 Binary files a/dist/setup-wiki.skill and b/dist/setup-wiki.skill differ diff --git a/dist/task-format.skill b/dist/task-format.skill index f0bd8c1..f8a85b5 100644 Binary files a/dist/task-format.skill and b/dist/task-format.skill differ diff --git a/dist/task-loop.skill b/dist/task-loop.skill index 766c013..ab5e2af 100644 Binary files a/dist/task-loop.skill and b/dist/task-loop.skill differ diff --git a/dist/tdd-criteria.skill b/dist/tdd-criteria.skill index 864b225..98aca81 100644 Binary files a/dist/tdd-criteria.skill and b/dist/tdd-criteria.skill differ diff --git a/dist/update-skills.skill b/dist/update-skills.skill index 423c0ed..e302674 100644 Binary files a/dist/update-skills.skill and b/dist/update-skills.skill differ diff --git a/dist/using-context7.skill b/dist/using-context7.skill index 83a66bc..129eac1 100644 Binary files a/dist/using-context7.skill and b/dist/using-context7.skill differ diff --git a/dist/using-interns.skill b/dist/using-interns.skill index b036008..a407d77 100644 Binary files a/dist/using-interns.skill and b/dist/using-interns.skill differ diff --git a/dist/using-markitdown.skill b/dist/using-markitdown.skill index 4b75fae..a6506d0 100644 Binary files a/dist/using-markitdown.skill and b/dist/using-markitdown.skill differ diff --git a/dist/using-projects-meta.skill b/dist/using-projects-meta.skill index a64babf..f786ff7 100644 Binary files a/dist/using-projects-meta.skill and b/dist/using-projects-meta.skill differ diff --git a/dist/using-system-snapshot.skill b/dist/using-system-snapshot.skill index 9464271..551dbcf 100644 Binary files a/dist/using-system-snapshot.skill and b/dist/using-system-snapshot.skill differ diff --git a/dist/using-vds-ops.skill b/dist/using-vds-ops.skill index 8bb49e0..6b686fa 100644 Binary files a/dist/using-vds-ops.skill and b/dist/using-vds-ops.skill differ diff --git a/dist/using-wiki-graph.skill b/dist/using-wiki-graph.skill index 9d54729..cf378b0 100644 Binary files a/dist/using-wiki-graph.skill and b/dist/using-wiki-graph.skill differ diff --git a/dist/using-wiki.skill b/dist/using-wiki.skill index 556a985..e0b64f9 100644 Binary files a/dist/using-wiki.skill and b/dist/using-wiki.skill differ diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md new file mode 100644 index 0000000..734eaca --- /dev/null +++ b/skills/brainstorming/SKILL.md @@ -0,0 +1,181 @@ +--- +name: brainstorming +adapted-from: obra/superpowers @ 6.2.0 (MIT) +version: 0.1.0 +description: > + The divergent phase of the design cycle: take a raw idea and explore it into a + sharpened design through collaborative dialogue — questions one at a time, + then 2-3 approaches with trade-offs, then a presented design the user approves + before any implementation. Trigger (user): «забрендшторми», «поштормим», «накидай идеи», + «что думаешь про идею», «есть идея, давай поразмышляем», "brainstorm this", + "help me think through", "what should we build". NOT a recommendation + (→ recommend-dont-menu), NOT a stress-test of a finished plan (→ grilling). +--- + +# Brainstorming + +Turn a raw idea into a fully formed design through natural collaborative +dialogue. This is the **divergent phase** of the three-phase cycle: + +1. **Brainstorming** (this skill) — explore intent, diverge, present a design +2. **Discussion** — recommend-dont-menu as the style of the agent's moves + (one position, not a menu) +3. **Grilling** — convergent phase, sharpen the design into an implementable + plan («хватит, к промоушену» / "enough, sharpen it" — the switch) + +The terminal state of this skill is **an approved design** — then grilling (or +the promotion pipeline) takes over. It does NOT write code. + + +Do NOT write code, scaffold a project, invoke an implementation skill, or take +any implementation action until you have presented a design and the user has +approved it. This applies to EVERY request regardless of perceived simplicity. + + +## 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 + +Complete these in order: + +1. **Explore project context** — check files, docs, recent commits. Don't + propose changes to a codebase you haven't looked at. +2. **Ask clarifying questions** — one at a time, understand + purpose/constraints/success criteria. +3. **Propose 2-3 approaches** — with trade-offs and your recommendation. +4. **Present design** — in sections scaled to their complexity, get user + approval after each section. +5. **Write design doc** — save to the project's spec location (below), commit. +6. **Spec self-review** — inline check for placeholders, contradictions, + ambiguity, scope (see below). +7. **User reviews written spec** — ask the user to review the spec file before + proceeding. +8. **Transition** — to grilling (convergence) or the promotion pipeline. + +## 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, flag it 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 flow. Each sub-project gets its own spec cycle. +- For appropriately-scoped projects, ask questions **one at a time**. Prefer + multiple choice questions when possible, but open-ended is fine too. +- Focus on understanding: purpose, constraints, success criteria. + +**Exploring approaches:** + +- Propose 2-3 different approaches with trade-offs. Lead with your + recommended option and explain why. +- Present options conversationally, not as a menu (recommend-dont-menu style: + one position, argued). +- YAGNI ruthlessly — remove unnecessary features from every approach. + +**Presenting the design:** + +- Once you believe you understand what's being built, 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 (a file grown too + large, unclear boundaries, tangled responsibilities), include targeted + improvements as part of the design. +- Don't propose unrelated refactoring. Stay focused on what serves the current + goal. + +## Spec location + +Where the design doc goes (per project-discipline Rule 1 — specs → wiki): + +- regular project → `.wiki/concepts/-design.md` +- workshop zone → `.brainstorm/.md` (running record), then the + promotion pipeline takes over (workshop-promote-brainstorm) +- user preference overrides the default + +Commit the design document to git. + +## Spec Self-Review + +After writing the spec, 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 re-review — just fix and move on. + +## User Review Gate + +After the self-review passes, ask the user to review the written spec before +proceeding: + +> "Spec written and committed to ``. Please review it and let me know if +> you want any changes before we move to convergence." + +Wait for the user's response. If they request changes, make them and re-run the +self-review. Only proceed once the user approves. + +## Transition + +Once the design is approved and the spec is reviewed: + +- if the design still has open decisions or needs sharpening → invoke + **grilling** («хватит, к промоушену» / "enough, sharpen it") +- otherwise → the promotion pipeline / task creation takes over + (workshop-promote-brainstorm in the workshop zone) + +Do NOT skip to implementation just because the design is approved — the +convergent phase is what turns a design into an implementable plan. + +## Cross-agent applicability + +Pure dialogue methodology — no harness-specific tool references. Works on pi, +Claude, or any agent. The spec-location line references our project-discipline +convention; on a different setup, follow that project's own wiki/spec layout. + +## Out of scope + +- Does NOT stress-test a finished plan (that's grilling). +- Does NOT give a single recommendation on demand (that's recommend-dont-menu). +- Does NOT write code or invoke implementation skills — the HARD-GATE holds + until the user approves the design. +- No visual companion / browser mockup server (upstream has one; we skip it — + if a visual question genuinely needs showing, offer a sketch/diagram in the + doc instead).