feat: add project-independent brainstorming skill and pack#70
Open
feat: add project-independent brainstorming skill and pack#70
Conversation
tkstang
added a commit
that referenced
this pull request
May 2, 2026
tkstang
added a commit
that referenced
this pull request
May 3, 2026
tkstang
force-pushed
the
feat/independent-brainstorming-mode
branch
from
3a80c5c to
69fd51f
Compare
tkstang
added a commit
that referenced
this pull request
May 4, 2026
tkstang
force-pushed
the
feat/independent-brainstorming-mode
branch
from
0b4190c to
c0c08dd
Compare
… locked frontmatter)
…script, and scaffold skill
… and default-on set
…ogfood backlog item
Replaces the always-on "any exploratory phrasing" activation model with
an explicit three-tier contract that separates brainstorm-quality
response (the default for any exploratory phrasing) from the OAT
brainstorm banner (a workflow commitment marker, reserved for explicit
hard-activation triggers or user confirmation).
Activation Contract tiers:
- Hard Activation: /oat-brainstorm or explicit `brainstorm` verb with
topic ("let's brainstorm X", "brainstorm this", "can we brainstorm
X", "help me brainstorm X"). Banner + mode + full Process flow.
- Soft Exploratory Path: ambiguous exploratory phrasing ("help me think
through", "I've been thinking about", "what if we", "I'm trying to
figure out"). Respond conversationally with brainstorm-quality
reasoning, no banner. After ≥2 sustained exploratory turns, append
the soft offer once.
- No Activation: advisory / review / debug / PR / status /
implementation / active-workflow questions ("thoughts?", "what's
your take?", "does this seem right?"). Direct response, no banner,
no offer.
Other changes:
- Frontmatter description tightened to explicit brainstorm-verb
triggers only (drops weak "I've been thinking about" / "what if we
did" generic openers).
- BLOCKED Activities collapses the two redundant visual-companion
rules into one combined rule (resolves prev1-review minor #1).
- Self-Correction Protocol gains a new top rule for printing the
banner on Soft / No Activation paths.
- Step 1: Activate gates the Process flow on the Activation Contract.
- dogfood-results.md gains an Activation Anti-Cases section (12 rows
across the three tiers) for live-dogfood verification.
- apps/oat-docs/docs/workflows/skills/index.md adds a "resume an
existing idea or expand a scratchpad seed" hint to the
oat-idea-ideate catalog entry (resolves prev1-review minor #2).
- apps/oat-docs/docs/workflows/ideas/index.md adds an explicit
direct-entry note that oat-idea-ideate requires an existing target
(resolves prev1-review minor #3).
- apps/oat-docs/docs/cli-utilities/tool-packs.md brainstorm pack
description rewritten to reflect the activation contract.
- 5 lockstep public packages bumped 0.0.60 → 0.0.61.
Per AGENTS.md, the oat-brainstorm SKILL.md `version:` is PR-scoped and
was already bumped to 1.0.1 during prev1; not double-bumped here.
Verified:
- pnpm release:validate: pass on all 5 public packages at 0.0.61
- pnpm format: pass
- pnpm lint: pass
- pnpm type-check: pass
- pnpm --filter @open-agent-toolkit/cli test: 1463/1463 pass
- pnpm oat:validate-skills: oat-brainstorm and oat-idea-ideate
validate clean; pre-existing 6 unrelated failures unchanged.
The prev2 commit introduced a bare colon in the unquoted YAML scalar
("the brainstorm verb: /oat-brainstorm, ..."), which YAML parsers
interpreted as a nested mapping inside the description value, producing
"mapping values are not allowed in this context". The validate-skills
linter only checked length and lead-word constraints so it didn't
surface the issue, but any consumer that actually loads the YAML
(provider sync, skill resolver) failed.
Replace "verb: \`/oat-brainstorm\`" with "verb, including
\`/oat-brainstorm\`" so the description reads as one unbroken scalar.
Description stays at 475 chars (under the 500 limit).
…iance PR #71 (`feat(skills): make end-of-lifecycle skills model-invokable`) removed the `disable-model-invocation` key from four skills to enable model invocation, but `pnpm oat:validate-skills` still requires the key as mandatory frontmatter (see `packages/cli/src/validation/skills.ts:351-364`). Validation has been broken for all consumers since PR #71 merged. Restore the key explicitly with the value that matches PR #71's intent (`false` = model-invokable). Also fix `oat-pjm-update-repo-reference` which was missing the same key pre-PR-71 (same end-of-lifecycle family, same intent). Skills bumped (PR-scoped per AGENTS.md): - oat-pjm-add-backlog-item: 1.1.0 → 1.1.1, added `disable-model-invocation: false` - oat-project-document: 1.4.0 → 1.4.1, added `disable-model-invocation: false` - oat-project-pr-final: 1.4.0 → 1.4.1, added `disable-model-invocation: false` - oat-project-summary: 1.1.0 → 1.1.1, added `disable-model-invocation: false` - oat-pjm-update-repo-reference: 1.1.0 → 1.1.1, added `disable-model-invocation: false` Also fixes one unrelated pre-existing validator failure surfaced while investigating: oat-project-spec's description started with "Optional standalone skill..." which fails the lead-word rule ("Use when", "Run when", "Trigger when"). Rewrote the lead to start with "Use when discovery is complete..." (semantics preserved); skill bumped 2.0.0 → 2.0.1. Out of scope of the model-invocation thread but small enough to fix in the same commit so the validator returns clean exit 0. Lockstep public packages bumped 0.0.61 → 0.0.62. Verified: - pnpm oat:validate-skills: OK (48/48 skills) - pnpm release:validate: pass on all 5 public packages at 0.0.62 - pnpm format / lint / type-check: pass Strict-YAML validation gap noted in `bl-f19a` (separate follow-up) will catch a related class of bugs at the parser level.
Address the 3 Important + 2 Minor findings from prev2-review-2026-05-04.md: - prev2-t04 (I1): remove `thoughts?` from the soft/ambiguous example list in oat-brainstorm/SKILL.md frontmatter and apps/oat-docs tool-packs.md. Same word listed under both Soft Exploratory Path and No Activation contradicted the activation contract; the No Activation classification is correct so the Soft list now drops it. - prev2-t05 (I2): scrub CODEX_CI from the spawned child env in visual-companion-smoke.test.ts. start-server.sh auto-sets FOREGROUND=true when CODEX_CI is present (intentional for real Codex usage), but the harness resolves on the child's `close` event — a foreground server never closes, causing all 5 smoke tests to time out at 30s under Codex CI. start-server.sh runtime behavior is unchanged. - prev2-t08 (m2): add three missing spaces around inline-code spans in the bl-f19a backlog item description (`verb:` was, scalar. `pnpm`, raised `mapping`). Verified: - CODEX_CI=1 pnpm --filter @open-agent-toolkit/cli exec vitest run src/integration/visual-companion-smoke.test.ts → 5/5 pass - pnpm oat:validate-skills → 48/48 pass - rg `thoughts?` confirms the string only appears in No Activation contexts.
Refresh OAT bookkeeping after the prev2-review fix batch: - state.md frontmatter: oat_current_task → null (all 5 fix tasks done), oat_last_commit → 877fbdc, oat_project_state_updated → 2026-05-05T01:10Z. - state.md body: status / progress / Next Milestone reflect the completed prev2-review batch and the orchestrator-owned push + re-review. - plan.md: prev2 Reviews row → fixes_completed; phase p-rev2 status → complete (8/8); ## Implementation Complete totals → 43/43 with the new commit hash. - implementation.md: Progress Overview prev2 row → complete 8/8; total → 43/43; oat_current_task_id → null; appended `Revision Completed: prev2 Review Fixes` section with per-task outcomes and verification. - .oat/state.md regenerated via `pnpm run cli -- state refresh`. Resolves prev2-review m1 (bookkeeping drift).
tkstang
force-pushed
the
feat/independent-brainstorming-mode
branch
from
edd47e0 to
8bd6125
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ships
oat-brainstorm, a new always-on user-invocable skill in a new dedicatedbrainstormtool pack, that turns OAT into a first-class destination for project-independent brainstorming conversations. The skill activates proactively on exploratory phrasing ("I've been thinking about", "what if we did", design uncertainty), runs a structured design conversation without requiring an idea or project artifact up front, and ends in a pack-aware terminal-state picker that hands off to existing OAT skills (oat-idea-*,oat-pjm-add-backlog-item,oat-project-*) or to inline / doc-to-path outcomes that work in any repo. Closesbl-53f0.The change also generalizes default-scope behavior across the OAT installer via a new
PACK_METADATAmechanism (ADR-017), so future user-default-scope packs can opt in by adding a single metadata entry rather than hardcoding pack names in scope-resolution code. The visual-companion bundle is a port of the MIT-licensedsuperpowers:brainstorming@5.0.7companion with OAT-aligned persistence-path resolution; attribution is inNOTICES.md.Goals / Non-Goals
Goals (from
bl-53f0acceptance criteria):disable-model-invocation: falseplus a tightly-scoped description string.oat config get tools.<pack>— done; same canonical signaloat-project-documentalready uses.NOTICES.mdextended with verbatim-vs-patched file enumeration..agents/skills/oat-brainstorm/references/dogfood-results.md); live dogfood follow-up captured as backlog itembl-7d5b.Non-Goals:
oat-idea-*skills — they continue to own conversational ideation when an idea exists.oat-project-revise).corepack consolidation under the newPACK_METADATAmechanism — flagged as a follow-up in ADR-017.Changes
Phase 1 — Pack-metadata mechanism (4 tasks):
PackMetadatainterface +PACK_METADATAmap +resolvePackDefaultScopehelper inpackages/cli/src/commands/init/tools/shared/skill-manifest.ts.buildUserScopeChoices(interactive picker) and the non-interactive branch ofresolvePackScopes.Phase 2 — Brainstorm pack registration + skill scaffolding + visual-companion bundle (8 tasks):
brainstormpack across the install/update/remove pipelines:BRAINSTORM_SKILLSmanifest constant;PackNametype union extended;bundle-assets.shSKILLS array; cascading exhaustive-switch updates acrossBUNDLED_PACK_MEMBERS,BUNDLED_PACK_ASSETS,install-sync-context,scan-tools,VALID_PACKS,PACK_DESCRIPTIONS; runInitTools dispatcher imports + dependency interface + default deps + dispatch branch; update/remove handlers; interactive picker description;oat init toolsdefault-on set entry.packages/cli/src/commands/init/tools/brainstorm/mirroring theideas/anddocs/patterns.superpowers:brainstorming@5.0.7(MIT):server.cjs,stop-server.sh,frame-template.html,helper.jsbyte-for-byte verbatim;start-server.shpatched only for OAT-managed persistence paths.references/destinations.md) with per-destination stanzas covering trigger phrases, required template fields, confirmation patterns, handoff targets, and "keep brainstorming" rules.templates/brainstorm-doc.md).NOTICES.mdextended with visual-companion attribution subsection.Phase 3 — Skill flow implementation (7 tasks):
.agents/skills/oat-brainstorm/SKILL.mdend-to-end: tightened always-on description, mode assertion, progress indicators, 9-step process flow, all 9 handoff branches (inline / doc-to-path / capture-as-new-idea / extend-existing-idea / summarize-idea-directly / scoped-backlog-item / promote-to-new-OAT-project / active-project router / fold-back / active-project reference file).git status --porcelain, scopedgit add --, three-option dirty-tree picker, conditional handoff prompt) — word-for-word aligned with design.Phase 4 — Documentation, dogfood, release validation (5 tasks):
apps/oat-docs/docs/cli-utilities/tool-packs.md; brainstorm entries inapps/oat-docs/docs/workflows/skills/index.md.dogfood-results.md; live-dogfood follow-up captured asbl-7d5b.0.0.59(rebased overf33c6597which had already shipped0.0.58)..oxfmtrc.jsoncignore patterns for bundled MIT-port scripts and bundled docs.Phase 5 — Final-review fixes (8 tasks):
tools.brainstormregistered end-to-end in config schema (validPacks / effective defaults / config command catalog).${SKILL_DIR}resolution with documented user/project fallback..oat/brainstorm/added to managed gitignore vialocalPaths.oat state refresh+ project state.md body matches frontmatter).bl-7d5bcreated with embedded copy ofdogfood-results.md.current-state.mdworkflow path references andoat tools installpack list updated.Documentation sync (separate commit):
apps/oat-docs/docs/workflows/ideas/index.md.apps/oat-docs/docs/workflows/ideas/lifecycle.mdcovering capture / extend / summarize routes from a brainstorm.apps/oat-docs/docs/workflows/projects/lifecycle.mdcovering both new-project seeding and active-project fold-back.bl-53f0closed, ADR-017 added,current-state.mdupdated,backlog/completed.mdentry added.Verification
pnpm release:validate— pass on all 5 public packages at0.0.59pnpm format— passpnpm lint— pass (0 warnings, 0 errors)pnpm type-check— pass (10 packages)pnpm --filter @open-agent-toolkit/cli test— pass (1459 tests across 163 files)pnpm build:docs— passpnpm oat:validate-skills—oat-brainstormvalidates clean (the two pre-existing failures onoat-pjm-update-repo-referenceandoat-project-specare unrelated baseline issues)pnpm cli config get tools.brainstorm— returnsfalse(wasUnknown config keybefore fix)git check-ignore .oat/brainstorm/test/page.html— exit 0Reviews
reviews/archived/p01-code-review-2026-05-01.mdreviews/archived/p02-code-review-2026-05-01.mdreviews/archived/p03-code-review-2026-05-01.mdreviews/archived/p04-code-review-2026-05-01.mdreviews/archived/p05-code-review-2026-05-02.mdreviews/archived/final-review-2026-05-02-v2.mdreviews/archived/artifact-design-review-2026-05-01.mdreviews/archived/artifact-plan-review-2026-05-01.mdThe first
finalcode review (v1, 2026-05-02) flagged 6 Important + 2 Medium + 1 Minor — all 9 converted to fix tasks (Phase 5) and closed in the v2 narrowed re-review (verdict: pass). A v3 final review surfaced 1 Important + 2 Medium of post-pass bookkeeping drift; the cycle limit (3) was exceeded, the v3 reviewer explicitly said no code changes were needed, and the user opted to apply fixes inline as a single bookkeeping commit — recorded inimplementation.mdReview History.Manual dogfood plan (pre-merge)
The user noted they will manually do some dogfooding before merging using a vault-copied reference at
~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Vault/02 - Projects/Open Agent Toolkit/References/dogfood-results.md(outside the repo, not committed). Live dogfood follow-up — especially the fold-back commit safety contract against a real dirty tree — is captured as backlog itembl-7d5b.References
discovery.mddesign.mdplan.mdimplementation.mdsummary.md.agents/skills/oat-brainstorm/SKILL.md.oat/repo/reference/decision-record.mdbl-53f0(closed in this PR)bl-7d5b