@open-agent-toolkit/cli 0.0.60 → 0.0.64

package/assets/docs/cli-utilities/tool-packs.md

@@ -22,6 +22,7 @@ This page covers CLI commands that manage bundled OAT tool packs and installed O
 - `utility` - review and repo-maintenance helpers
 - `project-management` - file-backed backlog/reference skills plus backlog and roadmap templates
 - `research` - research, analysis, comparison, and synthesis skills
+- `brainstorm` - always-on brainstorming entry point with visual companion
 
 ## `oat tools` command group
 
@@ -36,7 +37,7 @@ Purpose:
 Key behavior:
 
 - Scans installed skills and agents across project and user scopes
-- Displays version, pack (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `custom`), and status (`current`, `outdated`, `newer`, `not-bundled`)
+- Displays version, pack (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`, `custom`), and status (`current`, `outdated`, `newer`, `not-bundled`)
 - Supports `--scope` filtering and `--json` output
 
 ### `oat tools outdated`
@@ -67,14 +68,15 @@ Key behavior:
 
 Purpose:
 
-- Install bundled OAT tool packs (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`)
+- Install bundled OAT tool packs (`core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`)
 
 Key behavior:
 
 - Same pack selection and install flow as `oat init tools`
-- Pack-oriented install subcommands: `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`
+- Pack-oriented install subcommands: `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`
 - Interactive installs show each pack's current install location in the picker so already-installed packs are visible before you submit
-- User-scope follow-up choices are prepopulated from the current install state for user-eligible packs (`ideas`, `docs`, `utility`, `research`)
+- User-scope follow-up choices are prepopulated from the current install state for user-eligible packs (`ideas`, `docs`, `utility`, `research`, `brainstorm`)
+- The `brainstorm` pack defaults to user scope on fresh installs (driven by `PACK_METADATA[brainstorm].defaultScope = 'user'`); existing project-scope installs still take precedence on re-install so users do not get unexpected scope migrations
 - If a user-eligible pack is already installed in both project and user scope, the installer asks whether to keep both installs or normalize the pack to user scope before it makes any cleanup changes
 - Changing a user-eligible pack from project scope to user scope, or back again, is treated as a migration: the old canonical copy is removed so the pack ends in the selected scope instead of accumulating duplicate installs
 - Tracks installed vs bundled skill versions and reports outdated skills
@@ -167,6 +169,74 @@ Key behavior:
 - `oat tools update --pack docs` and `oat tools remove --pack docs` manage the
   workflow skills as a unit.
 
+## Brainstorm pack
+
+The `brainstorm` pack ships a single skill plus a bundled visual companion for
+project-independent brainstorming conversations:
+
+- **oat-brainstorm** — Brainstorming entry point with an explicit activation
+  contract. The OAT brainstorm banner is a workflow commitment marker, not a
+  response style — the skill enters mode only on **Hard Activation** (explicit
+  `brainstorm` verb: "let's brainstorm", "brainstorm this", "can we brainstorm
+  X", "help me brainstorm X", or `/oat-brainstorm`). Ambiguous exploratory
+  phrasing ("I've been thinking about", "what if we", "help me think through")
+  follows the **Soft Exploratory Path** — answered conversationally
+  with brainstorm-quality reasoning (options, tradeoffs, no premature
+  implementation, no destination guess) without the banner. After ≥2 sustained
+  exploratory turns the skill offers mode once: _"If you want, I can switch into
+  structured brainstorm mode for this."_ Advisory / review / debug / PR /
+  status / implementation / active-workflow questions ("thoughts?", "what's
+  your take?", "does this seem right?", "why is this failing?") follow **No
+  Activation** — direct response, no banner, no offer.
+  Once entered, brainstorm mode runs a structured design conversation (one
+  question at a time, 2-3 approaches with a recommendation) without committing
+  the user to an idea or project artifact, and ends in a pack-aware
+  terminal-state picker that hands off to existing OAT skills (idea capture,
+  scoped backlog item, project promotion, active-project fold-back,
+  doc-to-path) based on which packs are installed in the current repo. Two base
+  outcomes (inline-only and write a brainstorming doc to a user-specified path)
+  are always available regardless of installed packs.
+
+Key behavior:
+
+- **Default user scope.** The `brainstorm` pack is user-eligible and defaults
+  to user scope so the always-on trigger fires consistently across directories
+  and machines. This is driven by the generalized pack-metadata mechanism
+  (`PACK_METADATA[brainstorm].defaultScope = 'user'`); other user-eligible
+  packs (`ideas`, `docs`, `utility`, `research`) still default to project scope
+  unless their metadata is updated.
+- **Existing-install precedence.** Re-running install on a pack that is
+  already installed at project scope preserves that scope — `defaultScope` only
+  applies to fresh installs. This protects users from unexpected scope
+  migrations.
+- **Default-on in `oat init`.** `brainstorm` is checked by default in the
+  `oat init tools` guided setup, so new repos get the brainstorming entry point
+  out of the box.
+- **Visual companion.** A bundled local browser-based UI (Node-based HTTP +
+  WebSocket server, content-fragment authoring, per-question terminal-vs-browser
+  routing) ships with the skill at `.agents/skills/oat-brainstorm/scripts/`
+  and is documented in
+  `.agents/skills/oat-brainstorm/references/visual-companion.md`. The companion
+  is offered only when the topic is visual-likely (mockups, layout comparisons,
+  diagrams, visual option comparisons). Text-likely brainstorms skip the offer
+  and can surface it later if the conversation turns visual. Persistence paths
+  use OAT-managed prefixes (`.oat/brainstorm/<session-id>/` repo-scope or
+  `~/.oat/brainstorm/<session-id>/` user-scope).
+- **Terminal-state picker filtered by `tools.<pack>` config.** When the user
+  converges on a destination, the skill consults `oat config get tools.ideas`,
+  `tools.project-management`, and `tools.workflows` to filter the available
+  terminal states. Pack-gated outcomes (capture-as-idea, scoped backlog item,
+  project promotion, active-project fold-back) only appear when the
+  corresponding pack is installed.
+- **Destinations playbook.** The full set of terminal-state stanzas — trigger
+  phrases, required template fields, confirmation patterns, handoff targets —
+  lives at `.agents/skills/oat-brainstorm/references/destinations.md` and is
+  consulted by the skill at destination-identification time.
+- **Pack lifecycle.** `oat tools install brainstorm`, `oat tools update --pack
+brainstorm`, and `oat tools remove --pack brainstorm` manage the skill plus
+  visual-companion bundle as a unit. Standard config-write semantics
+  (`tools.brainstorm: true` on install) apply.
+
 ### Auto-sync behavior
 
 All mutation commands (`install`, `update`, `remove`) automatically run `oat sync --scope <scope>` after successful operations. This ensures provider views stay in sync with canonical assets without manual intervention.

package/assets/docs/workflows/ideas/index.md

@@ -9,6 +9,12 @@ Use the ideas workflow when you need a place to think, sketch, or explore before
 
 Ideas are intentionally lighter than projects: they are usually gitignored, personal, and optimized for brainstorming rather than traceable delivery.
 
+## Not Sure If It's an Idea Yet?
+
+> **Direct entry to `oat-idea-ideate` requires an existing target** — either a tracked idea record or an unchecked scratchpad seed in `{IDEAS_ROOT}/scratchpad.md`. For blank-slate brainstorms, route to [`oat-brainstorm`](../../cli-utilities/tool-packs.md) instead.
+
+If the thought is still pre-shape — you don't know whether it should land as a quick scratchpad note, a captured idea, a scoped backlog item, or a full project — start with [`oat-brainstorm`](../../cli-utilities/tool-packs.md). It's the project-independent brainstorming entry point: Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, it runs a structured design conversation and routes the outcome into the right destination (including this ideas workflow if that's where the brainstorm lands). Use ideas directly when you already know the work is "an idea worth tracking" and you want to capture or extend one without going through the dispatcher.
+
 ## Contents
 
 - [Lifecycle](lifecycle.md) - Capture, ideate, refine, and summarize an idea before promotion or discard.

package/assets/docs/workflows/ideas/lifecycle.md

@@ -25,6 +25,16 @@ Each level has its own independent backlog, scratchpad, and active-idea config v
 3. Resume brainstorming: `oat-idea-ideate` (multiple sessions over time)
 4. Finalize: `oat-idea-summarize` (generates summary, updates backlog)
 
+## Relationship to `oat-brainstorm`
+
+The always-on `oat-brainstorm` skill (in the `brainstorm` tool pack) can feed into this workflow. When a brainstorming conversation converges on an ideas-pack destination, the dispatcher follows the same flow above and seeds it with the brainstorming session content:
+
+- **Capture as new idea** — runs `oat-idea-new` Steps 3-7 inline and pre-fills the new idea's `discovery.md` from the brainstorming payload (`What's the Idea?` from the synthesized summary + motivation, `What Would It Look Like?` from the vision, `Open Questions` from the conversation, plus a first session under `Notes & Discussion` headed `### Session: YYYY-MM-DD (seeded from oat-brainstorm)`). The dispatcher then optionally chains into `oat-idea-ideate` Step 4 to keep brainstorming inside the idea, or stops with the session captured.
+- **Extend existing idea** — jumps straight to `oat-idea-ideate` Step 4 (Start New Session) on the chosen idea path and appends the brainstorming transcript as a new session under `Notes & Discussion`.
+- **Summarize directly** — fast path that runs the capture flow silently and then invokes `oat-idea-summarize` end-to-end, producing both the idea record and the summary in one shot. Only offered when the brainstorming conversation produced enough material to summarize directly.
+
+`oat-brainstorm` sets `activeIdea` automatically when its destination lands in this workflow. If the brainstorming conversation converges on a non-ideas destination instead (scoped backlog item, new project, doc-to-path, inline), `oat-brainstorm` does not touch ideas — see [Tool Packs](../../cli-utilities/tool-packs.md) for the full brainstorm pack reference.
+
 ## Directory structure
 
 ```text
@@ -93,6 +103,8 @@ To promote a summarized idea to a Spec-Driven OAT project:
 2. Run the `oat-project-discover` skill and use the idea's `summary.md` as the initial request
 3. Update the ideas backlog entry to Archived with reason: promoted to project
 
+If the work hasn't been summarized as an idea yet — or never was an idea to begin with — `oat-brainstorm`'s **"promote to a new OAT project"** destination is a parallel route. The brainstorm dispatcher scaffolds the project via `oat project new <slug> --mode <mode>`, writes the seeded `discovery.md` directly from the brainstorming payload (Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, Open Questions), and stops with a pointer to `oat-project-quick-start` or `oat-project-design`. It deliberately writes `discovery.md` only — never a partial `design.md` — so the design phase keeps its full collaborative cadence.
+
 ## Initialization
 
 The ideas directory is created automatically by `oat-idea-new` or `oat-idea-scratchpad` on first use. Future: `oat init ideas` will scaffold the directory and copy idea skills into the project.

package/assets/docs/workflows/projects/lifecycle.md

@@ -210,6 +210,26 @@ See the [Workflow preferences section in the Configuration guide](../../cli-util
 - Projects root is stored in `.oat/config.json` (`projects.root`) and can be read via `oat config get projects.root`.
 - Workflow skills prefer `oat config get activeProject` / `oat config get projects.root` rather than reading pointer files directly.
 
+## Brainstorming integration with the project lifecycle
+
+`oat-brainstorm` (in the `brainstorm` tool pack) interacts with the project lifecycle in two distinct ways: it can **seed a brand new project** from a brainstorming conversation when no project is active, or **fold back into an active project** when one is.
+
+### Seeding a new project from a brainstorm
+
+When the brainstorming destination is "promote to a new OAT project", the dispatcher confirms a project slug and a mode (`quick` vs `spec-driven`) with the user, runs `oat project new <slug> --mode <mode>` to scaffold the project, and writes the new project's `discovery.md` directly from the brainstorming payload — Initial Request, Solution Space with approaches considered, Chosen Direction, Key Decisions, Open Questions. It writes `discovery.md` only (never a partial `design.md`), so the design phase keeps its full collaborative cadence and consumes the brainstorm's architectural intent from discovery's Solution Space and Chosen Direction sections during approach reaffirmation. The dispatcher stops with a pointer to `oat-project-quick-start` or `oat-project-design` — it deliberately does not auto-chain into the next phase, so the user makes that transition consciously.
+
+This is a parallel entry path into the Spec-Driven and Quick lanes, not a new lane: the resulting project follows the normal lane it was scaffolded into. The brainstorm-as-seed step is what changes — the user arrives at `oat-project-quick-start` (or `oat-project-design`) with discovery already populated rather than starting from a blank discovery template.
+
+### Folding back into an active project
+
+When `oat-brainstorm` fires while a project is active, it offers a 3-way picker before any pack-filtered destination shows up:
+
+- **Related to the project** → fold the synthesized brainstorming content back into the most-specific upstream artifact (`design.md` if it exists, otherwise `discovery.md`), commit immediately, and print a handoff prompt for the right plan-authoring skill (`oat-project-plan` for spec-driven, `oat-project-quick-start` for quick, `oat-project-revise` when an open PR exists). The fold-back commit is safety-gated: a preflight `git status --porcelain -- "$ARTIFACT_PATH"` checks for dirty state, staging is exactly `git add -- "$ARTIFACT_PATH"` (never `-A`, never globs), and the handoff prompt only prints after the scoped commit succeeds.
+- **Independent of the project** → the active project is acknowledged but doesn't constrain the picker; brainstorm routes through its standard pack-filtered terminal-state options (new project, backlog item, idea, doc-to-path, inline).
+- **Related but supplementary** → write a brainstorming reference file at `.oat/projects/<scope>/<project>/brainstorming/YYYY-MM-DD-<topic>.md`, alongside `pr/` and `reviews/`. No lifecycle artifact is touched.
+
+The fold-back path is what makes "we got to plan and realized the design missed something" recoverable mid-project: the upstream artifact gets updated and committed cleanly, then the user re-runs plan authoring with a "don't refresh, integrate" context that preserves review-table state.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/spec.md`

package/assets/docs/workflows/skills/index.md

@@ -20,7 +20,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Import an existing plan: `oat-project-import-plan`
 - Retroactively capture existing work: `oat-project-capture`
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
-- Manage the repo backlog and reference docs: `oat-pjm-add-backlog-item`, `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
+- Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
+- Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
 - Work on docs surfaces: `oat-docs-bootstrap` (guided bootstrap of a new docs app), `oat-docs-analyze`, `oat-docs-apply`, and `oat-project-document`
 - Generate a shipping digest or scheduled recap: `oat-wrap-up`
 - Research a topic in depth: `deep-research`
@@ -28,7 +29,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Compare options with domain-aware dimensions: `compare`
 - Verify a claim adversarially: `skeptic`
 - Merge multiple analysis artifacts: `synthesize`
-- Capture or refine ideas: `oat-idea-new`, `oat-idea-ideate`, `oat-idea-scratchpad`, `oat-idea-summarize`
+- Capture or refine ideas: `oat-idea-new` (capture a new idea), `oat-idea-ideate` (resume an existing tracked idea or expand a scratchpad seed — not for blank-slate brainstorms; use `oat-brainstorm` for those), `oat-idea-scratchpad`, `oat-idea-summarize`
+- Run a project-independent brainstorming conversation: `oat-brainstorm` — entry point with an explicit activation contract. Hard Activation fires only on the `brainstorm` verb ("let's brainstorm", "brainstorm this", "can we brainstorm X", "help me brainstorm X", or `/oat-brainstorm`); ambiguous exploratory phrasing answers conversationally without the banner and offers structured mode only after sustained exploration. Once entered, runs a structured design conversation (one question at a time, 2-3 approaches with a recommendation) and routes to inline / doc-to-path / idea / backlog item / project handoffs based on installed packs. See [Tool Packs](../../cli-utilities/tool-packs.md) for the brainstorm pack details.
 
 ## If You Are Trying To...
 
@@ -72,6 +74,10 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-idea-scratchpad`
     - `oat-idea-summarize`
 
+=== "Brainstorming"
+
+    - `oat-brainstorm`
+
 === "Docs and instructions"
 
     - `oat-docs-bootstrap`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.60",
-  "docs-config": "0.0.60",
-  "docs-theme": "0.0.60",
-  "docs-transforms": "0.0.60"
+  "cli": "0.0.64",
+  "docs-config": "0.0.64",
+  "docs-theme": "0.0.64",
+  "docs-transforms": "0.0.64"
 }