From 50640d8cb539fa2091f3d97745863b3c98e8bad8 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Tue, 2 Jun 2026 23:23:41 +0300 Subject: [PATCH] =?UTF-8?q?feat(skills):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=20=D1=81=D0=BA=D0=B8=D0=BB=D0=BB=20brainstor?= =?UTF-8?q?m-with-docs=20(v1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - нужен ручной скилл для брейнсторма и дизайна, который удерживает словарь смыслов (CONTEXT.md) и лёгкие ADR, активно прожаривает план и не сваливается в реализацию. - Что: - SKILL.md: процесс (контекст → классификация → декомпозиция → грилл → синтез опций → подтверждение → артефакт), единый HARD-GATE «исследуй, но не меняй состояние» с поправкой на auto mode. - artifacts/: шаблоны spec, research-note, adr, runbook, prd, context (по файлу на тип для progressive disclosure). - README.md с MIT-атрибуцией grill-with-docs (Pocock) и brainstorming (obra/superpowers); шов для будущей фазы дивергенции в шаге 5. - frontmatter переносим: Claude читает все поля, Codex — name+description. - Проверка: - python3 yaml-парс frontmatter; markdown-ссылки на artifacts/ резолвятся. --- .../skills/brainstorm-with-docs/README.md | 81 +++++++ .../skills/brainstorm-with-docs/SKILL.md | 229 ++++++++++++++++++ .../brainstorm-with-docs/artifacts/adr.md | 40 +++ .../brainstorm-with-docs/artifacts/context.md | 53 ++++ .../brainstorm-with-docs/artifacts/prd.md | 38 +++ .../artifacts/research-note.md | 38 +++ .../brainstorm-with-docs/artifacts/runbook.md | 37 +++ .../brainstorm-with-docs/artifacts/spec.md | 56 +++++ 8 files changed, 572 insertions(+) create mode 100644 agents/.agents/skills/brainstorm-with-docs/README.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/SKILL.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/context.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/prd.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/research-note.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/runbook.md create mode 100644 agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md new file mode 100644 index 0000000..ef25d08 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/README.md @@ -0,0 +1,81 @@ +# brainstorm-with-docs + +A manually-invoked skill for **brainstorming, design alignment, and durable +documentation** — grounded in a project's existing docs and vocabulary. It takes +an unclear engineering, DevOps, architecture, migration, integration, research, +or documentation problem and turns it into the *smallest useful* durable +artifact: a spec, ADR, runbook, research note, or `CONTEXT.md` glossary update. + +It is deliberately **not** an implementation skill. It reads project files and +proposes documentation, but stops before code, config, or infrastructure changes +— approval of a design direction is never approval to implement. + +## Why this exists + +It combines three things that are usually separate: + +- **shared domain language** (glossary / `CONTEXT.md`) and **lightweight ADRs** — + the discipline of capturing terminology and durable decisions as they crystallise; +- **active grilling** — not just extracting requirements, but pressure-testing + them: challenging terms against the glossary, sharpening fuzzy language, probing + with edge-case scenarios, cross-checking claims against the code; +- **option exploration** — always comparing 2-3 viable approaches with trade-offs + before recommending a direction. + +## Usage + +Invoke manually: + +``` +/brainstorm-with-docs +``` + +On **Claude Code** the skill is manual-only (`disable-model-invocation: true`) — +it never auto-triggers; you always call it. On **Codex** that field is ignored +(Codex reads only `name` + `description`), so it may auto-trigger on matching +design tasks; the negative triggers in the description keep that disciplined. + +## Layout + +``` +brainstorm-with-docs/ +├── SKILL.md # the skill: process, rules, grill mechanics +├── README.md # this file +└── artifacts/ # output templates — read only the one you need + ├── spec.md # solution design / engineering spec + ├── research-note.md # exploratory, answer not yet known + ├── adr.md # lightweight architectural decision record + ├── runbook.md # operational procedure + ├── prd.md # product-facing behaviour + └── context.md # CONTEXT.md glossary format +``` + +Templates are split per type so the agent loads only what's relevant +(progressive disclosure). + +## Roadmap + +- **v1 (current):** working hybrid — context inspection, glossary/ADR discipline, + active grilling, option comparison, durable artifacts, stop-before-implementation. +- **v2 (planned):** a *divergence phase* before option synthesis (an + idea-generation toolkit plus the rule "at least one option the user didn't + already imply"), a "design for isolation" lens, and fuller multi-context + support. A `` marker in `SKILL.md` step 5 marks where it slots in. + +## Attribution + +This is a derived, original skill — not a copy of either source. It borrows ideas +from two MIT-licensed projects: + +- **grill-with-docs / grill-me** by Matt Pocock — + (MIT, © 2026 Matt Pocock). + Source of the glossary/`CONTEXT.md` discipline, lightweight ADRs, and the + active grilling techniques. +- **brainstorming** by Jesse Vincent (obra), from Superpowers — + (MIT, © 2025 Jesse Vincent). + Source of the explore-context → question → compare-options → present-design flow + and the stop-before-implementation gate. + +The `CONTEXT.md` and ADR formats are adapted from Matt Pocock's `grill-with-docs` +companion files. Both upstream projects are MIT-licensed; see their repositories +for full license text. diff --git a/agents/.agents/skills/brainstorm-with-docs/SKILL.md b/agents/.agents/skills/brainstorm-with-docs/SKILL.md new file mode 100644 index 0000000..88752eb --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/SKILL.md @@ -0,0 +1,229 @@ +--- +name: brainstorm-with-docs +description: Structured brainstorming and design alignment for unclear technical problems, grounded in the project's existing docs and vocabulary — questioning assumptions, sharpening terminology, comparing options, and recommending a direction. Use when exploring an ambiguous engineering, DevOps, architecture, migration, integration, research, or documentation problem and turning it into a durable artifact such as a spec, ADR, runbook, research note, or CONTEXT.md glossary update. Not for implementation, trivial fixes, or executing an already-approved plan. +disable-model-invocation: true +argument-hint: "[problem-or-topic]" +allowed-tools: Read Grep Glob Write Edit WebSearch WebFetch Bash(git log:*) Bash(git diff:*) Bash(git status:*) Bash(git show:*) +--- + +# Brainstorm With Docs + +Move the user from an unclear problem to shared understanding, clear project +language, viable options, a recommended direction, and the smallest useful +durable documentation artifact. This skill is for thinking, alignment, and +documentation — not for implementation. + + + +Do NOT write code, change configuration or infrastructure, run state-changing +commands, refactor, run migrations, deploy, or invoke any implementation skill +until the user has approved a design AND explicitly asked to implement. + +Approval of a design direction is NOT approval to implement. After producing or +updating the agreed documentation artifact, STOP. + +The skill may freely investigate — read project files, run read-only inspection +commands, and look up external documentation — and may create or update +documentation files once the user agrees on the direction. It must NOT change the +state of any system: no code, config, or infrastructure changes; no data writes +or migrations; no deployments; and no outward-facing actions other than read-only +lookups. + +If you are unsure whether a command has side effects — especially when querying a +live or production system — state what you intend to run and why, and get a yes, +before running it. Do not rely on the harness to stop you; in auto mode it may +not. + + + + + +Use this skill for: + +* ambiguous engineering tasks +* architecture or design decisions +* DevOps and infrastructure work +* research-heavy technical tasks +* migration, integration, or operational-procedure design +* choosing between implementation approaches +* converting a discussion into a durable specification +* clarifying project terminology and assumptions + +Do not use this skill for: + +* tiny mechanical edits or straightforward bug fixes with an obvious cause +* simple code generation +* pure execution of an already-approved plan +* cases where the user explicitly asks to skip discussion and implement + +If invoked with arguments, treat `$ARGUMENTS` as the initial problem statement. + + + + + +* Ask one question at a time when interviewing; wait for the answer. +* Never ask for something the repository can answer — search first. +* Prefer project-specific language over generic terminology. +* Surface assumptions, constraints, risks, trade-offs, and non-goals. +* Don't interview forever — when the problem, constraints, and success criteria + are clear enough, stop asking and synthesize. +* Always consider 2-3 viable approaches before recommending one. +* Be direct. Give a real recommendation; don't hide behind "it depends" when the + context supports a call. +* Explicitly state what should NOT be done now. +* Use the smallest artifact that preserves the useful thinking. +* Keep `CONTEXT.md` strictly a glossary; create ADRs only sparingly. +* Do not produce a detailed implementation plan unless the user asks for one. + + + + + +## 1. Inspect project context + +Before asking the user anything, read the relevant context. Prefer this order: + +1. `AGENTS.md` or an equivalent project map +2. README / project overview +3. `docs/`, then existing specs and design docs +4. ADRs (`docs/adr/`), runbooks, status docs +5. code and config relevant to the problem + +Look for: existing terminology, decisions already made, known constraints, +previously rejected options, deployment model, testing/validation conventions, +and patterns the solution should follow. Respect a documented structure if one +exists. If no context is available, say so and continue with what the user gives. + +## 2. Classify the work and pick the likely artifact + +Decide what kind of work this is, then which artifact is likely to fit: + +* answer still unknown → [research note](artifacts/research-note.md) +* direction chosen, not yet built → [spec / solution design](artifacts/spec.md) +* durable, surprising, hard-to-reverse trade-off → [ADR](artifacts/adr.md) +* operational procedure / recovery / diagnostics → [runbook](artifacts/runbook.md) +* shared project vocabulary → [`CONTEXT.md` glossary](artifacts/context.md) +* product-facing, user-visible behaviour → [PRD](artifacts/prd.md) + +Don't force everything into a PRD. Read an artifact's file only when you're +actually about to write that kind of artifact. + +## 3. Check scope and decompose if needed + +Before deep brainstorming, check whether this is one coherent problem or several. +If it's too broad, pause and propose a decomposition — separating research from +implementation, design from execution, product requirements from engineering +design, one-time setup from recurring operations, reversible from hard-to-reverse +decisions. Ask which part to handle first. + +## 4. Interview / grill + +Interview the user until the problem is clear enough to synthesize. One question +at a time. When the reason for a question isn't obvious, briefly say why it +matters. Prefer questions that clarify: the actual problem and why it matters, +expected outcome, who is affected, constraints, non-goals, success criteria, +failure modes, operational and security risks, reversibility, deadlines or +sequencing, what's been tried, and what must not change. + +Grill actively — don't just collect answers, pressure-test them: + +* **Challenge against the glossary.** If a term conflicts with `CONTEXT.md`, call + it out: "Your glossary defines 'cancellation' as X, but you mean Y — which?" +* **Sharpen fuzzy language.** Propose a precise canonical term for vague or + overloaded words: "You say 'account' — Customer or User? Those differ." +* **Probe with concrete scenarios.** Invent edge cases that force precision about + the boundaries between concepts. +* **Cross-reference with code.** When the user states how something works, check + the code agrees; surface contradictions: "Your code cancels whole Orders, but + you said partial cancellation is possible — which is right?" + +Capture resolved terms in `CONTEXT.md` inline, as they happen, using the format +in [artifacts/context.md](artifacts/context.md) — don't batch them. + +## 5. Synthesize options + + + +Present 2-3 viable approaches. For each: short description, when it fits, +benefits, trade-offs, risks, operational implications, documentation impact, and +what it avoids or postpones. Then recommend one, explaining why it fits the +constraints, what risks remain, what to validate first, and what to explicitly +not do now. + +## 6. Confirm direction + +Before writing or changing durable project documents, confirm the direction. +Confirmation can be lightweight, e.g.: + +> "I recommend option B. I'd document it as a solution design, add one +> lightweight ADR for the storage-layout decision, and add two terms to +> `CONTEXT.md`. Does that match your intent?" + +Don't ask permission for every wording choice, but DO confirm before: creating a +spec, creating an ADR, changing architectural direction, or changing documented +vocabulary. + +## 7. Write the artifact + +Once the user agrees, create or update the artifact, following the format in the +matching `artifacts/*.md` file. Choose the smallest form that preserves the +thinking. + +Where it goes: follow the repo's existing documentation layout if there is one. +Otherwise use the conventional homes — `CONTEXT.md` at the repo root, ADRs in +`docs/adr/`, and other artifacts under `docs/` (e.g. `docs/specs/`, +`docs/runbooks/`). If the location isn't obvious, propose a path and confirm it +as part of step 6 rather than guessing. Create directories lazily. + +Then go to `` and ``. + + + + + +`CONTEXT.md` is only for shared project language: domain terms, project-specific +concepts, preferred names, terms to avoid, and short relationships between +concepts when they clarify language. It is a glossary, not a spec, work log, ADR +store, validation plan, or list of rejected alternatives. + +While interviewing, watch for terms that are ambiguous, overloaded, used +inconsistently, or missing from shared docs. If a durable term matters to future +work, propose adding it. Full format and rules: [artifacts/context.md](artifacts/context.md). + +If something is a decision → spec or ADR. If it's an operational procedure → +runbook. If it's a validation rule for this work → the spec. + + + + + +Before presenting the final artifact, review it for: unclear terms, missing +constraints, hidden assumptions, contradictions with existing docs, unnecessary +scope expansion, premature implementation detail, missing validation criteria, +decisions that should (or should not) be ADRs, operational steps that should be a +runbook, and context that does (or does not) belong in `CONTEXT.md`. + +If it's too large, propose splitting it. If it's too vague, continue the +interview. + + + + + +After the artifact is produced, STOP. Do not start coding, change +infrastructure, alter configuration, or run state-changing commands unless the +user explicitly asks. Offer a small set of next actions, such as: + +* refine the spec +* create or update an ADR +* update `CONTEXT.md` +* create a runbook +* derive a compact implementation checklist +* start implementation (only on explicit request) + +Do not proceed automatically. + + diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md new file mode 100644 index 0000000..239b073 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/adr.md @@ -0,0 +1,40 @@ +# ADR — Architectural Decision Record + +ADRs live in `docs/adr/` with sequential numbering: `0001-slug.md`, +`0002-slug.md`, etc. Create `docs/adr/` lazily — only when the first ADR is +needed. To number a new one, scan `docs/adr/` for the highest number and add one. + +## When to offer an ADR + +Offer one only when **all three** are true: + +1. **Hard to reverse** — the cost of changing your mind later is meaningful. +2. **Surprising without context** — a future reader will look at the code and + wonder "why on earth did they do it this way?" +3. **The result of a real trade-off** — there were genuine alternatives and one + was picked for specific reasons. + +If any of the three is missing, skip it. Easy to reverse → you'll just reverse +it. Not surprising → nobody will wonder. No real alternative → nothing to record +beyond "we did the obvious thing". Do not create an ADR for every small choice. + +## Template + +```markdown +# {Short title of the decision} + +{1-3 sentences: what's the context, what we decided, and why.} +``` + +That's it. An ADR can be a single paragraph. The value is recording *that* a +decision was made and *why* — not in filling out sections. + +## Optional sections + +Add these only when they earn their place (most ADRs won't need them): + +- **Status** frontmatter (`proposed | accepted | deprecated | superseded by + ADR-NNNN`) — useful when decisions get revisited. +- **Considered options** — only when the rejected alternatives are worth + remembering (otherwise someone re-proposes them in six months). +- **Consequences** — only when non-obvious downstream effects need calling out. diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md new file mode 100644 index 0000000..c1c099a --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/context.md @@ -0,0 +1,53 @@ +# CONTEXT.md — Shared Project Language + +`CONTEXT.md` is a **glossary and nothing else**. It exists so that the user, the +code, and future agents use the same words for the same concepts. It is totally +devoid of implementation details, decisions, plans, or work logs. + +A single `CONTEXT.md` lives at the repo root. If a `CONTEXT-MAP.md` exists at the +root, the repo has multiple contexts — read it to find which `CONTEXT.md` the +current topic belongs to. (Multi-context handling is deliberately light in v1.) + +Create the file lazily — only when the first term is actually worth recording. + +## Structure + +```markdown +# {Context Name} + +{One or two sentences: what this context is and why it exists.} + +## Language + +**Order**: +A customer's request to purchase one or more items. +_Avoid_: Purchase, transaction + +**Invoice**: +A request for payment sent to a customer after delivery. +_Avoid_: Bill, payment request + +**Customer**: +A person or organisation that places orders. +_Avoid_: Client, buyer, account +``` + +## Rules + +- **Be opinionated.** When several words mean the same thing, pick the best one + and list the rest under `_Avoid_`. +- **Keep definitions tight.** One or two sentences. Define what it *is*, not what + it *does*. +- **Only project-specific terms.** General programming concepts (timeouts, retry, + cache) don't belong, even if the project uses them heavily. Ask: is this unique + to this project's domain, or generic? Only the former belongs. +- **Group under subheadings** when natural clusters emerge; a flat list is fine + otherwise. + +## What does NOT go in CONTEXT.md + +- implementation details +- specs, decisions, or rejected alternatives → spec / ADR +- operational procedures → runbook +- validation rules for the current work → spec +- work logs, temporary notes, speculative ideas diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/prd.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/prd.md new file mode 100644 index 0000000..7334367 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/prd.md @@ -0,0 +1,38 @@ +# PRD — Product Requirements Document + +Use **only** for product-facing work with user-visible behaviour. For internal +engineering, infra, or architecture work use `artifacts/spec.md` instead — don't +force everything into a PRD. + +## Template + +```markdown +# Title + +## Problem statement + +## Users + +## Goals + +## Non-goals + +## User stories + +## Requirements + +## Out of scope + +## Success criteria + +## Open questions +``` + +## Notes + +- A PRD describes *what* and *why* from the user's point of view, not *how*. The + engineering "how" belongs in a spec. +- **Non-goals** and **Out of scope** are deliberately separate: non-goals are + things we chose not to optimise for; out of scope is work explicitly deferred. +- **Success criteria** must be observable — how will we know the behaviour is + right once shipped? diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/research-note.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/research-note.md new file mode 100644 index 0000000..fa16f02 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/research-note.md @@ -0,0 +1,38 @@ +# Research Note + +Use when the work is exploratory and the final answer is not yet known. The +output is *findings and a direction*, not a committed design. + +When the question is resolved, the research note often graduates into a spec +(`artifacts/spec.md`) or an ADR (`artifacts/adr.md`). + +## Template + +```markdown +# Title + +## Question + +## Context + +## Known facts + +## Assumptions + +## Options / hypotheses + +## Findings + +## Recommendation + +## Remaining unknowns + +## Next checks +``` + +## Notes + +- Keep **Known facts** and **Assumptions** strictly separate. Conflating them is + how a guess hardens into an unexamined "fact". +- **Remaining unknowns** and **Next checks** are what make a research note + useful to the next agent — they say where to dig next. diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/runbook.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/runbook.md new file mode 100644 index 0000000..bdfdbdb --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/runbook.md @@ -0,0 +1,37 @@ +# Runbook + +Use for operational procedures: diagnostics, verification, recovery, deployment, +or routine maintenance. A runbook is for *doing*, so optimise for someone +following it under pressure — concrete commands, expected output, clear failure +branches. + +## Template + +```markdown +# Title + +## Purpose + +## When to use + +## Preconditions + +## Procedure + +## Verification + +## Rollback / recovery + +## Known failure modes + +## Notes +``` + +## Notes + +- **Procedure** steps should be copy-pasteable where possible, with the expected + result after each consequential step. +- **Verification** is how the operator confirms success — not "it should work" + but "run X, expect Y". +- **Rollback / recovery** and **Known failure modes** are what separate a + runbook from a tutorial. If you can't say how to undo it, say that explicitly. diff --git a/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md b/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md new file mode 100644 index 0000000..0febebd --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/artifacts/spec.md @@ -0,0 +1,56 @@ +# Solution Design / Spec + +Use for engineering, architecture, DevOps, integration, migration, or any +non-product feature work where a direction has been chosen but not yet built. + +Use the smallest version that preserves the useful thinking. Drop sections that +add nothing for this particular problem — an empty section is noise. + +## Template + +```markdown +# Title + +## Problem + +## Context + +## Goals + +## Non-goals + +## Current state + +## Options considered + +## Recommended approach + +## Rationale + +## Decisions and rejected alternatives + +## Risks and mitigations + +## Validation + +## Documentation impact + +## Open questions +``` + +## Notes on key sections + +**Decisions and rejected alternatives** is the highest-value section. Capture: + +- accepted decisions and the reason behind each +- rejected alternatives and *why* they were rejected +- subtle constraints and important defaults +- sequencing decisions +- assumptions future agents must not silently re-derive + +Do not turn this section into an ADR dump. Promote a decision to its own ADR +(`artifacts/adr.md`) only when it is durable, surprising, and the result of a +real trade-off. + +**Validation** describes how we will know the implementation is correct — tests, +checks, acceptance criteria. It belongs here, not in `CONTEXT.md`.