0 Fork 0

Files

T

ddadmin 01d1de88d3 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

4.0 KiB

Raw Blame History

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; 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  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.

4.0 KiB Raw Blame History