Help us improve
Share bugs, ideas, or general feedback.
From brainbrew-devkit
Sets up workflow templates like develop and devops chains for agents, manages flows, validates configs, lists active chains, and adds team nodes.
npx claudepluginhub brainbrewlabs/brainbrew-devkit --plugin brainbrew-devkitHow this skill is triggered — by the user, by Claude, or both
Slash command
/brainbrew-devkit:chain-builderThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Use MCP tool:**
Chains multi-step agent workflows where each step receives the previous output as context. Use for sequential data transformation, code analysis pipelines, or multi-prompt orchestration.
Validates, runs, and debugs multi-agent YAML workflows. Use when orchestrating AI agents, configuring routing, or setting up human-in-the-loop gates.
Composes Claude Code skills into automated pipelines for multi-step workflows like feature development, bug fixes, content launches, and project bootstraps. Supports auto-detection, dynamic step selection, progress tracking, and CLI management.
Share bugs, ideas, or general feedback.
Use MCP tool:
mcp__brainbrew__template_bump(template: "develop")
| Template | Chain |
|---|---|
develop | planner → plan-reviewer → implementer → parallel-review (team) → tester → git-manager |
devops | code-scanner → security-auditor → test-runner → deployer → monitor |
marketing | researcher → content-writer → editor → seo-optimizer → publisher |
research | topic-researcher → source-gatherer → analyzer → synthesizer → report-writer |
docs | code-scanner → doc-generator → doc-reviewer → formatter → publisher |
support | ticket-classifier → router → knowledge-searcher → response-drafter → reviewer |
data | data-collector → cleaner → analyzer → visualizer → reporter |
moderation | content-scanner → classifier → flagger → reviewer → actioner |
review | code-reviewer → END |
skill-dev | skill-finder → skill-creator → skill-reviewer (PASS = END, FIXES → skill-improver) |
minimal | hooks only (add your own) |
List chains and show the active one:
mcp__brainbrew__chain_list()
View active chain config:
cat .claude/chains/$(grep 'active:' .claude/chain-config.yaml | cut -d' ' -f2).yaml
mcp__brainbrew__chain_validate()
Checks:
.claude/agents/{name}.md filesname and agent fields.claude/agents/Returns ✅ PASS or list of ❌/⚠ issues.
The project uses a pointer file + chain directory:
.claude/chain-config.yaml # pointer to active chain
.claude/chains/
develop.yaml # chain definition (hooks + flow)
discovery.yaml # another chain
Pointer file (.claude/chain-config.yaml):
active: develop
chains_dir: .claude/chains/
Each chain file in .claude/chains/ has the same format:
hooks:
PostToolUse:
- plugin:post-agent.cjs
SubagentStart:
- plugin:subagent-start.cjs
SubagentStop:
- plugin:subagent-stop.cjs
saveOutput:
- explore
- scout
flow:
agent-name:
routes:
next-agent: "When to go here"
decide: |
AI routing rules
The saveOutput: list at the top level specifies which agent types always save their output. The explore agent is saved by default even without this field. Outputs go to .claude/outputs/{agent}/{timestamp}.md.
mcp__brainbrew__chain_list()
Shows all chains and which is active.
mcp__brainbrew__chain_switch(chain: "discovery")
Takes effect immediately for subsequent agent runs. Use chain_switch when you want to change the active chain without enforcing the first agent.
mcp__brainbrew__chain_run(chain: "discovery", session_id: "{current_session_id}")
Switches to the chain, clears previous chain state, and enforces the first agent immediately. PreToolUse and Stop hooks will block until the first agent is spawned. Use chain_run as the preferred way to start a chain from scratch.
There are two node types: agent (default) and team.
Edit the active chain file in .claude/chains/:
flow:
new-agent:
routes:
next-agent: "Success — move forward"
fallback: "Failed — try alternative"
decide: |
If SUCCESS → "next-agent"
If FAILED → "fallback"
Then update the previous agent's routes to point to the new agent.
| Field | Required | Purpose |
|---|---|---|
routes | Yes | Map of agent-name: "description". Multiple routes allowed |
decide | No | AI prompt sent to Haiku to pick route based on agent output |
reset_counters | No | Reset loop counters when routing (for approval gates). Loop protection is off by default. |
context | No | Extra context injected into the agent's system-reminder via SubagentStart. Supports inline text or multiline block (|). |
saveOutput | No | Set to true to save this agent's output to .claude/outputs/{agent}/{timestamp}.md regardless of the top-level saveOutput: list. |
next | No | Legacy: simple next agent (use routes instead) |
on_fail | No | Legacy: fallback on failure keywords |
on_issues | No | Legacy: fallback on issue keywords |
decide prompt exists and output > 50 chars → Haiku analyzes output against routing rules{"route": "agent-name", "reason": "..."}"END" stops the chainrunner.cjs enforces pending chain steps before running any hook:
currentAgent is set), any non-Agent tool call is blocked with a reminder to spawn the required agent first.skip chain or /skip-chain in any message to clear the pending state immediately.Chain state is stored per session in ~/.claude/tmp/chain-state/{sessionId}.json with two fields: currentAgent (the pending next agent) and chainBlockCount (how many times the current step has been blocked).
When an agent completes, PostToolUse saves its full output to ~/.claude/tmp/agent-outputs/{agentId}.md. Before the next agent spawns, the PreToolUse hook (runner.cjs) reads this file and injects it directly into the new agent's prompt as a ## Previous Agent Output ({type}) section via updatedInput. This gives every agent in the chain automatic access to what the previous agent produced, without any manual wiring.
Agent teams run multiple agents in parallel at a chain step. Each teammate gets its own context and they can communicate with each other.
flow:
parallel-review:
type: team
teammates:
- name: code-quality
agent: code-reviewer
prompt: "Review code for bugs, quality, and adherence to plan"
- name: security-check
agent: security-scan
prompt: "Scan for security vulnerabilities and exposed secrets"
routes:
tester: "All reviews passed"
implementer: "Issues found, needs fixes"
decide: |
If ALL reviews PASSED with no issues → "tester"
If ANY review found bugs, issues, vulnerabilities → "implementer"
| Field | Required | Purpose |
|---|---|---|
type | Yes | Must be team |
teammates | Yes | Array of teammate definitions |
routes | Yes | Same as agent node — where to go after team completes |
decide | No | AI routing rules applied to synthesized team output |
| Field | Required | Purpose |
|---|---|---|
name | Yes | Unique identifier for this teammate |
agent | Yes | Agent type to spawn (must exist in .claude/agents/) |
prompt | No | Specific instructions for this teammate's focus area |
model | No | Override model (sonnet, opus, haiku) |
type: teamdecide rules| Use Teams | Use Sequential |
|---|---|
| Independent tasks (review + security + tests) | Tasks that depend on each other |
| Different perspectives on same work | Each step builds on previous output |
| Speed matters — parallel is faster | Order matters — must be sequential |
| Teammates don't edit same files | Agents modify shared files |
Parallel code review (security + quality + performance):
comprehensive-review:
type: team
teammates:
- name: security
agent: security-scan
prompt: "Focus on vulnerabilities, injection risks, exposed secrets"
- name: quality
agent: code-reviewer
prompt: "Focus on bugs, logic errors, naming, patterns"
- name: performance
agent: code-reviewer
prompt: "Focus on performance bottlenecks, memory leaks, N+1 queries"
routes:
tester: "All clear"
implementer: "Issues found"
Parallel research:
parallel-research:
type: team
teammates:
- name: frontend-scout
agent: scout
prompt: "Explore frontend architecture, components, state management"
- name: backend-scout
agent: scout
prompt: "Explore backend architecture, APIs, database schema"
- name: test-scout
agent: scout
prompt: "Explore test coverage, testing patterns, CI setup"
routes:
planner: "Research complete, ready to plan"
mcp__brainbrew__template_bump(template: "minimal").claude/agents/{name}.md.claude/skills/{name}/SKILL.md.claude/chains/{name}.yamlmcp__brainbrew__chain_run(chain: "name", session_id: "{current_session_id}") (recommended) or mcp__brainbrew__chain_switch(chain: "name") to switch without enforcementHooks run in order through 2 layers:
| Layer | Source | When |
|---|---|---|
| 1. User hooks | .claude/hooks.yaml | If file exists |
| 2. Chain hooks | .claude/chains/{name}.yaml → hooks: section | Only when chain is active |
User hooks — create .claude/hooks.yaml to add hooks at any lifecycle stage:
PreToolUse:
- plugin:safety-guard.cjs
- ./my-linter.js
SessionStart:
- plugin:session-start.cjs
- ./setup-env.js
SessionEnd:
- plugin:session-end.cjs
PostToolUse:
- ./my-logger.js
SubagentStart:
- ./inject-context.js
SubagentStop:
- ./my-validator.js
UserPromptSubmit:
- ./my-prompt-filter.js
Stop:
- ./cleanup.js
Notification:
- ./my-notifier.js
Scripts go in .claude/hooks/. Each receives stdin JSON from Claude Code.
Return {"decision": "block", "reason": "..."} to block, or exit 0 to pass through.
Available lifecycle events: PreToolUse, PostToolUse, SubagentStart, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, Stop, Notification
Plugin scripts (opt-in via plugin: prefix in hooks.yaml):
| Script | Purpose |
|---|---|
plugin:safety-guard.cjs | Block dangerous commands (rm -rf, git push --force, DROP TABLE, etc.) |
plugin:session-start.cjs | Session initialization and context setup |
plugin:session-end.cjs | Session cleanup |
Chain hooks — defined inside chain files (.claude/chains/{name}.yaml), only run when that chain is active:
hooks:
PostToolUse:
- plugin:post-agent.cjs
SubagentStart:
- plugin:subagent-start.cjs
SubagentStop:
- plugin:subagent-stop.cjs
| Prefix | Resolves to |
|---|---|
plugin: | Plugin's built-in scripts |
./ | .claude/hooks/ in project |
/absolute | Absolute path |
After template_bump, review and tune these files:
.claude/chains/{name}.yaml)decide promptsreset_counters for approval gates.claude/agents/*.md)description for your project contexttools list (add/remove as needed)skills: frontmatter.claude/skills/*/SKILL.md).claude/skills/common/mcp__brainbrew__chain_validate()
Plugins extend Claude Code sessions with background tools (notifications, cost tracking, sandboxing, etc.).
Browse available plugins:
mcp__brainbrew__plugin_list()
Search by keyword:
mcp__brainbrew__plugin_list(query: "docker")
mcp__brainbrew__plugin_list(query: "cost")
Each result includes the plugin path. Read its CLAUDE.md for install instructions — the AI handles the rest.
To customize a plugin, copy it into the project:
cp -r <plugin-path> .claude/plugins/<name>/
Agents can save their output to .claude/outputs/{agent}/{timestamp}.md. There are two ways to enable this:
Top-level list — add a saveOutput: section to the chain YAML to auto-save specific agent types:
saveOutput:
- explore
- planner
Per-node flag — set saveOutput: true on any agent node in the flow:
flow:
scout:
saveOutput: true
routes:
planner: "Research complete"
The explore agent is always saved by default even without explicit config.
Each saved file has a YAML frontmatter block followed by the agent's prompt and output:
---
agent: planner
id: {agentId}
tokens: 12450
duration_ms: 34200
tools_used: 8
timestamp: 2026-04-11T10:15:22.000Z
session: {sessionId}
next: implementer
description: "Create implementation plan for feature X"
tool_breakdown:
Read: 4
Bash: 2
Grep: 2
files_read:
- /path/to/file.ts
files_modified: []
files_created: []
bash_commands:
- "git status"
grep_searches:
- "pattern in src/"
---
## Prompt
{agent prompt}
## Output
{agent output}
Agent stats (tool_breakdown, files_read, files_modified, files_created, bash_commands, grep_searches) are parsed from the agent's JSONL transcript by SubagentStop and stored in ~/.claude/tmp/agent-stats/{agentId}.json before the output file is written.
.claude/outputs/
explore/
2026-04-10T22-36-35.md
planner/
2026-04-11T10-15-22.md
scout/
2026-04-11T11-00-01.md
Tell user:
Workflow ready! You can:
- "Create an agent for X"
- "Create a skill for Y"
- "Add a team node for parallel review"
- "Add agent context for X" (context injection)
- "Show the chain flow"
- "List available plugins" (plugin_list)