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

| ID | Topic | Reference File | |----|-------|----------------| | overview | Four Plugins Overview | topic-overview.md | | installation | Installation & Updates | topic-installation.md | | killer-flow | Spec → Plan → Start | topic-killer-flow.md | | teams | Dynamic Teams | topic-teams.md | | skills-catalog | All Skills Catalog | topic-skills-catalog.md | | agents-catalog | All Agents Catalog | topic-agents-catalog.md | | customization | Build Your Own | topic-customization.md | | integration | Project Configuration | topic-integration.md | | advanced | Power Features | topic-advanced.md |

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):
2. Exact match → go to Phase 3 with that topic ID
3. Partial/fuzzy match (e.g., "kill" → killer-flow, "agent" → agents-catalog) → go to Phase 3
4. 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:
3. ✅ if topic ID is in $PROGRESS.completed
4. ⬜ if not
5. Show the welcome banner + menu
6. Determine recommended next topic:
7. If no completions → recommend overview (topic 1)
8. If Getting Started done (overview + installation) → recommend killer-flow
9. If Core Workflow done → recommend agents-catalog
10. Otherwise → first incomplete topic in order

1. 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
2. Use the user's language ($PROGRESS.lang) — translate content if not en
3. Include relevant ASCII diagrams when referenced
4. Show CLI commands as ready-to-copy code blocks

1. 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

1. 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 bash "${CLAUDE_SKILL_DIR}/scripts/progress.sh" status ``

1. Show completion status to user

1. 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.

1. 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 mes