guide

Caution

Starting from scratch is overwhelming. The brewcode suite has 4 plugins, 15+ skills, and 13+ agents. Reading all the docs at once doesn’t work — there’s no thread, no order, no feedback. Without a guide, most users discover 20% of the features and miss the rest.

Tip

Guide is a structured, interactive walkthrough. 9 topics across 3 domains, delivered section by section with pauses for questions. Progress is saved — pick up where you left off next session. Runs on haiku for instant responses. Never modifies your project files.

Quick reference

FieldValue
Command/brewdoc:guide [topic]
Argumentsoverview, installation, killer-flow, teams, skills-catalog, agents-catalog, customization, integration, advanced — or none for interactive menu
Modelhaiku
ToolsRead, Glob, Grep, Bash, WebSearch, AskUserQuestion

When to use

  • First time with brewcode — run /brewdoc:guide with no args, follow the menu
  • Jump to a specific domain — /brewdoc:guide killer-flow skips straight to Spec→Plan→Start
  • Resume after a break — the skill loads your saved progress and recommends the next topic
  • Fuzzy navigation — /brewdoc:guide agent resolves to the agents catalog via partial match
  • After an update — guide checks plugin versions on every launch and offers to update stale plugins

Examples

# Start the interactive menu (recommended for new users)
/brewdoc:guide

# Jump directly to a topic by name
/brewdoc:guide killer-flow

# Partial match — resolves to agents-catalog
/brewdoc:guide agent

Expected output when starting fresh:

Component     Status      Details
Docs Site     UP          200
Latest        v3.6.2      GitHub
brewcode      3.6.2       current
brewdoc       3.6.2       current
brewtools     3.6.2       current
Auto-update   ON

Welcome! Choose a topic or follow the recommendation:
→ Recommended next: Four Plugins Overview

Flow

The guide follows a 6-step onboarding walkthrough on every launch:

  1. Validate environment

    Checks the docs site, GitHub latest release, and all four installed plugin versions. Prints a health table so you know exactly what’s current before learning anything.

  2. Check plugin freshness

    Invokes /brewtools:plugin-update check silently. If any plugin is stale or missing, offers to update now, remind later, or skip — your choice, no forced interruptions.

  3. Load language and progress

    First run asks your preferred language (English, Russian). Returning users see their completion score and the recommended next topic based on what they’ve already covered.

  4. Route to topic

    With an argument — exact or fuzzy match against the 9 topic IDs, then straight to delivery. Without an argument — interactive menu with checkmarks (✅ completed, ⬜ pending) and a recommendation.

  5. Deliver topic section by section

    Each topic has 3–4 sections. After each section: continue, show me an example, go deeper, skip, or back to menu. Examples use your actual project context (reads CLAUDE.md and .claude/ structure) — not generic placeholders.

  6. Update progress and recommend next

    Marks the topic complete in .claude/brewdoc/guide-progress.json. Shows updated completion status. If all 9 topics are done, prints a “what to do now” summary with concrete next commands.

Progress tracking and topic map

Progress is saved to .claude/brewdoc/guide-progress.json (project-relative). If the project directory is not writable, falls back to ${BD_PLUGIN_DATA}/guide-progress.json.

{
  "lang": "en",
  "completed": ["overview", "installation"],
  "last_topic": "killer-flow",
  "last_ts": "2026-04-02T10:00:00Z",
  "shown_count": { "overview": 2, "installation": 1 }
}
IDTopicDomain
overviewFour Plugins OverviewA: Getting Started
installationInstallation & UpdatesA: Getting Started
killer-flowSpec → Plan → StartB: Core Workflow
teamsDynamic TeamsB: Core Workflow
skills-catalogAll Skills CatalogB: Core Workflow
agents-catalogAll Agents CatalogC: Mastery
customizationBuild Your OwnC: Mastery
integrationProject ConfigurationC: Mastery
advancedPower FeaturesC: Mastery

Two helper scripts manage the guide: validate.sh checks docs site, GitHub release, and installed versions; progress.sh handles CRUD for the progress JSON (read, complete, lang, reset, status).

📄

my-claude

Generate Claude Code installation docs for your project — complements the guide’s installation topic.

🤖

auto-sync

Universal doc sync skill — keep docs in sync as your project evolves after the guide.

🔗

GitHub source

Source code, topic reference files, and progress scripts.

🚀

brewdoc overview

All brewdoc skills in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.