feat: rewrite /guide as interactive beginner walkthrough

plugin/commands/guide.md

@@ -1,101 +1,143 @@
 ---
-description: Interactive guide to how fellowship works. Use when you're new to fellowship or need a refresher on concepts, commands, and workflow.
+description: Interactive guide to fellowship. Walks you through a real task using the structured research-plan-implement flow, then shows you what's next.
 ---
 
-# Fellowship Guide
+# Fellowship Guide — Learn by Doing
 
-Present the following overview to the user, then transition to Q&A mode.
+## Overview
 
----
+This guide teaches fellowship by running a real task on the user's codebase. It does NOT explain concepts upfront — it demonstrates them, then names them afterward.
 
-## What is Fellowship?
+**Do not mention** gates, lembas, tome, worktree, balrog, warden, council, palantir, herald, eagles, errands, companies, or scouts until Act 3 (Graduation). Use plain language throughout Acts 1–2.
 
-Fellowship is a multi-quest orchestrator for Claude Code. It coordinates parallel tasks — code quests and research scouts — using agent teams. A coordinator named Gandalf manages the fellowship: spawning teammates, routing approvals, and reporting progress. Gandalf never writes code.
+## Act 1: Pitch
 
-## Core Concepts
+Present this to the user:
 
-### Quests
+> **Fellowship helps Claude work through complex tasks more carefully** — researching before planning, planning before coding. Each step has a checkpoint where you review the work before moving on.
+>
+> Let's try it on something real in your codebase.
 
-A quest is a structured code task that moves through 6 phases:
+Then ask using AskUserQuestion:
 
-```
-Onboard -> Research -> Plan -> Implement -> Review -> Complete
-```
+> **What would you like to work on?**
+>
+> Pick something real — a bug to fix, a feature to add, or a refactor to do. It should be non-trivial (more than a one-line change) but completable in a single session.
 
-Each quest runs in an isolated git worktree so teammates don't interfere with each other. At the end, each quest produces a PR.
+Wait for their response. This is the task description used for the rest of the guide.
 
-- **Onboard** — create worktree, load project context
-- **Research** — explore the codebase, understand the system
-- **Plan** — outline explicit steps with file paths and test strategy
-- **Implement** — execute the plan using TDD (test-driven development)
-- **Review** — convention checks, code quality review, verification
-- **Complete** — create PR, clean up
+## Act 2: Guided Quest
 
-### Gates
+### Setup
 
-Between each phase is an approval gate. By default, every gate surfaces to you for approval — you see a summary of what the quest accomplished and decide whether to proceed. This keeps you in the loop without micromanaging.
+1. Determine the current branch: `git branch --show-current`
+2. Create a new branch: `git checkout -b guide/<slug>` where `<slug>` is a short kebab-case summary of the task (e.g., `guide/fix-auth-redirect`)
+3. Read the project's CLAUDE.md (if it exists) to understand conventions and reference files. Do not present this to the user — absorb it silently.
 
-You can auto-approve specific gates via config (e.g., always auto-approve Research and Plan gates) so only the high-stakes transitions need your attention.
+### Stage 1: Research
 
-### Gandalf (The Coordinator)
+**Goal:** Understand the relevant parts of the codebase before making a plan.
 
-When you run `/fellowship`, you become Gandalf — the coordinator who:
-- Spawns quest runners and scouts as teammates
-- Routes gate approvals between you and teammates
-- Tracks progress across all active quests
-- Never writes code directly
+1. Use the Explore agent (Agent tool with subagent_type=Explore) to find files related to the task. Focus on:
+   - Files that will likely need modification
+   - Files that define patterns to follow
+   - Test files for the affected area
+   - Types, configs, or dependencies that constrain the work
+2. If CLAUDE.md lists reference files for the relevant area, read them and note the patterns (naming, error handling, structure, data flow). Do not present the raw pattern analysis — internalize it.
+3. Present a structured research summary to the user:
 
-### Worktrees
+> **Here's what I found:**
+>
+> **Relevant files:**
+> - `path/to/file.go:20-45` — [why it matters]
+> - `path/to/other.go:10-30` — [why it matters]
+>
+> **How it works:** [2-3 sentence explanation of the relevant system]
+>
+> **Approach:** [1-2 sentences on how you'd tackle the task based on what you found]
+>
+> **Does this look right before I make a plan?**
 
-Each quest gets its own git worktree — a separate working directory on its own branch. This means multiple quests can modify code simultaneously without conflicts. Worktrees are created automatically in Phase 0.
+Wait for the user's response. Revise if they correct anything.
 
-### Lembas (Context Compression)
+### Stage 2: Plan
 
-Between each phase, the quest runner compresses its conversation context into a structured checkpoint (`.fellowship/checkpoint.md`). This keeps the context window in the "smart zone" and provides crash recovery — if a session dies, the checkpoint survives on disk.
+**Goal:** Outline explicit steps before writing any code.
 
-### Scouts
+1. Enter plan mode (EnterPlanMode) and draft a concise implementation plan:
+   - Numbered steps with specific file paths
+   - What each step changes and why
+   - Which tests to add or modify
+   - Expected behavior after each step
+2. Present the plan and ask:
 
-Scouts are research-only tasks. They investigate questions, analyze code, and produce reports — but never modify code or create PRs. Use scouts for questions like "how does the auth middleware chain work?" or "list all API endpoints." Scout findings can be routed to specific quest runners.
+> **Does this plan look good before I start coding?**
 
-## Commands
+Wait for approval. Revise if needed. Exit plan mode (ExitPlanMode) once approved.
 
-These are the commands you'll use directly:
+### Context Checkpoint (silent)
 
-| Command | What it does |
-|---------|-------------|
-| `/fellowship` | Start a new fellowship — become Gandalf and coordinate parallel quests |
-| `/quest` | Run a single quest outside of a fellowship (standalone mode) |
-| `/guide` | This guide — overview of how fellowship works |
-| `/rekindle` | Recover a fellowship after a session crash |
-| `/settings` | View or edit fellowship config (`~/.claude/fellowship.json`) |
-| `/scribe` | Create a project-specific quest template from codebase conventions |
-| `/chronicle` | Generate a CLAUDE.md conventions section by analyzing your codebase |
-| `/red-book` | Capture PR review feedback as conventions in CLAUDE.md |
+Before starting implementation, compress your context. Discard verbose research output (file contents, search results) and carry forward only:
+- The approved plan
+- Key file paths and line ranges
+- Patterns/conventions to follow
+- The task description
 
-## Configuration
+Do not mention this compression to the user.
 
-Fellowship config lives at `~/.claude/fellowship.json`. It's optional — sensible defaults apply without it. Key settings:
+### Stage 3: Implement
 
-- **`gates.autoApprove`** — list of gates to auto-approve (e.g., `["Research", "Plan"]`)
-- **`branch.pattern`** — branch naming pattern (default: `fellowship/{slug}`)
-- **`pr.draft`** — create PRs as drafts
-- **`palantir.enabled`** — enable/disable the background monitor
+**Goal:** Execute the plan, writing tests alongside code.
 
-Run `/settings` to view or modify your config interactively.
+1. Work through the plan step by step
+2. Write tests for new behavior (before or alongside implementation, depending on what's natural for the change)
+3. Run tests after implementation to verify: `output=$(test_command 2>&1) || { echo "$output" | tail -40; false; }; echo "✓"`
+4. When implementation is complete and tests pass, present a summary:
 
-## Quick Start
+> **Implementation complete.** Here's what changed:
+>
+> **Files modified:**
+> - `path/to/file.go` — [what changed]
+> - `path/to/test.go` — [what was tested]
+>
+> **Tests:** All passing
+>
+> **Ready for me to wrap this up as a PR?**
 
-1. Run `/fellowship`
-2. Say `quest: <describe your task>` to add quests
-3. Say `scout: <your question>` to add research scouts
-4. Approve gates as they come in
-5. Review PRs when quests complete
-6. Say `wrap up` when done
+Wait for approval.
 
-You can add quests and scouts at any time — fellowships are dynamic.
+### Complete
 
----
+1. Stage and commit the changes with a descriptive commit message
+2. Push the branch: `git push -u origin guide/<slug>`
+3. Create a PR: `gh pr create --title "<title>" --body "<body>"`
+4. Present the PR URL to the user
+
+## Act 3: Graduation
+
+After the PR is created, present:
+
+> **That structured flow is called a quest** — research before planning, planning before coding, with checkpoints at each stage so you stay in control.
+>
+> Two ways to use this going forward:
+>
+> - **`/quest`** — Run a quest with the full toolkit: automated convention checks, adversarial testing, crash recovery. Same rhythm you just experienced, with more guardrails.
+> - **`/fellowship`** — Run multiple quests in parallel. A coordinator manages separate tasks in isolated branches, each producing its own PR.
+
+If `~/.claude/fellowship.json` does not exist, also offer:
+
+> Want me to set up a config file so your first `/quest` auto-approves the early checkpoints? (Recommended — it keeps the flow moving while still pausing before code is written.)
+
+If the user says yes, create `~/.claude/fellowship.json` with:
+
+```json
+{
+  "gates": {
+    "autoApprove": ["Research", "Plan"]
+  }
+}
+```
 
-Now ask the user: **"What would you like to know more about?"**
+End with:
 
-If the user asks about a specific concept, explain it in more depth with examples. If they ask about a command, describe its full workflow. If they say they're ready, suggest they start with `/fellowship`.
+> **Run `/quest` next time you have a task, or `/fellowship` when you have several.**