docs(brainstorm-with-docs): добавлены ROADMAP и DEV-HANDOFF на время разработки

- Зачем: - решения и рассуждения по скиллу были размазаны по памяти агента, README и комментарию у шва; нужен durable in-repo источник, который переживёт смену сессии и не зависит от конкретного агента. - Что: - ROADMAP.md: статус v1, отложенные решения (R1 рекомендованный ответ на вопрос, R2 дотошность грилла, F1 строка дивергенции, F4 связь с grill-with-docs, F5a docs/agents), v2-крупное и отклонённое (F6). - DEV-HANDOFF.md: контекст для возобновления, неочевидные обоснования (frontmatter-переносимость, гейт под auto mode, агайл), suggested skills. - README.md: ссылка на ROADMAP с пометкой про dev-only docs. - Проверка: - markdown-ссылка README → ROADMAP.md резолвится.
2026-06-03 00:01:46 +03:00
1 parent f24b342123
commit 01d1de88d3
@@ -0,0 +1,75 @@
+# Dev handoff — brainstorm-with-docs
+
+Resume context for a fresh agent working on **this skill's development**.
+Dev-phase only; remove before the skill stabilises. For the backlog and decisions
+see [ROADMAP.md](ROADMAP.md); don't duplicate it here.
+
+## What this is
+
+A custom, manually-invoked skill that fuses Matt Pocock's `grill-with-docs`
+(glossary/`CONTEXT.md` + lightweight ADRs + active grilling) with obra/superpowers
+`brainstorming` (explore → question → compare options → recommend → design doc),
+tailored to the user. It is for thinking/alignment/documentation, never
+implementation. See `SKILL.md`, `README.md`, and `artifacts/*.md` for the result.
+
+Source files on disk (for comparison / not to be copied wholesale):
+- `~/.claude/skills/grill-with-docs/{SKILL.md,CONTEXT-FORMAT.md,ADR-FORMAT.md}`
+- `~/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.7/skills/brainstorming/SKILL.md`
+
+## State
+
+- v1 shipped + reviewed. Commits `50640d8`, `f24b342` (pushed to origin/master).
+- Repo path: `~/dotfiles/agents/.agents/skills/brainstorm-with-docs/`, symlinked
+  into `~/.claude/skills/` (stow). Codex has a *separate* skills dir; this skill
+  is not yet shared there.
+- Cross-session memory: `project_brainstorm_with_docs.md` (in the agent's memory
+  dir, indexed from MEMORY.md). The in-repo `ROADMAP.md` is now the canonical
+  roadmap; memory is a pointer.
+
+## Non-obvious rationale (the "why", not re-derivable from the files)
+
+- **Frontmatter is portability-driven.** Claude reads all fields; Codex reads
+  ONLY `name` + `description` (verified from Codex's own skill-creator). So extra
+  fields are kept only when "useful on Claude, inert on Codex." `disallowed-tools`
+  was removed — it's ineffective even on Claude (clears after the next message).
+  `allowed-tools` space-separated is valid (Claude docs); it is pre-approval, not
+  a restriction. Don't reopen this (= rejected finding F6 in ROADMAP).
+- **The gate is the real control, not the harness.** User runs agents in auto
+  mode, where permission prompts are unreliable. So `<hard_gate>` is written to be
+  self-enforcing ("don't rely on the harness; announce before touching live
+  systems") and allows investigation (read + read-only cmds + web research) while
+  forbidding state changes.
+- **`disable-model-invocation: true` is intentional** even though the user said
+  "mostly manual" — for an *interview* skill, surprise auto-activation is more
+  annoying than helpful; predictable manual invocation fits better.
+- **Agile by design.** v1 = "boring-correct working hybrid"; the novel
+  divergence mechanics are deferred to v2 on purpose, with a `<!-- SEAM -->` at
+  `SKILL.md` step 5 kept self-contained so v2 slots in without restructuring.
+
+## Open threads (decide with the user)
+
+All tracked in `ROADMAP.md`. Most live ones:
+- **R1** — restore grill's "give a recommended answer with each question" (likely
+  accidental drop in v1). User leaning yes; deciding whether to do it now or after
+  the first live test.
+- **R2 / F1** — interview relentlessness + the divergence one-liner are held back
+  on purpose so the first live test shows the pure-convergence baseline.
+- **F4** — decide how `brainstorm-with-docs` and `grill-with-docs` coexist.
+
+## Immediate next step
+
+The user runs the **first live test on real tasks** next. Capture observations
+(does it under-grill? do options collapse into one idea? is multi-context missed?)
+and feed them into the R1/R2/F1 decisions. Append findings to this file or
+`ROADMAP.md` as you go.
+
+## Suggested skills
+
+- **brainstorm-with-docs itself** — dogfood it; refining it is exactly a
+  design/documentation problem.
+- **write-a-skill** — sanity-check SKILL.md structure/frontmatter on changes.
+- **grill-with-docs** — reference to check no valuable mechanic was lost (this is
+  how R1/R2 were found).
+- **conventional-commits** — required for any commit here (commits are in Russian,
+  `type(scope): …` + Зачем/Что/Проверка body).
+- **handoff** — refresh this file when a session produces a new stable state.
@@ -65,6 +65,10 @@ Templates are split per type so the agent loads only what's relevant
  already imply"), a "design for isolation" lens, and fuller multi-context
  support. A `<!-- SEAM -->` marker in `SKILL.md` step 5 marks where it slots in.

+See [ROADMAP.md](ROADMAP.md) for the full backlog, pending decisions, and what
+has been considered and rejected. (Dev-phase docs — `ROADMAP.md` and any
+`DEV-HANDOFF.md` — can be removed once the skill stabilises.)
+
 ## Attribution

 This is a derived, original skill — not a copy of either source. It borrows ideas
@@ -0,0 +1,55 @@
+# Roadmap & backlog — brainstorm-with-docs
+
+Single source of truth for what's done, pending, and deferred. In-repo and
+versioned so it survives across sessions and tools (not just an agent's memory).
+
+## Status
+
+- **v1 — shipped.** Commits `50640d8` (initial) and `f24b342` (review fixes).
+  Working hybrid: context inspection, glossary/`CONTEXT.md` + lightweight ADR
+  discipline, active grilling, option comparison, durable artifacts, and a
+  stop-before-implementation gate that allows investigation but forbids state
+  changes.
+- **Next process step:** live test on real tasks (started ~2026-06-03). Findings
+  feed the decisions below.
+
+## Pending decisions (small, near-term)
+
+- **R1 — restore "recommend an answer per question."** `grill-with-docs` and
+  `grill-me` both require giving a recommended answer with each question; v1
+  dropped it (likely accidental). Cheap to restore in `SKILL.md` step 4.
+  *Decision pending: restore now, or after the first live test.*
+- **R2 — interview relentlessness.** v1 softened grill's "interview relentlessly,
+  walk every branch" into "don't interview forever, move to synthesis" (from
+  superpowers brainstorming). Decide after the live test whether it feels
+  under-rigorous and needs hardening — or whether that's what `grill-with-docs`
+  stays for (see R4).
+- **F1 — divergence one-liner.** Add one `<core_rule>`: "among the options, at
+  least one must be something the user did not already imply." Deliberately
+  deferred to keep the v1 baseline test clean. Marked as `TODO(F1)` at the SEAM
+  in `SKILL.md` step 5. Reconsider right after the first live test.
+- **F4 — relationship to `grill-with-docs`.** This skill overlaps it (grill +
+  CONTEXT/ADR). Decide: document when-to-use-which in `README.md`, or supersede
+  `grill-with-docs`. Not a strict superset (we lack full multi-context, R2).
+- **F5a — read `docs/agents/*.md` in step 1.** On repos using Matt Pocock's
+  skill-config convention, the spec/layout path is more reliable from there than
+  guessing. Cheap addition to the step-1 read list.
+
+## v2 (larger)
+
+- **Divergence phase** at the SEAM (`SKILL.md` step 5): full idea-generation
+  toolkit — axis of variation, archetype stances (MVP / robust / radical),
+  inversion, steal-from-adjacent-domain, cost-shifting, pre-mortem, constraint
+  relaxation, null option. F1 is the cheap precursor to this.
+- **"Design for isolation / clarity" lens** (from superpowers brainstorming):
+  evaluate options by whether each unit has one clear purpose and a clean
+  interface.
+- **Fuller multi-context.** v1 handles a single root `CONTEXT.md` and only
+  mentions `CONTEXT-MAP.md`. Restore grill-with-docs's full model: `CONTEXT-MAP.md`
+  + per-context `CONTEXT.md` + per-context `docs/adr/` + a Relationships section.
+
+## Rejected (do not revisit without new evidence)
+
+- **F6 — "space-separated `allowed-tools` won't parse."** False. Claude Code docs
+  accept space- or comma-separated or YAML list; and `allowed-tools` is
+  pre-approval, not a restriction. No change needed.