kochetkov-ma/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):
   • 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