diff --git a/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md b/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md new file mode 100644 index 0000000..95ce585 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/DEV-HANDOFF.md @@ -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 `` 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. diff --git a/agents/.agents/skills/brainstorm-with-docs/README.md b/agents/.agents/skills/brainstorm-with-docs/README.md index 04820ab..fa21943 100644 --- a/agents/.agents/skills/brainstorm-with-docs/README.md +++ b/agents/.agents/skills/brainstorm-with-docs/README.md @@ -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 `` 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 diff --git a/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md new file mode 100644 index 0000000..9c18db1 --- /dev/null +++ b/agents/.agents/skills/brainstorm-with-docs/ROADMAP.md @@ -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 ``: "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.