chain-builder

Chain Builder

Set Up a Workflow Template

Use MCP tool:

mcp__brainbrew__template_bump(template: "develop")

Templates

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)

Show Chain Flow

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

Validate Chain Config

mcp__brainbrew__chain_validate()

Checks:

• All agents in flow have matching .claude/agents/{name}.md files
• Team nodes have valid teammates with name and agent fields
• Teammate agents exist in .claude/agents/
• All routes point to nodes defined in the flow
• No dead-end nodes (nodes without routes)

Returns ✅ PASS or list of ❌/⚠ issues.

Chain Config Structure

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.

List Chains

mcp__brainbrew__chain_list()

Shows all chains and which is active.

Switch Active Chain

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.

Run a Chain (Recommended)

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.

Flow Node Types

There are two node types: agent (default) and team.

Add Agent Node

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.

Agent Node Fields

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

How Routing Works

1. Agent completes → PostToolUse hook fires
2. If decide prompt exists and output > 50 chars → Haiku analyzes output against routing rules
3. Haiku returns {"route": "agent-name", "reason": "..."}
4. If Haiku fails → fallback to keyword matching (pass/approved/success vs fail/error/issues)
5. If no match → default to first route
6. Route "END" stops the chain

Chain Enforcement

runner.cjs enforces pending chain steps before running any hook:

• PreToolUse: If a chain step is pending (currentAgent is set), any non-Agent tool call is blocked with a reminder to spawn the required agent first.
• Stop: If a chain step is pending, the session stop is blocked with a MANDATORY NEXT STEP reminder.
• Release after 3 blocks: If the same event is blocked 3 times, the pending state is cleared and execution is released with a hint to spawn the agent.
• Bypass: Type 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).

Agent Communication

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.

Add Agent Team Node

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"

Team Node Fields

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

Teammate Fields

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)

How Teams Work

1. Previous agent completes → hook detects next node is type: team
2. Hook emits MANDATORY NEXT STEP instructing Claude to create an agent team
3. Claude spawns all teammates in parallel using TeamCreate
4. Each teammate works independently with its own context
5. After all teammates finish, results are synthesized
6. Hook routes to next agent based on decide rules

When to Use Teams vs Sequential Agents

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

Team Examples

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"

Create Custom Workflow

1. Start with: mcp__brainbrew__template_bump(template: "minimal")
2. Create agents: .claude/agents/{name}.md
3. Create skills: .claude/skills/{name}/SKILL.md
4. Edit active chain: .claude/chains/{name}.yaml
5. Run chain: mcp__brainbrew__chain_run(chain: "name", session_id: "{current_session_id}") (recommended) or mcp__brainbrew__chain_switch(chain: "name") to switch without enforcement
6. Restart Claude Code session

Hook System (2 Layers)

Hooks 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

Script Path Resolution

Prefix	Resolves to
plugin:	Plugin's built-in scripts
./	.claude/hooks/ in project
/absolute	Absolute path

Post-Bump Tuning

After template_bump, review and tune these files:

1. Chain Config (.claude/chains/{name}.yaml)

• Adjust routing rules in decide prompts
• Add/remove agents from flow
• Configure reset_counters for approval gates

2. Agent Definitions (.claude/agents/*.md)

• Update description for your project context
• Adjust tools list (add/remove as needed)
• Add project-specific skills in skills: frontmatter

3. Skills (.claude/skills/*/SKILL.md)

• Update skill instructions for your stack/conventions
• Add project-specific rules and patterns
• Reference common patterns from .claude/skills/common/

4. Validate

mcp__brainbrew__chain_validate()

Install Plugins

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>/

Output Saving

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.

Output File Format

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.

Output Directory Structure

.claude/outputs/
  explore/
    2026-04-10T22-36-35.md
  planner/
    2026-04-11T10-15-22.md
  scout/
    2026-04-11T11-00-01.md

After Setup

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)