ddadmin
01d1de88d3
- Зачем:
- решения и рассуждения по скиллу были размазаны по памяти агента,
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 резолвится.
76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# 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.
|