Brewdoc:Guide

Brewcode Guide

Interactive teaching skill for the brewcode/brewdoc/brewtools/brewui plugin suite.

Read-only — never modifies user project files. Only writes progress JSON.

Topic Map

---

Phase 0: Validate Environment

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" 2>/dev/null || echo "VALIDATE_SKIP"

If output is VALIDATE_SKIP — skip silently, continue to Phase 0.5. Otherwise — show the health table to the user as-is.

---

Phase 0.5: Plugin freshness check

Before teaching anything, make sure the user's plugin suite is current.

0.5a: Check plugin status

Invoke the brewtools:plugin-update skill with the check argument. This runs in non-interactive status mode — no prompts, no side effects, just a report of installed vs available versions for brewcode, brewdoc, brewtools, brewui.

Use the Skill tool if available:

Skill(skill="brewtools:plugin-update", args="check")

Otherwise instruct the main conversation to run /brewtools:plugin-update check and capture the result.

0.5b: Evaluate result

Parse the check output. A plugin is stale if:

• it is missing (not installed), or
• its installed version is older than the marketplace version.

If all four plugins are current → skip to Phase 1 silently.

0.5c: Offer update

If any plugin is stale or missing:

AskUserQuestion:

question: "Some brewcode plugins are outdated or missing. Update now before continuing the guide?"
options:
  - "Update now"
  - "Show me later"
  - "Skip"

Handle the response:

• Update now → invoke the skill again with the update argument:

  Skill(skill="brewtools:plugin-update", args="update")

When it finishes, continue to Phase 1. Note that a Claude Code restart or /reload-plugins may be required before the new versions take effect.

• Show me later → remember this (set an internal flag remind_update = true). Continue to Phase 1. At the end of the guide (Phase 4, final completion message), remind the user that plugins are still out of date and show the /brewtools:plugin-update command.

• Skip → continue to Phase 1 without reminder.

---

Phase 1: Language & Progress

1a: Load Progress

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/progress.sh" read

Store the JSON result as $PROGRESS.

1b: Language Selection (first run only)

If $PROGRESS.lang is empty:

AskUserQuestion:

question: "Which language do you prefer for the guide?"
options:
  - "English"
  - "Русский"
  - "Português"

Map selection: English → en, Русский → ru, Português → pt.

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/progress.sh" lang "<selected_code>"

1c: Returning User

If $PROGRESS.completed is non-empty array — greet:

Welcome back! You've completed X/9 topics.
Last session: {$PROGRESS.last_topic} on {$PROGRESS.last_ts}.

---

Phase 2: Route — Menu or Direct Topic

If $ARGUMENTS is non-empty:

1. Match $ARGUMENTS against Topic Map IDs (exact or fuzzy):

• Exact match → go to Phase 3 with that topic ID
• Partial/fuzzy match (e.g., "kill" → killer-flow, "agent" → agents-catalog) → go to Phase 3
• No match → show menu (Phase 2b)

If $ARGUMENTS is empty (Phase 2b — Menu):

1. Read welcome template: ${CLAUDE_SKILL_DIR}/references/welcome.md 2. Build menu — replace {status} markers with:

• ✅ if topic ID is in $PROGRESS.completed
• ⬜ if not

3. Show the welcome banner + menu 4. Determine recommended next topic:

• If no completions → recommend overview (topic 1)
• If Getting Started done (overview + installation) → recommend killer-flow
• If Core Workflow done → recommend agents-catalog
• Otherwise → first incomplete topic in order

5. AskUserQuestion:

   question: "Recommended next: {topic_name}. Choose a topic or follow the recommendation:"
   options:
     - "Follow recommendation"
     - "1 — Four Plugins Overview"
     - "2 — Installation & Updates"
     - "3 — Spec → Plan → Start"
     - "4 — Dynamic Teams"
     - "5 — Skills Catalog"
     - "6 — Agents Catalog"
     - "7 — Build Your Own"
     - "8 — Project Configuration"
     - "9 — Power Features"
     - "Exit guide"

If "Exit guide" → stop with farewell message. Otherwise → map selection number to topic ID, go to Phase 3.

---

Phase 3: Deliver Topic

3a: Load Content

1. Read the topic reference file: ${CLAUDE_SKILL_DIR}/references/topic-{TOPIC_ID}.md 2. Read diagrams: ${CLAUDE_SKILL_DIR}/references/ascii-diagrams.md

3b: Present Section by Section

The reference file has 3-4 sections (marked by ### Section N:). For each section:

1. Present the section content to the user

• Use the user's language ($PROGRESS.lang) — translate content if not en
• Include relevant ASCII diagrams when referenced
• Show CLI commands as ready-to-copy code blocks

2. After each section, ask:

AskUserQuestion (for non-last sections):

   question: "What would you like to do?"
   options:
     - "Continue to next section"
     - "Show me an example"
     - "Go deeper"
     - "Skip to next topic"
     - "Back to menu"
     - "Exit guide"

AskUserQuestion (for the last section):

   question: "You've finished this topic! What next?"
   options:
     - "Show me an example"
     - "Go deeper"
     - "Next topic"
     - "Back to menu"
     - "Exit guide"

Handle responses:

• Continue → present next section
• Show me an example → generate a practical example relevant to the current section. Use the user's project context if available (read CLAUDE.md, check .claude/ structure). Base examples only on loaded reference files and project state.
• Go deeper → expand on the current section using ONLY information from loaded reference files, ascii-diagrams.md, and WebSearch results. Do not invent features or details not found in these sources.
• Skip to next topic → go to Phase 2b (do NOT mark topic as complete)
• Next topic → go to Phase 4
• Back to menu → go to Phase 2b (do NOT mark topic as complete)
• Exit guide → go to Phase 4, then stop

3. After "Next topic" or "Exit guide" from last section → go to Phase 4

---

Phase 4: Update Progress

4a: Mark Complete

EXECUTE using Bash tool:

bash "${CLAUDE_SKILL_DIR}/scripts/progress.sh" complete "{TOPIC_ID}"

4b: Recommend Next

1. Reload progress: EXECUTE using Bash tool:

   bash "${CLAUDE_SKILL_DIR}/scripts/progress.sh" status

2. Show completion status to user

3. If all 9 topics completed:

   Congratulations! You've completed the full guide.
   You now know everything about the brewcode plugin suite.
   
   Useful next steps:
   - Run /brewcode:setup in your project
   - Create a team with /brewcode:teams create
   - Start a task with /brewcode:spec "your task description"

Stop.

4. Otherwise — recommend next incomplete topic:

AskUserQuestion:

   question: "Continue to the next topic?"
   options:
     - "Yes — {next_topic_name}"
     - "Back to menu"
     - "Exit guide"

• Yes → go to Phase 3 with next topic
• Back to menu → go to Phase 2b
• Exit guide → farewell message, stop

---

Language Support

When $PROGRESS.lang is not en:

• Translate ALL user-facing text (section content, questions, options, messages)
• Keep CLI commands, code blocks, and technical terms in English
• Keep table headers in English, translate descriptions

Guide

Interactive tutorial for the brewcode/brewdoc/brewtools/brewui plugin suite -- 9 topics, 3 domains, progress tracking.

Overview

Guide walks you through every feature of the plugin suite across three progressive domains: Getting Started (overview, installation), Core Workflow (spec/plan/start, teams, skills catalog), and Mastery (agents, custom creation, power features). It tracks your progress, supports multiple languages (EN/RU/PT), and adapts to your level. Read-only -- never modifies project files.

Quick Start

/brewdoc:guide                  # Interactive menu
/brewdoc:guide overview         # Jump to a specific topic
/brewdoc:guide killer-flow      # Spec/Plan/Start pipeline
/brewdoc:guide agents-catalog   # All 18 agents

Topics

Progress Tracking

Progress is saved to .claude/brewdoc/guide-progress.json (project-relative) and persists across sessions. If the project directory is not writable, the script falls back to ${BD_PLUGIN_DATA}/guide-progress.json for interactive sessions. Returning users see completion status and a recommendation for the next topic. Partial matching works for topic names.

Documentation

Full docs: guide

ASCII Diagrams

Pre-drawn diagrams for the guide skill. Reference by name from topic files.

Diagram: Plugin Suite Architecture

┌─────────────────────────────────────────────────┐
│              claude-brewcode (marketplace)       │
├─────────────────┬──────────────┬────────────────┤
│    brewcode      │   brewdoc    │   brewtools    │
│─────────────────│──────────────│────────────────│
│ setup, spec     │ auto-sync    │ text-optimize  │
│ plan, start     │ my-claude    │ text-human     │
│ teams, review   │ memory       │ secrets-scan   │
│ convention, e2e │ md-to-pdf    │                │
│ rules, grepai   │ guide        │                │
│                 │ publish      │                │
│ + 14 agents     │              │                │
│ + 9 hooks       │              │                │
└─────────────────┴──────────────┴────────────────┘

Diagram: Killer Flow Pipeline

┌──────┐   ┌──────┐   ┌───────┐   ┌─────────┐   ┌───────┐
│ spec │──>│ plan │──>│ start │──>│ handoff │──>│ start │──> ...
└──────┘   └──────┘   └───┬───┘   └────┬────┘   └───┬───┘
                          │            │             │
                     ┌────┴────┐  ┌────┴────┐  ┌────┴────┐
                     │ hooks   │  │ compact │  │ hooks   │
                     │ inject  │  │ KNOW-   │  │ re-read │
                     │ context │  │ LEDGE   │  │ state   │
                     └─────────┘  └─────────┘  └─────────┘
                                       │
                          KNOWLEDGE.jsonl persists
                          across all sessions

Diagram: Teams Architecture

┌────────────────────┐
│   /brewcode:teams   │
└────────┬───────────┘
         │ spawns
    ┌────┴────┐
    │ agent-  │
    │ creator │
    └────┬────┘
         │ creates domain agents
   ┌─────┼─────────┐
   v     v         v
┌─────┐┌─────┐┌────────┐
│ db- ││ api- ││ ui-    │
│ agent││agent││ agent  │
└──┬──┘└──┬──┘└───┬────┘
   │      │       │
   └──────┴───────┘
         │
   trace.jsonl tracks
   all agent actions

Diagram: Hook Chain

SessionStart         PreToolUse:Task     PostToolUse:Task
     │                     │                    │
     v                     v                    v
┌────────────┐     ┌────────────┐      ┌─────────────┐
│ session-   │     │ pre-task   │      │ post-task   │
│ start.mjs  │     │ inject ctx │      │ bind session│
└────────────┘     └────────────┘      └─────────────┘
     │                                        │
     v                                        v
┌────────────┐                        ┌─────────────┐
│ grepai-    │   PreCompact           │   Stop      │
│ session    │       │                │   event     │
└────────────┘       v                └──────┬──────┘
                ┌────────────┐               v
                │ pre-compact│        ┌─────────────┐
                │ compact KN │        │ stop.mjs    │
                │ write hoff │        │ block if    │
                └────────────┘        │ not terminal│
                                      └─────────────┘

Diagram: Project Directory

.claude/tasks/
└── {TS}_{NAME}_task/
    ├── PLAN.md              # execution plan
    ├── SPEC.md              # task specification
    ├── KNOWLEDGE.jsonl      # persistent learnings
    ├── .lock                # session lock
    ├── artifacts/
    │   ├── FINAL.md         # final summary
    │   └── {P}-{N}{T}/     # phase artifacts
    │       └── {AGENT}_output.md
    └── backup/              # auto-backups

Topic: Power Features

Domain: Mastery

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: Grepai -- Semantic Code Search

Grepai indexes your codebase for semantic search. Much smarter than grep — it understands intent, not just text patterns.

# Setup grepai for your project
/brewcode:grepai

# After setup, search semantically:
grepai_search query:"user authentication flow"
grepai_search query:"error handling", compact:true

# Trace call chains:
trace_callers symbol:"validateToken"
trace_callees symbol:"processOrder"
trace_graph symbol:"main" depth:2

Search modes:

Query tips:

• Use natural English, 3-7 words
• Describe intent, not syntax: "validate credentials" not "validateUser"
• Add compact:true for large result sets (returns file + line, no content)
• Add limit:5 for quick exploration

Grepai auto-activates via the grepai-session hook at conversation start.

Section 2: Convention Extraction

Convention extraction analyzes your existing code to discover patterns and enforce them automatically.

# Analyze existing code patterns
/brewcode:convention

# Modes:
/brewcode:convention extract   # Find patterns in code
/brewcode:convention document  # Generate convention docs

What it extracts:

• Naming conventions — how you name classes, methods, variables, files
• Error handling patterns — try/catch structure, error types, logging
• Test structure — setup, assertions, mocking patterns
• API patterns — endpoint naming, request/response shapes, middleware
• Architecture — layer separation, dependency direction, module boundaries

Output goes to .claude/rules/ as auto-loaded rule files. New code follows your established patterns automatically — no manual style guides needed.

The convention skill identifies etalon (reference) classes in your codebase. These become the standard that generated rules point to.

Section 3: Standards Review

Quorum code review with multiple independent perspectives.

# Plugin skill for standards compliance:
/brewcode:standards-review

# Local quorum review (generated by /brewcode:setup):
/brewcode:review

How it works: 1. Three independent reviewers analyze the code simultaneously 2. Each reviewer focuses on different aspects: architecture, security, performance, correctness, maintainability 3. Issues require 2/3 consensus to be flagged (reduces false positives) 4. Up to MAX_CYCLES=3 review-fix loops

Review process:

Code submitted -> 3 reviewers analyze independently
  -> Compare findings -> 2/3 consensus required
    -> Issues reported -> Developer fixes
      -> Re-review (up to 3 cycles)
        -> Final report

The quorum approach filters out subjective preferences and focuses on issues that multiple reviewers agree on.

Section 4: Secrets Scanning

Detect leaked credentials before they reach your repository.

/brewtools:secrets-scan

What it detects:

• API keys and tokens (AWS, GCP, Azure, GitHub, Stripe, etc.)
• Passwords and connection strings
• Private keys (RSA, SSH, PGP)
• Environment variable leaks in committed files
• Hardcoded credentials in source code

How it works:

• Scans all git-tracked files in the project
• Combines pattern matching with entropy analysis
• Zero false positives design — only flags high-confidence matches
• Reports file, line number, and credential type

Best practice: run /brewtools:secrets-scan before commits as part of your workflow. Combine with /brewcode:review for comprehensive pre-merge checks.

Topic: All Agents

Domain: Mastery

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: What Are Agents?

Agents are specialized sub-processes spawned via the Task tool. Each has a specific model, toolset, and expertise area.

Key concepts:

• The main conversation acts as manager — it delegates, never implements directly
• Each agent runs in isolated context with only the tools it needs
• Agents are defined as .md files with YAML frontmatter (name, model, tools, description)
• Located in .claude/agents/ (project-specific) or plugin directories

How it works:

User request -> Manager analyzes -> Selects best agent -> Task tool spawns agent
  -> Agent executes in isolation -> Returns result -> Manager continues

Claude Code allows nested spawns up to 5 levels deep (since 2.1.172). The brewcode workflow, however, requires spawning only from the main conversation (manager level): the 2-step report protocol binds the task lock to a single session and delivers report/coordinator instructions to the spawning conversation. Nested spawns bypass session binding, KNOWLEDGE injection, and the coordinator loop — so under brewcode only the manager uses the Task tool.

Section 2: Plugin Agents (18)

These agents ship with the brewcode plugin suite. Available immediately after installation.

Agents prefixed with bc- are internal to brewcode workflows. The rest are user-facing.

Section 3: System Agents

Built into Claude Code itself. Always available, no plugin required.

System agents are selected when no plugin agent is a better match.

Section 4: Model Selection Guide

Rule of thumb:

• Agent writes or reviews code: opus
• Agent processes text or runs tests: sonnet
• Agent coordinates or tracks state: haiku

Topic: Build Your Own

Domain: Mastery

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: Create Custom Skills

Skills are interactive instructions that Claude Code executes step by step.

# Use the skill-creator agent
/brewcode:skills
# Or describe what you need: "Create a skill for database migrations"

Skill structure:

skills/my-skill/
  SKILL.md          # Frontmatter + instructions
  references/       # Knowledge files loaded during execution
  scripts/          # Helper bash scripts

Key SKILL.md frontmatter fields:

---
name: plugin:skill-name
description: "What it does. Trigger keywords."
user-invocable: true
allowed-tools: [Read, Write, Bash, AskUserQuestion]
model: haiku|sonnet|opus
---

• name — how users invoke it: /plugin:skill-name
• description — also used for auto-detection (include trigger keywords)
• model — determines which model runs the skill
• allowed-tools — restricts skill to only necessary tools
• Reference files use ${CLAUDE_SKILL_DIR} to locate themselves

Section 2: Create Custom Agents

Agents are single .md files placed in .claude/agents/.

# Use the agent-creator agent
/brewcode:agents
# Or describe what you need: "Create an agent for API testing"

Agent file structure:

---
name: my-agent
description: "What it does. When to trigger."
model: sonnet
tools: [Read, Write, Edit, Bash, Grep, Glob]
---
# Instructions for the agent...

Key decisions when creating agents:

• model — opus for complex tasks, sonnet for moderate, haiku for simple
• tools — only include what the agent actually needs (principle of least privilege)
• description — the manager uses this to decide when to delegate to your agent

Agents in .claude/agents/ are auto-discovered. No manifest entry needed.

Section 3: Create Custom Hooks

Hooks are JavaScript (.mjs) files that intercept Claude Code lifecycle events.

# Hook-creator helps build lifecycle hooks
# "Create a PreToolUse hook to validate Bash commands"

Available hook events:

Hooks are configured in hooks.json:

[
  { "event": "PreToolUse", "match": "Bash", "script": "./hooks/validate-bash.mjs" }
]

Response channels: additionalContext (inject text), updatedInput (modify tool input), decision (block/allow).

Hooks shipped with brewcode suite

brewcode (7):

brewtools (2):

brewui (2):

brewdoc (1):

Section 4: Dynamic Teams

Teams are collections of project-specific agents generated from your codebase.

/brewcode:teams create "my project team"

What happens: 1. Analyzes your project structure, conventions, and tech stack 2. Creates 5-20 specialized agents tailored to your codebase 3. Stores team config in .claude/teams/{team-name}/ 4. Agents understand your specific patterns, naming, and architecture

Team directory:

.claude/teams/{team-name}/
  team.md          # Team composition and rules
  trace.jsonl      # Team creation trace
  agents/          # Generated agent .md files

Teams make the manager smarter about your specific project — instead of generic "developer" or "tester", you get agents that already know your stack.

Topic: Installation & Updates

Domain: Getting Started

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: Prerequisites

Before installing, make sure you have:

• Claude Code CLI installed and working (claude command available)
• GitHub CLI (gh) — recommended but not strictly required
• jq — used by some internal scripts

Check prerequisites:

claude --version
gh --version
jq --version

All three should return version numbers without errors.

Section 2: Installation Steps

Three commands to install everything:

# Step 1: Add the marketplace
claude plugin marketplace add https://github.com/kochetkov-ma/claude-brewcode

# Step 2: Install all 4 plugins
claude plugin install brewcode@claude-brewcode
claude plugin install brewdoc@claude-brewcode
claude plugin install brewtools@claude-brewcode
claude plugin install brewui@claude-brewcode

After installation, run /reload-plugins. If plugins still do not appear, restart Claude Code.

You can install only the plugins you need. brewcode is the core; brewdoc and brewtools are optional.

Section 3: Verify Installation

# List all installed plugins
claude plugin list

You should see all four plugins with matching version numbers.

Quick smoke test:

/brewcode:setup

If the setup wizard starts, installation is working.

Section 4: Updating

All four plugins share a version number. When one updates, update all of them:

# Step 1: Update marketplace index
claude plugin marketplace update claude-brewcode

# Step 2: Update each plugin
claude plugin update brewcode@claude-brewcode
claude plugin update brewdoc@claude-brewcode
claude plugin update brewtools@claude-brewcode
claude plugin update brewui@claude-brewcode

After updating, run /reload-plugins (or /reload-skills for skill-only changes, Claude Code 2.1.152+). Restart only if reloading does not pick up the changes.

If you see version mismatches across plugins, update all four to fix it.

Section 5: Dev Mode (for contributors)

If you are working on the plugin source code, run from source without installing:

claude --plugin-dir ./brewcode
claude --plugin-dir ./brewdoc
claude --plugin-dir ./brewtools
claude --plugin-dir ./brewui

Changes take effect immediately without reinstalling.

Never use --plugin-dir for production — developer-only flag.

Section 6: Keeping Plugins Up to Date

The easiest way to keep the whole suite current:

/brewtools:plugin-update

This checks the marketplace, compares installed versions, and updates everything in one pass. Use check for status-only, update for non-interactive update, or all for everything.

Manual fallback

claude plugin marketplace update claude-brewcode
claude plugin update brewcode@claude-brewcode
claude plugin update brewdoc@claude-brewcode
claude plugin update brewtools@claude-brewcode
claude plugin update brewui@claude-brewcode

After updating

• Preferred: /reload-plugins
• Fallback: exit the session, then run claude again

If version mismatches persist after an update, re-run — all four must share the same version.

Topic: Project Configuration

Domain: Mastery

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: CLAUDE.md -- Project Instructions

CLAUDE.md in the project root is the primary configuration file for Claude Code.

What it contains:

• Overview — project description, tech stack, architecture summary
• Commands — how to build, test, lint, run the project
• Rules — coding standards, naming conventions, patterns to follow/avoid
• Structure — key directories and their purposes

Key principles:

• Loaded automatically at conversation start
• Every token counts — keep it concise, use tables and lists over prose
• Use @path/to/file syntax to import other files into context
• Code format saves ~30% tokens compared to prose

Example structure:

# CLAUDE.md
## Overview
MyApp — Spring Boot 3.2 REST API with PostgreSQL

## Commands
| Command | Purpose |
|---------|---------|
| `./gradlew build` | Build without tests |
| `./gradlew test` | Run all tests |

## Architecture
@docs/architecture.md

Section 2: Rules -- .claude/rules/*.md

Rules are path-specific instructions that activate when matching files are in context.

---
globs: ["src/**/*.ts", "tests/**"]
---
# TypeScript Rules
- Use strict null checks
- Prefer interfaces over type aliases
- All functions must have return types

How rules work:

• Glob matching — rules load only when relevant files are being edited
• Project rules — .claude/rules/*.md (checked into repo, shared with team)
• Global rules — ~/.claude/rules/*.md (personal, apply to all projects)
• Auto-loaded — no need to reference them from CLAUDE.md

Organize by concern:

.claude/rules/
  testing.md        # globs: ["**/test/**", "**/*.test.*"]
  api.md            # globs: ["src/api/**"]
  database.md       # globs: ["**/repository/**", "**/*Repository*"]

Use /brewcode:rules to generate rules from KNOWLEDGE.jsonl learnings.

Section 3: Memory -- Persistent Context

Memory files store information that persists across conversations.

• Located in the auto-configured memory directory
• MEMORY.md = index file with pointers to individual memory files
• Survives conversation restarts — Claude reads them at session start

Memory types:

Optimize memory with /brewdoc:memory — removes duplicates, consolidates entries, reduces token usage.

Memory is different from KNOWLEDGE.jsonl:

• Memory = cross-conversation persistence (about the user/project)
• KNOWLEDGE = within-task persistence (about the current task execution)

Section 4: Full .claude/ Structure

Complete directory layout for a project using brewcode:

.claude/
  CLAUDE.md              # Symlink or pointer to root CLAUDE.md
  settings.json          # Project settings (model, permissions)
  rules/                 # Path-specific rules
    testing.md
    api.md
  agents/                # Project-specific agents
    db-expert.md
    ui-specialist.md
  skills/                # Project-specific skills
  teams/                 # Dynamic team configs
    {team-name}/
      team.md
      trace.jsonl
  tasks/                 # Brewcode task directories
    cfg/
      brewcode.config.json   # Plugin configuration
      brewcode.state.json    # Current state
    templates/               # Adapted PLAN/SPEC templates
    logs/                    # Execution logs
    sessions/                # Session tracking
      {session_id}.info
    {ts}_{name}_task/        # Individual task directories
      SPEC.md
      PLAN.md
      KNOWLEDGE.jsonl
      phases/
      artifacts/
        FINAL.md
      backup/
      .lock

Key directories:

• cfg/ — created by /brewcode:setup, stores config and state
• tasks/ — each task gets its own isolated directory
• teams/ — created by /brewcode:teams, stores generated agents

Topic 3: The Killer Flow — Spec, Plan, Start

Domain: Core Workflow

Section 1: The Pipeline

The core workflow chains 3 skills into one continuous pipeline:

1. /brewcode:spec "description" — Creates SPEC.md through research + user Q&A 2. /brewcode:plan — Creates PLAN.md with phases, dependencies, agent assignments 3. /brewcode:start — Executes with infinite context handoff

User describes task
  -> /brewcode:spec analyzes codebase, asks clarifying questions
    -> Produces SPEC.md in .claude/tasks/{ts}_{name}_task/
      -> /brewcode:plan reads SPEC, creates phases
        -> Produces PLAN.md + phases/*.md
          -> /brewcode:start executes phase by phase
            -> Automatic handoff when context fills
              -> Continues from where it left off

Each skill feeds the next. SPEC defines WHAT. PLAN defines HOW. START does the work.

Reference Diagram: Killer Flow Pipeline from ascii-diagrams.md.

Section 2: Infinite Context — How Handoff Works

The "infinite" part: tasks survive context window limits automatically.

No user intervention needed. The hook chain drives it all:

session-start -> pre-task -> post-task -> pre-compact -> stop

Pre-compact writes handoff state. Session-start reads it back. The loop is seamless.

Section 3: Knowledge Persistence

KNOWLEDGE.jsonl stores learnings across sessions and compactions. It never gets lost.

Format:

{"ts":"2026-01-26T14:00:00","t":"❌","txt":"Avoid SELECT *","src":"sql_expert"}
{"ts":"2026-01-26T14:05:00","t":"✅","txt":"Use parameterized queries","src":"db_agent"}
{"ts":"2026-01-26T14:10:00","t":"ℹ️","txt":"DB uses PostgreSQL 16","src":"setup"}

Priority levels (highest to lowest):

Knowledge is injected into every agent prompt via the pre-task hook. Agents learn from previous sessions without re-discovering.

Section 4: Task Directory Structure

Every task gets its own directory under .claude/tasks/:

.claude/tasks/{ts}_{name}_task/
  SPEC.md              # What to build
  PLAN.md              # How to build it
  KNOWLEDGE.jsonl      # Learnings
  phases/              # Phase instructions
    P1_setup.md
    P1V_verify.md
    ...
  artifacts/           # Agent outputs
    FINAL.md
    {P}-{N}{T}/
  backup/              # Pre-execution backups
  .lock                # Execution lock

Reference Diagram: Project Directory from ascii-diagrams.md.

Key files:

• SPEC.md — Created by /brewcode:spec, never modified after
• PLAN.md — Created by /brewcode:plan, tracks phase status
• KNOWLEDGE.jsonl — Grows during execution, compacted at handoff
• .lock — Prevents concurrent execution of the same task

Topic: Four Plugins Overview

Domain: Getting Started

Deliver section by section. Pause after each section with AskUserQuestion.

Section 1: What is Brewcode?

Brewcode is a plugin suite for Claude Code. It ships as 4 plugins in a single marketplace package.

Key ideas:

• Few powerful workflows that handle real-world complexity
• Extend yourself: create your own skills, agents, and hooks
• Not a framework. A set of tools that work together without locking you in.

One marketplace, four plugins, one version number. Install what you need.

Section 2: The Four Plugins

brewcode is the core. It runs tasks that survive context limits through automatic handoff. It manages agents, hooks, and knowledge persistence.

brewdoc handles documentation. Auto-sync keeps docs updated. My-claude generates Claude Code setup docs for any project. Memory optimizes memory files. Publish shares content via brewpage.app.

brewtools provides standalone utilities. Text-optimize reduces token usage in prompts. Secrets-scan catches leaked credentials. SSH and deploy handle server management and CI/CD workflows. These work in any project.

brewui handles UI and visual tasks. Image-gen creates AI images via multiple providers. GLM-design-to-code converts designs into multi-framework code.

Section 3: How They Work Together

The plugins complement each other:

• brewcode handles the heavy lifting: task execution, planning, code review, convention extraction
• brewdoc keeps documentation in sync with your codebase as it evolves
• brewtools provides utility skills you can call from anywhere
• brewui generates images and converts designs to code

All four share the same version number. They update together from the same marketplace. No version mismatches.

Example workflow: 1. /brewcode:setup initializes a project 2. /brewcode:spec + /brewcode:plan + /brewcode:start executes a feature 3. /brewdoc:auto-sync updates affected documentation 4. /brewtools:secrets-scan checks nothing was leaked

Section 4: What Makes It Unique

Five capabilities that set brewcode apart:

1. Infinite context via handoff — tasks automatically hand off to fresh sessions when context fills up. No progress lost. KNOWLEDGE.jsonl carries learnings forward.

2. KNOWLEDGE.jsonl persistence — every insight, mistake, and decision is captured. Future sessions start smarter than the last one ended.

3. Dynamic teams — create domain-specific agents on the fly. Need a database expert? A UI specialist? Generate them from your codebase conventions.

4. Convention extraction — analyze existing code to extract patterns, naming conventions, architecture rules. New code follows established patterns automatically.

5. Quorum code review — multiple reviewer perspectives (security, performance, architecture) in a single review pass. Configurable reviewer count.

Reference: see "Diagram: Plugin Suite Architecture" in ascii-diagrams.md

Topic 5: All Skills Catalog

Domain: Core Workflow

Section 1: Brewcode Skills (13)

The main plugin. Task execution, code quality, project management.

Note: /brewcode:setup also generates a local /brewcode:review skill for quorum code review (3 reviewers, 2/3 consensus). It is project-specific, not shipped with the plugin.

Typical flow: setup (once) -> spec -> plan -> start -> standards-review

Section 2: Brewdoc Skills (6)

Documentation tools. Sync, generate, optimize, export, publish.

Section 3: Brewtools Skills (11)

Universal utilities. Work in any project, no setup needed.

These are standalone — no project configuration required. Run them anywhere.

Section 3b: Brewui Skills (2)

UI/visual/creative tools. AI image generation and design-to-code conversion.

Section 4: Common Patterns

Arguments: Most skills accept inline arguments.

/brewcode:spec "add user authentication with OAuth2"
/brewcode:teams create backend-team
/brewcode:convention extract
/brewcode:review -q 3-5

Recommended order for new projects:

Tips:

• Skills that modify files always confirm before writing
• Use /brewcode:setup first in any new project — it detects your stack and creates templates
• /brewcode:teardown removes task artifacts but keeps the task directory for reference

Topic 4: Dynamic Teams

Domain: Core Workflow

Section 1: What Are Teams?

Teams are collections of 5-20 domain-specific agents tailored to YOUR project.

Unlike generic agents (developer, tester, reviewer), team agents know your domain: your database schema, your API patterns, your frontend components. They are created by analyzing your actual codebase.

Section 2: Creating a Team

# Analyze project and create team
/brewcode:teams create

# Create with custom name
/brewcode:teams create backend-team

# Create with specific focus
/brewcode:teams create "focus on API layer and database"

Creation process:

Each agent gets a dedicated markdown file with:

• Role description and responsibilities
• Project-specific knowledge (files, patterns, conventions)
• Tool permissions and constraints
• Interaction rules with other team agents

Reference Diagram: Teams Architecture from ascii-diagrams.md.

Section 3: Team Management

# Check team status and health
/brewcode:teams status

# Update agents based on project changes
/brewcode:teams update

# Clean up team files
/brewcode:teams cleanup

Updates re-analyze the codebase and adjust agent knowledge. New files, changed patterns, or removed modules are reflected in agent definitions.

Section 4: Trace Tracking

Every agent action is logged to trace.jsonl in the team directory.

.claude/teams/{name}/
  trace.jsonl          # action log
  roster.json          # agent definitions
  verification/        # integrity checks

Trace enables:

Verification scripts ensure agent integrity — confirming that agent files match the roster and that no agents have been corrupted or accidentally modified.

Welcome

Banner

╔══════════════════════════════════════════════════╗
║  ____                              _             ║
║ | __ ) _ __ _____      _____ ___  __| | ___      ║
║ |  _ \| '__/ _ \ \ /\ / / __/ _ \ / _` |/ _ \    ║
║ | |_) | | |  __/\ V  V / (_| (_) | (_| |  __/    ║
║ |____/|_|  \___| \_/\_/ \___\___/ \__,_|\___|    ║
║              G  U  I  D  E                       ║
╚══════════════════════════════════════════════════╝

Menu Template

Present this menu to the user:

Replace {status} with the completion marker: use a checkmark if completed, use an empty box if not.

Quick Start

If user is brand new, recommend: "Start with topic 1 (Four Plugins Overview)" If user has completed Getting Started, recommend Core Workflow topics. If user has completed Core Workflow, recommend Mastery topics.

Navigation

After each section, offer via AskUserQuestion:

• "Continue to next section"
• "Show me an example"
• "Go deeper"
• "Back to menu"
• "Exit guide"