Generate .grepai/config.yaml through deep project analysis
bc-rules-organizer
sonnet
Create and optimize .claude/rules/*.md files
1. /brewcode:install
Purpose: Interactive installer for all dependencies required for brewcode plugin operation. Checks and installs brew, coreutils, jq, as well as optional ollama, bge-m3 and grepai.
Parameter
Value
Arguments
None
Context
fork
Model
sonnet
Dependencies
None (first command in chain)
Allowed tools
Read, Bash, AskUserQuestion
Created Files
Command does not create files directly -- it installs system packages and utilities.
Components
Component
Type
Purpose
brew
required
Package manager
coreutils + timeout
required
Timeouts for scripts
jq
required
JSON processor for hooks
ollama
optional
Local embeddings server
bge-m3
optional
Multilingual embeddings model (~1.2GB)
grepai
optional
CLI for semantic code search
Bash Scripts
Script Command
Purpose
install.sh state
Current state of all components
install.sh check-updates
Check for available updates
install.sh check-timeout
Check for timeout command presence
install.sh update-all
Update outdated components
install.sh required
Install brew, coreutils, jq
install.sh timeout
Create symlink for timeout
install.sh grepai
Install ollama, bge-m3, grepai
install.sh summary
Final summary
Agents
Does not use subagents.
Workflow
Phase 1: State Check -- check state of all components
Phase 2: Updates Check -- check for updates, prompt user
Purpose: Creates detailed task specification (SPEC.md) through parallel codebase research and interactive clarification with user. Includes quorum specification review.
Parameter
Value
Arguments
Text description of task or path to requirements file
Name slug: lowercase, underscores (e.g., auth_feature)
Directory: .claude/tasks/{TIMESTAMP}_{NAME}_task/
Usage Example
/brewcode:spec "Implement authorization via JWT tokens"
/brewcode:spec requirements/auth-feature.md
4. /brewcode:plan
Purpose: Creates execution plan (PLAN.md) from specification (SPEC.md) or Plan Mode file. Includes phase breakdown, agent assignment, quorum plan review and requirements coverage verification.
Parameter
Value
Arguments
Path to task directory, SPEC.md, or .claude/plans/LATEST.md
Quick reference (path to latest task added at beginning)
v3 Phase Files
In v3, phase details are moved out of PLAN.md into individual files under phases/. PLAN.md contains only a slim Phase Registry table with phase name, status, agent, and parallel group. The manager never reads phases/ files directly -- only agents receive the phase file path via Task API.
Bash Scripts
Does not use custom scripts. Validation through direct Bash commands.
Agents
Agent
Count
Purpose
Plan
1
Quorum plan review (coverage check)
brewcode:architect
1
Quorum plan review (architecture, tech choices, dependencies)
brewcode:reviewer
1-2
Quorum plan review (quality, risks) + traceability verification
Purpose: Starts task execution by PLAN.md phases with infinite context through automatic handoff. In v3, uses Task API (TaskCreate/TaskUpdate/TaskList) for phase management instead of reading phases inline. Plugin hooks provide knowledge injection into agents, compaction when approaching context limit and automatic continuation.
Parameter
Value
Arguments
[task-path] (path to PLAN.md; default from .claude/TASK.md)
Context
session
Model
opus
Dependencies
/brewcode:plan (PLAN.md + phases/ directory must exist)
Fix phase files (dynamic, created on verification failure)
Bash Scripts
Does not use custom scripts. Execution through plugin hooks.
Agents
Agent
Purpose
bc-coordinator
Knowledge extraction + report verification only (lighter in v3)
developer
Phase implementation (main work)
tester
Testing, verification
reviewer
Final review (3+ in parallel)
Project agents
Assigned according to PLAN.md Phase Registry
v3 Task API Architecture
In v3, the manager (start skill) uses Task API to manage phase execution:
API
Purpose
TaskCreate
Spawn agent with phase file path -- agent reads its own phases/{N}-{name}.md
TaskUpdate
Update phase status in PLAN.md Phase Registry
TaskList
Check running/completed tasks for parallel group management
The manager never readsphases/ files directly. Only the spawned agents read their assigned phase file. This keeps the manager context slim and enables parallel execution of phases in the same Parallel group.
Hooks Enabling Operation
Hook
Event
Purpose
session-start.mjs
SessionStart
Session initialization, Task API reminder on active v3 task
pre-task.mjs
PreToolUse:Task
Knowledge ## K injection + v3 phase file reminder
post-task.mjs
PostToolUse:Task
Task API instructions for manager
pre-compact.mjs
PreCompact
KNOWLEDGE compaction, v3-aware handoff
stop.mjs
Stop
Block if incomplete, clean lock
Workflow
Resolve Task Path -- from arguments or .claude/TASK.md
Initialize via Coordinator -- validation, create lock, status in progress
Load Context -- read PLAN.md Phase Registry and KNOWLEDGE.jsonl (manager does NOT read phases/ files)
Execute Phases via Task API -- for each phase:
TaskCreate -- spawn agent with path to phases/{N}-{name}.md (agent reads its own phase file)
Agent executes, WRITES report to artifacts/{P}-{N}{T}/{AGENT}_output.md
Purpose: Code review with quorum consensus. Multiple agents review code in parallel, findings confirmed by quorum, then verified by DoubleCheck agent. Optional Critic phase (devil's advocate).
/brewcode:setup (generates skill in .claude/skills/brewcode-review/)
Allowed tools
Read, Glob, Grep, Task, Bash, Write
Important: This skill is not shipped directly in the plugin. It is generated by /brewcode:setup command as a project skill in .claude/skills/brewcode-review/SKILL.md, adapted to the specific project stack.
Phase 6: Report -- generate report with P0-P3 priorities
Finding Priorities
Priority
Source
Description
P0
Critic + DoubleCheck
Verified Critic findings (only with -c)
P1
Quorum + DoubleCheck
Confirmed by quorum and verified
P2
Quorum only
Confirmed by quorum, failed DoubleCheck
P3
Exceptions
Blocker/critical without quorum
Usage Example
/brewcode:review "Check null-safety in service layer"
/brewcode:review -q 5-3 -c "Full review of authorization module"
/brewcode:review requirements/review-checklist.md --quorum 4-3-2
7. /brewcode:rules
Purpose: Extracts anti-patterns and best practices from accumulated knowledge (KNOWLEDGE.jsonl) or session context and updates .claude/rules/avoid.md and .claude/rules/best-practice.md files.
Parameter
Value
Arguments
[path-to-KNOWLEDGE.jsonl] (empty = session mode)
Context
session
Model
sonnet
Dependencies
/brewcode:start (creates KNOWLEDGE.jsonl) or current session
Allowed tools
Read, Write, Edit, Glob, Grep, Bash
Created Files
File
Purpose
.claude/rules/avoid.md
Anti-patterns table (created/updated)
.claude/rules/best-practice.md
Best practices table (created/updated)
Bash Scripts
Script Command
Purpose
rules.sh read "PATH"
Read KNOWLEDGE.jsonl file
rules.sh check
Check if rules files exist
rules.sh create
Create rules files from templates
rules.sh validate
Validate table structure
Agents
Does not use subagents.
Operating Modes
Mode
Condition
Source
File
Path in $ARGUMENTS
Parse KNOWLEDGE.jsonl
Session
Empty $ARGUMENTS
Analyze session context (max 5 rules)
Knowledge Type Mapping
Record Type
Target File
t: "❌"
avoid.md (anti-pattern)
t: "✅"
best-practice.md (best practice)
t: "ℹ️"
Only scope: "global"
Rules Optimization
Deduplication by semantic similarity
Merge related entries into single row
Prioritize by impact: critical > important > nice-to-have
Maximum 20 rows per file
Format: code preferred over prose (~30% token savings)
Moved:/brewcode:auto-sync and bd-auto-sync-processor agent are now in the dedicated brewdoc plugin. Install brewdoc and use /brewdoc:auto-sync.
8. /brewcode:grepai
Purpose: Setup and management of semantic code search based on grepai (Ollama + bge-m3). Supports setup, status, start, stop, reindex, optimize and upgrade.
/brewcode:grepai setup
/brewcode:grepai status
/brewcode:grepai reindex
/brewcode:grepai optimize
/brewcode:grepai upgrade
9. /brewcode:teardown
Purpose: Removes all files and directories created by /brewcode:setup command. Preserves task directories and user rules.
Parameter
Value
Arguments
[--dry-run] (optional -- show without deleting)
Context
fork
Model
haiku
Dependencies
/brewcode:setup (files to remove)
Allowed tools
Bash, Read
Bash Scripts
Script
Purpose
teardown.sh
Remove files (supports --dry-run)
Agents
Does not use subagents.
What Gets Removed
Path
Status
.claude/tasks/templates/
Removed
.claude/tasks/cfg/
Removed
.claude/tasks/logs/
Removed
.claude/plans/
Removed
.grepai/
Removed
.claude/skills/brewcode-review/
Removed
What Gets Preserved
Path
Reason
.claude/tasks/*_task/
Task directories with data
.claude/rules/
User rules
Usage Example
/brewcode:teardown --dry-run
/brewcode:teardown
15. /brewcode:agents
Purpose: Interactive orchestrator for creating and improving Claude Code agents. Collects requirements via AskUserQuestion, delegates to agent-creator agent, then applies text-optimize. Optionally updates CLAUDE.md agents table.
Parameter
Value
Arguments
create <description> | up <name|path> | <name|path> (shorthand)
kochetkov-ma