brainstorm-toolkit

brainstorm-toolkit

Cross-tool plugin for Claude Code + GitHub Copilot: focused, low-token skills for brainstorming, SDLC, eval-driven development, and repo onboarding. Single AGENTS.md and TASKS.md contract so both agents work from the same source of truth.

Why this exists

Most AI-agent task systems bolt on heavyweight task databases, multi-agent orchestrators, and inline templates that balloon every command to hundreds of lines. brainstorm-toolkit goes the other direction:

• One skill = one SKILL.md file, deliberately short (37–250 lines each).
• Markdown-native contracts — AGENTS.md, TASKS.md, GOTCHAS.md, .claude/project.json — so Claude Code, GitHub Copilot, Cursor, and friends all read the same files.
• No central registry, no dual persistence, no ralph-loop autonomous runners by default. /sdlc is the heaviest thing in here and it's still one file.

Install

Option A — Claude Code plugin

If you use the Claude Code plugin system, add this repo as a marketplace source or install directly:

# In Claude Code:
/plugin marketplace add <this-repo-url>
/plugin install brainstorm-toolkit

Option B — setup.sh (Claude, Copilot, or both)

For Copilot users, or if you prefer file-based installs:

# Clone this repo once, anywhere
git clone <this-repo-url> ~/brainstorm-toolkit

# Inside any target repo:
bash ~/brainstorm-toolkit/setup.sh --target . --tools both

setup.sh copies:

• skills/* → <target>/.claude/skills/<name>/ (Claude), <target>/.github/skills/<name>/ (Copilot), and <target>/.agents/skills/<name>/ (Codex), for skills whose metadata.brainstorm-toolkit-applies-to includes that tool. When a Copilot-optimized override exists in copilot/skills/<name>/, that version is installed for Copilot instead of the canonical one; Codex prefers a codex/skills/<name>/ override, then the Copilot overlay, then the canonical. The full skill directory is copied so bundled scripts, assets, and references stay available.
• Some Copilot-distributed skills are intentionally manual-only and set disable-model-invocation: true, which keeps them available as slash commands without making them auto-load on semantic matching.
• Legacy .github/prompts/*.prompt.md files from older installs are removed during Copilot installs so the workspace stops advertising prompt-file shims.
• agents/* → <target>/.claude/agents/ (Claude-only helper agents; VS Code can also discover Claude-format agents from .claude/agents/ when needed).
• scripts/* → <target>/scripts/.
• templates/AGENTS.md.template → <target>/AGENTS.md if missing. Symlinks CLAUDE.md → AGENTS.md on POSIX, else copies.
• templates/TASKS.md.template → <target>/TASKS.md if missing.
• templates/CHEATSHEET.md.template → <target>/CHEATSHEET.md if missing. This is the printable companion to /cheatsheet; once present, setup leaves user edits alone.
• templates/project.json.example → <target>/.claude/project.json.example (left for you to rename and edit).

Re-running setup.sh is safe — it skips existing files unless you pass --force. Install only for one tool with --tools claude or --tools copilot.

Windows note

setup.sh is bash; run it under WSL, Linux, or macOS. Windows-native git handles symlinks inconsistently, so the CLAUDE.md → AGENTS.md link falls back to a copy outside POSIX environments.

The cross-tool contract

Every consumer repo gets four shared files:

File	Purpose	Read by
AGENTS.md	Architecture + agent conventions	Claude Code (via CLAUDE.md copy/symlink), Copilot, Cursor, Codex
TASKS.md	Markdown checkbox task queue	All agents, humans, GitHub UI
GOTCHAS.md	Project-specific pitfalls	/gotcha, /sdlc sanity check
.claude/project.json	Runner config (tests, logs, eval)	/test-check, /eval-harness, /sdlc

Every project.json key is optional — skills skip steps gracefully when config is missing. A repo with no project.json still gets useful behavior from /brainstorm, /task, /gotcha, etc.

Skills